scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-02 03:27:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

website: a lot more concepts

Browse Source
This commit is contained in:
Mitchell Hashimoto
2015-04-17 17:18:20 -07:00
parent 4316b1b88c
commit 4e56567d6e
4 changed files with 262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
website/source/docs/concepts/auth.html.md Normal file
View File

@@ -0,0 +1,99 @@
---
layout: "docs"
page_title: "Authentication"
sidebar_current: "docs-concepts-auth"
description: |-
Before performing any operation with Vault, the connecting client must be authenticated.
---
# Authentication
Before performing any operation with Vault, the connecting client must be
_authenticated_. Authentication is the process of verifying a person or
machine is who they say they are and assigning an identity to them. This
identity is then used when making requests with Vault.
Authentication in Vault is pluggable via authentication backends. This
allows you to authenticate with Vault using a method that works best for your
organization. For example, you can authenticate using GitHub, certs, etc.
## Authentication Backends
There are many authentication backends available for Vault. They
are enabled using `vault auth-enable`. After they're enabled, you can
learn more about them using `vault help auth/<name>`. For example,
if you enable GitHub, you can use `vault help auth/github` to learn more
about how to configure it and login.
Multiple authentication backends can be enabled, but only one is required
to gain authentication. It is not currently possible to force a user through
multiple authentication backends to gain access.
This allows you to enable human-friendly as well as machine-friendly
backends at the same time. For example, for humans you might use the
"github" auth backend, and for machines you might use the "app-id" backend.
## Tokens
There is an [entire page dedicated to tokens](/docs/concepts/tokens.html),
but it is important to understand that authentication works by verifying
your identity and then generating a token to associate with that identity.
For example, even though you may authenticate using something like GitHub,
Vault generates a unique access token for you to use for future requests.
The CLI automatically attaches this token to requests, but if you're using
the API you'll have to do this manually.
This token given for authentication with any backend can also be used
with the full set of token commands, such as creating new sub-tokens,
revoking tokens, and renewing tokens. This is all covered on the
[token concepts page](/docs/concepts/tokens.html).
## Authenticating
#### Via the CLI
To authenticate with the CLI, `vault auth` is used. This supports many
of the built-in authentication methods. For example, with GitHub:
```
$ vault auth -method=github token=<token>
...
```
After authenticating, you will be logged in. The CLI command will also
output your raw token. This token is used for revocation and renewal.
As the user logging in, the primary use case of the token is renewal,
covered below in the "Auth Leases" section.
To determine what variables are needed for an authentication method,
supply the `-method` flag without any additional arguments and help
will be shown.
If you're using a method that isn't supported via the CLI, then the API
must be used.
#### Via the API
API authentication is generally used for machine authentication. Each
auth backend implements is own login endpoint. Use the `vault help`
mechanism to find the proper endpoint.
For example, the GitHub login endpoint is located at `auth/github/login`.
And to determine the arguments needed, `vault help auth/github/login` can
be used.
## Auth Leases
Just like secrets, identities have
[leases](/docs/concepts/lease.html) associated with them. This means that
you must reauthenticate after the given lease period to continue accessing
Vault.
To set the lease associated with an identity, reference the help for
the specific authentication backend in use. It is specific to each backend
how leasing is implemented.
And just like secrets, identities can be renewed without having to
completely reauthenticate. Just use `vault token-renew <token>` with the
token associated with your identity to renew it.

93
website/source/docs/concepts/policies.html.md Normal file
View File

@@ -0,0 +1,93 @@
---
layout: "docs"
page_title: "Policies"
sidebar_current: "docs-concepts-policies"
description: |-
Policies are how authorization is done in Vault, allowing you to restrict which parts of Vault a user can access.
---
# Access Control Policies
After [authenticating](/docs/concepts/auth.html) with Vault, the
next step is authorization. This is the process of determining what
a user is allowed to do. Authorization is unified in Vault in the form
of _policies_.
Policies are [HCL](https://github.com/hashicorp/hcl) or JSON documents
that describe what parts of Vault a user is allowed to access. An example
of a policy is shown below:
```
path "sys" {
policy = "deny"
}
path "secret" {
policy = "write"
}
path "secret/foo" {
policy = "read"
}
```
Policies use prefix-based routing to apply rules. They are deny by default,
so if a path isn't explicitly given, Vault will reject any access to it.
This works well due to Vault's architecture of being like a filesystem:
everything has a path associated with it, including the core configuration
mechanism under "sys".
## Policies
Allowed policies for a path are:
* `write` - Read, write access to a path.
* `read` - Read-only access to a path.
* `deny` - No access allowed.
* `sudo` - Read, write, and root access to a path.
The only non-obvious policy is "sudo". Some routes within Vault and mounted
backends are marked as _root_ paths. Clients aren't allowed to access root
paths unless they are a root user (have the special policy "root") or
have access to that path with the "sudo" policy.
For example, modifying the audit log backends is done via root paths.
Only root or "sudo" privilege users are allowed to do this.
## Root Policy
The "root" policy is special policy that can'be modified or removed.
Any user associated with the "root" policy becomes a root user. A root
user can do _anything_ within Vault.
There always exists at least one root user (associated with the token
when initializing a new server). After this root user, it is recommended
to create more strictly controlled users. The original root token should
be protected accordingly.
## Managing Policies
Policy management can be done via the API or CLI. The CLI commands are
`vault policies` and `vault policy-write`. Please see the help associated
with these commands for more information. They are very easy to use.
## Associating Policies
To associate a policy with a user, you must consult the documentation for
the authentication backend you're using.
For tokens, they are assocated at creation time with `vault token-create`
and the `-policy` flags. Child tokens can be associated with a subset of
a parent's policies. Root users can assign any policies.
There is no way to modify the policies associated with an active
identity. The identity must be revoked and reauthenticated to receive
the new policy list.
If an _existing_ policy is modified, the modifications propogate
to all associated users instantly. The above paragraph is more specifically
stating that you can't add new or remove policies associated with an
active identity.

58
website/source/docs/concepts/tokens.html.md Normal file
View File

@@ -0,0 +1,58 @@
---
layout: "docs"
page_title: "Tokens"
sidebar_current: "docs-concepts-tokens"
description: |-
Tokens are a core authentication method in Vault. Child tokens, token-based revocation, and more.
---
# Tokens
Tokens are the core method for _authentication_ within Vault. Tokens
can be used directly or [authentication backends](/docs/concepts/auth.html)
can be used to dynamically generate tokens based on external identities.
If you've gone through the getting started guide, you probably noticed that
`vault server -dev` (or `vault init` for a non-dev server) outputs an
initial "root token." This is the first method of authentication for Vault.
It is also the only authentication backend that cannot be disabled.
As stated in the [authentication concepts](/docs/concepts/auth.html),
all external authentication mechanisms such as GitHub map down to dynamically
created tokens. These tokens have all the same properties as a normal
manually created token.
On this page, we'll show you how to create and manage tokens.
## Token Creation
Tokens are created via the API or using `vault token-create` from the CLI.
This will create a new token that is a child of the currently authenticated
token. As a child, the new token will automatically be revoked if the parent
is revoked.
If you're logged in as root, you can create an _orphan_ token by
specifying the `-orphan` flag. An orphan token has no parent, and therefore
when your token is revoked, it will not revoke the orphan.
Metadata associated with the token with `-metadata` is used to annotate
the token with information that is added to the audit log.
Finally, the `-policy` flag can be used to set the policies associated
with the token. Learn more about policies on the
[policies concepts](/docs/concepts/policies.html) page.
## Token Leases
Every token has a lease associated with it. These leases behave in much
the same way as [leases for secrets](/docs/concepts/lease.html). After
the lease period is up, the token will no longer function. In addition
to no longer functioning, Vault will revoke it.
In order to avoid your token being revoked, the `vault token-renew`
command should be used to renew the lease on the token periodically.
After a token is revoked, all of the secrets in use by that token will
also be revoked. Therefore, if a user requests AWS access keys, for example,
then after the token expires the AWS access keys will also be expired even
if they had remaining lease time.

12
website/source/layouts/docs.erb
View File

@@ -46,6 +46,18 @@
<a href="/docs/concepts/lease.html">Lease, Renew, and Revoke</a>
</li>
<li<%= sidebar_current("docs-concepts-auth") %>>
<a href="/docs/concepts/auth.html">Authentication</a>
</li>
<li<%= sidebar_current("docs-concepts-tokens") %>>
<a href="/docs/concepts/tokens.html">Tokens</a>
</li>
<li<%= sidebar_current("docs-concepts-policies") %>>
<a href="/docs/concepts/policies.html">Access Control Policies</a>
</li>
<li<%= sidebar_current("docs-concepts-ha") %>>
<a href="/docs/concepts/ha.html">High Availability</a>
</li>