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 have not "logged in"
to Vault. When starting the Vault server in
dev mode, it automatically logs
you in as the root user with admin permissions. In a non-dev setup, you would
have had to authenticate first.
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 auth methods, making it easy to authenticate with Vault using whatever form works best for your organization. On this page we will use the token auth method and the GitHub auth method.
Authentication is the process by which user or machine-supplied information is verified and converted into a Vault token with matching policies attached. The easiest way to think about Vault's authentication is to compare it to a website.
When a user authenticates to a website, they enter their username, password, and maybe 2FA code. That information is verified against external sources (a database most likely), and the website responds with a success or failure. On success, the website also returns a signed cookie that contains a session id which uniquely identifies that user for this session. That cookie and session id are automatically carried by the browser to future requests so the user is authenticated. Can you imagine how terrible it would be to require a user to enter their login credentials on each page?
Vault behaves very similarly, but it is much more flexible and pluggable than a standard website. Vault supports many different authentication mechanisms, but they all funnel into a single "session token", which we call the "Vault token".
Authentication is simply the process by which a user or machine gets a Vault token.
Token authentication is enabled by default in Vault and cannot be disabled. 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.
You can create more tokens:
$ vault token create Key Value --- ----- token 463763ae-0c3b-ff77-e137-af668941465c token_accessor 57b6b540-57c8-64c4-e9c6-0b18ab058144 token_duration ∞ token_renewable false token_policies [root]
By default, this will create a child token of your current token that inherits all the same 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:
$ vault token revoke 463763ae-0c3b-ff77-e137-af668941465c Success! Revoked token (if it existed)
In a previous section, we use the
vault lease revoke command. This command
is only used for revoking leases. For revoking tokens, use
vault token revoke.
To authenticate with a token:
$ vault login a402d075-6d59-6129-1ac7-3718796d4346 Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. Key Value --- ----- token a402d075-6d59-6129-1ac7-3718796d4346 token_accessor 7636b2f8-0cf1-e110-9b18-8f8b5ecf8351 token_duration ∞ token_renewable false token_policies [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 the
login command, create a new token first.
» Best Practice
In practice, operators should not use the
token create command to generate
Vault tokens for users or machines. Instead, those users or machines should
authenticate to Vault using any of Vault's configured auth methods such as
GitHub, LDAP, AppRole, etc. For legacy applications which cannot generate their
own token, operators may need to create a token in advance. Auth methods are
discussed in more detail in the next section.
» Auth Methods
Vault supports many auth methods, but they must be enabled before use. Auth methods give you flexibility. Enabling and configuration are typically performed by a Vault operator or security team. As an example of a human-focused auth method, let's authenticate via GitHub.
First, enable the GitHub auth method:
$ vault auth enable -path=github github Success! Enabled github auth method at: github/
Just like secrets engines, auth methods default to their TYPE as the PATH, so the following commands are equivalent:
$ vault auth enable -path=github github $ vault auth enable github
Unlike secrets engines which are enabled at the root router, auth methods are
always prefixed with
auth/ in their path. So the GitHub auth method we just
enabled is accessible at
auth/github. As another example:
$ vault auth enable -path=my-github github Success! Enabled github auth method at: my-github/
This would make the GitHub auth method accessible at
auth/my-github. You can
vault path-help to learn more about the paths.
Next, configure the GitHub auth method. Each auth method has different configuration options, so please see the documentation for the full details. In this case, the minimal set of configuration is to map teams to policies.
$ vault write auth/github/config organization=hashicorp
With the GitHub auth method 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/my-team value=default,my-policy Success! Data written to: auth/github/map/teams/my-team
The first command configures Vault to pull authentication data from the "hashicorp" organization on GitHub. The next command tells Vault to map any users who are members of the team "my-team" (in the hashicorp organization) to map to the policies "default" and "my-policy". These policies do not have to exist in the system yet - Vault will just produce a warning when we login.
As a user, you may want to find which auth methods are enabled and available:
$ vault auth list Path Type Description ---- ---- ----------- github/ github n/a token/ token token based credentials
vault auth list command will list all enabled auth methods. To learn more
about how to authenticate to a particular auth method via the CLI, use the
vault auth help command with the PATH or TYPE of an auth method:
$ vault auth help github Usage: vault login -method=github [CONFIG K=V...] The GitHub auth method allows users to authenticate using a GitHub personal access token. Users can generate a personal access token from the settings page on their GitHub account. Authenticate using a GitHub token: $ vault login -method=github token=abcd1234 Configuration: mount=<string> Path where the GitHub credential method is mounted. This is usually provided via the -path flag in the "vault login" command, but it can be specified here as well. If specified here, it takes precedence over the value for -path. The default value is "github". token=<string> GitHub personal access token to use for authentication.
Similarly, you can ask for help information about any CLI auth method, even if it is not enabled:
$ vault auth help aws $ vault auth help userpass $ vault auth help token
As per the help output, authenticate to GitHub using the
vault login command.
Enter your GitHub personal access token and Vault will authenticate
$ vault login -method=github GitHub Personal Access Token (will be hidden): Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token. Key Value --- ----- token 7efb3969-8743-880f-e234-afca6e12d790 token_accessor f7bfb6a3-c41e-eb87-5317-88a0aad200ae token_duration 768h token_renewable true token_policies [default my-policy] token_meta_org hashicorp token_meta_username my-user
Success! As the output indicates, Vault has already saved the resulting token in
its token helper, so you do not need to run
vault login again. However, this
new user we just created does not have many permissions in Vault. To continue,
re-authenticate as the root token:
$ vault login <initial-root-token>
You can revoke any logins from an auth method using
vault token revoke with
-mode argument. For example:
$ vault token revoke -mode path auth/github
Alternatively, if you want to completely disable the GitHub auth method:
$ vault auth disable github Success! Disabled the auth method (if it existed) at: github/
This will also revoke any logins for that auth method.
In this page you learned about how Vault authenticates users. You learned about the built-in token system as well as enabling other auth methods. At this point you know how Vault assigns an identity to a user.
The multiple auth methods Vault provides let you choose the most appropriate authentication mechanism for your organization.
In this next section, we'll learn about authorization and policies.