open-vault/website/source/intro/getting-started/authentication.html.md

layout	page_title	sidebar_title	sidebar_current	description
intro	Authentication - Getting Started	Authentication	gettingstarted-auth	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 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.

Background

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.

Tokens

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 vault 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 use 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

The 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 you.

$ 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 the -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.

Next

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.