173 lines
6.3 KiB
Markdown
173 lines
6.3 KiB
Markdown
---
|
|
layout: "intro"
|
|
page_title: "Authentication"
|
|
sidebar_current: "gettingstarted-auth"
|
|
description: |-
|
|
Authentication to Vault gives a user access to use Vault. Vault can authenticate using multiple methods.
|
|
---
|
|
|
|
# Authentication
|
|
|
|
Now that we know how to use the basics of Vault, it is important to understand
|
|
how to authenticate to Vault itself. Up to this point, we haven't had to
|
|
authenticate because starting the Vault server in dev mode automatically logs
|
|
us in as root. In practice, you'll almost always have to manually authenticate.
|
|
|
|
On this page, we'll talk specifically about _authentication_. On the next
|
|
page, we talk about _authorization_.
|
|
Authentication is the mechanism of assigning an identity to a Vault user.
|
|
The access control and permissions associated with an identity are
|
|
authorization, and will not be covered on this page.
|
|
|
|
Vault has pluggable authentication backends, making it easy to authenticate
|
|
with Vault using whatever form works best for your organization. On this page
|
|
we'll use the token backend as well as the GitHub backend.
|
|
|
|
## Tokens
|
|
|
|
We'll first explain token authentication before going over any other
|
|
authentication backends. Token authentication is enabled by default in
|
|
Vault and cannot be disabled. It is also what we've been using up to this
|
|
point.
|
|
|
|
When you start a dev server with `vault server -dev`, it outputs your
|
|
_root token_. The root token is the initial access token to configure Vault.
|
|
It has root privileges, so it can perform any operation within Vault.
|
|
We'll cover how to limit privileges in the next section.
|
|
|
|
You can create more tokens using `vault token-create`:
|
|
|
|
```
|
|
$ vault token-create
|
|
Key Value
|
|
token c2c2fbd5-2893-b385-6fa5-30050439f698
|
|
token_accessor 0c1c3317-3d58-17e5-c1a9-3f54fa26610e
|
|
token_duration 0
|
|
token_renewable true
|
|
token_policies [root]
|
|
```
|
|
|
|
By default, this will create a child token of your current token that
|
|
inherits all the same access control policies. The "child" concept here
|
|
is important: tokens always have a parent, and when that parent token is
|
|
revoked, children can also be revoked all in one operation. This makes it
|
|
easy when removing access for a user, to remove access for all sub-tokens
|
|
that user created as well.
|
|
|
|
After a token is created, you can revoke it with `vault token-revoke`:
|
|
|
|
```
|
|
$ vault token-revoke c2c2fbd5-2893-b385-6fa5-30050439f698
|
|
Revocation successful.
|
|
```
|
|
|
|
In a previous section, we use the `vault revoke` command. This command
|
|
is only used for revoking _secrets_. For revoking _tokens_, the
|
|
`vault token-revoke` command must be used.
|
|
|
|
To authenticate with a token, use the `vault auth` command:
|
|
|
|
```
|
|
$ vault auth d08e2bd5-ffb0-440d-6486-b8f650ec8c0c
|
|
Successfully authenticated! The policies that are associated
|
|
with this token are listed below:
|
|
|
|
root
|
|
```
|
|
|
|
This authenticates with Vault. It will verify your token and let you know
|
|
what access policies the token is associated with. If you want to test
|
|
`vault auth`, make sure you create a new token first.
|
|
|
|
## Auth Backends
|
|
|
|
In addition to tokens, other authentication backends can be enabled.
|
|
Authentication backends enable alternate methods of identifying with Vault.
|
|
These identities are tied back to a set of access policies, just like tokens.
|
|
|
|
Vault supports other authentication backends in order to make authentication
|
|
easiest for your environment. For example, for desktop environments,
|
|
private key or GitHub based authentication may be easiest. For server
|
|
environments, some shared secret may be best. Auth backends give you
|
|
flexibility to choose what authentication you want to use.
|
|
|
|
As an example, let's authenticate using GitHub. First, enable the
|
|
GitHub authentication backend:
|
|
|
|
```
|
|
$ vault auth-enable github
|
|
Successfully enabled 'github' at 'github'!
|
|
```
|
|
|
|
Auth backends are mounted, just like secret backends, except auth
|
|
backends are always prefixed with `auth/`. So the GitHub backend we just
|
|
mounted can be accessed at `auth/github`. You can use `vault path-help` to
|
|
learn more about it.
|
|
|
|
With the backend enabled, we first have to configure it. For GitHub,
|
|
we tell it what organization users must be a part of, and map a team to a policy:
|
|
|
|
```
|
|
$ vault write auth/github/config organization=hashicorp
|
|
Success! Data written to: auth/github/config
|
|
|
|
$ vault write auth/github/map/teams/default value=root
|
|
Success! Data written to: auth/github/map/teams/default
|
|
```
|
|
|
|
The above configured our GitHub backend to only accept users from the
|
|
"hashicorp" organization (you should fill in your own organization)
|
|
and to map any team to the "root" policy, which is the only policy we have
|
|
right now until the next section.
|
|
|
|
With GitHub enabled, we can authenticate using `vault auth`:
|
|
|
|
```
|
|
$ vault auth -method=github token=e6919b17dd654f2b64e67b6369d61cddc0bcc7d5
|
|
Successfully authenticated! The policies that are associated
|
|
with this token are listed below:
|
|
|
|
root
|
|
```
|
|
|
|
Success! We've authenticated using GitHub. The "root" policy was associated
|
|
with my identity since we mapped that earlier. The value for "token" should be your own
|
|
[personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
|
|
|
|
You can revoke authentication from any authentication backend using
|
|
`vault token-revoke` as well, which can revoke any path prefix. For
|
|
example, to revoke all GitHub tokens, you could run the following.
|
|
**Don't run this unless you have access to another root token or you'll
|
|
get locked out.**
|
|
|
|
```
|
|
$ vault token-revoke -mode=path auth/github
|
|
```
|
|
|
|
When you're done, you can disable authentication backends with
|
|
`vault auth-disable`. This will immediately invalidate all authenticated
|
|
users from this backend.
|
|
|
|
```
|
|
$ vault auth-disable github
|
|
Disabled auth provider at path 'github'!
|
|
```
|
|
|
|
If you ran the above, you'll probably find you can't access your Vault
|
|
anymore unless you have another root token, since it invalidated your
|
|
own session since we authenticated with GitHub above. Since we're still
|
|
operating in development mode, just restart the dev server to fix this.
|
|
|
|
## Next
|
|
|
|
In this page you learned about how Vault authenticates users. You learned
|
|
about the built-in token system as well as enabling other authentication
|
|
backends. At this point you know how Vault assigns an _identity_ to
|
|
a user.
|
|
|
|
The multiple authentication backends Vault provides let you choose the
|
|
most appropriate authentication mechanism for your organization.
|
|
|
|
In this next section, we'll learn about
|
|
[access control policies](/intro/getting-started/acl.html).
|