--- layout: "intro" page_title: "Authentication - Getting Started" sidebar_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 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](/intro/getting-started/policies.html). 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: ```text $ 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: ```text $ vault token revoke 463763ae-0c3b-ff77-e137-af668941465c Success! Revoked token (if it existed) ``` In a [previous section](/intro/getting-started/dynamic-secrets.html#revoking-the-secret), 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: ```text $ 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: ```text $ 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: ```text $ 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: ```text $ 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. ```text $ 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: ```text $ 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: ```text $ 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: ```text $ 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= 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= 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_: ```text $ 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][gh-pat] and Vault will authenticate you. ```text $ 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: ```text $ vault login ``` You can revoke any logins from an auth method using `vault token revoke` with the `-mode` argument. For example: ```text $ vault token revoke -mode path auth/github ``` Alternatively, if you want to completely disable the GitHub auth method: ```text $ 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](/intro/getting-started/policies.html). [gh-pat]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/