Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

Getting Started

Authentication

You created your first secret, learned about secrets engines and explored dynamic secrets with the Vault server you started in development mode.

In this tutorial, you will explore authentication with Vault tokens and GitHub credentials.

»Token authentication

Token authentication is automatically enabled. When you started the dev server, the output displayed a root token. The Vault CLI read the root token from the $VAULT_TOKEN environment variable. This root token can perform any operation within Vault because it is assigned the root policy. One capability is to create new tokens.

Create a new token.

$ vault token create
Key                  Value
---                  -----
token                s.iyNUhq8Ov4hIAx6snw5mB2nL
token_accessor       maMfHsZfwLB6fi18Zenj3qh6
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

The token is created and the output describes this token a table of keys and values. The created token is displayed here as s.iyNUhq8Ov4hIAx6snw5mB2nL.

This token is a child of the root token, and by default, it inherits the policies from its parent.

Login with this new token.

$ vault login s.iyNUhq8Ov4hIAx6snw5mB2nL

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                s.iyNUhq8Ov4hIAx6snw5mB2nL
token_accessor       maMfHsZfwLB6fi18Zenj3qh6
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

You successfully authenticated with this new token. As this token has the root policy it can create its own tokens.

Create another token.

$ vault token create

Key                  Value
---                  -----
token                s.TsKT5ubouZ7TF26Eg7wNIl3k
token_accessor       b1d0curWHYqmgCndk0G1cM6R
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

The token is created and displayed here as s.TsKT5ubouZ7TF26Eg7wNIl3k. Each token that Vault creates is unique.

When a token is no longer needed it can be revoked.

Revoke the first token you created.

$ vault token revoke s.iyNUhq8Ov4hIAx6snw5mB2nL

Success! Revoked token (if it existed)

The token has been revoked.

Attempt to login with the last token you created.

$ vault login s.TsKT5ubouZ7TF26Eg7wNIl3k
Error authenticating: error looking up token: Error making API request.

URL: GET http://127.0.0.1:8200/v1/auth/token/lookup-self
Code: 403. Errors:

* permission denied

You are not able to authenticate with this token because when a token is revoked it will revoke all the tokens that it created.

Login with the root token.

$ vault login $VAULT_TOKEN

You successfully authenticated again with the root token.

»GitHub authentication

Vault supports authentication methods for human operators. GitHub authentication enables a user to authenticate with Vault by providing their GitHub credentials and receive a Vault token.

Enable the GitHub auth method.

$ vault auth enable github

Success! Enabled github auth method at: github/

The auth method is enabled and available at the path auth/github/.

This auth method requires that you set a GitHub organization in the configuration. A GitHub organization maintains a list of users which you are allowing to authenticate with Vault.

Set the organization for the github authentication.

$ vault write auth/github/config organization=hashicorp

Success! Data written to: auth/github/config

Now all users within the hashicorp GitHub organization are able to authenticate.

GitHub organizations can define teams. Each team may have access to different actions across all the repositories that the organization maintains. These teams may also need access to specific secrets within Vault.

Configure the GitHub engineering team authentication to be granted the default and applications policies.

$ vault write auth/github/map/teams/engineering value=default,applications

Success! Data written to: auth/github/map/teams/engineering

The members of the GitHub engineering team in the hashicorp organization will authenticate and are authorized with the default and applications policies.

Display all the authentication methods that Vault has enabled.

$ vault auth list

Path       Type      Description
----       ----      -----------
github/    github    n/a
token/     token     token based credentials

The output displays the github and token auth methods.

Learn more about the github auth method using help.

$ 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

## ...

The output displays an example of login with the github method. This method requires that the method be defined and that an operator provide a GitHub personal access token.

Attempt to login with the github auth method.

$ 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                  s.DNtKCjVQ1TxAzgMqtDuwjjC2
token_accessor         e7zLJuPg2tLpav66ZSu5AyDC
token_duration         768h
token_renewable        true
token_policies         [default applications]
token_meta_org         hashicorp
token_meta_username    my-user

When the GitHub personal access token is not provided to the command the Vault CLI prompts the operator. If a valid GitHub personal access token is provided then the operator logs in and the output displays a Vault token. The operator can use the Vault token until it is revoked or its lifetime exceeds the token_duration

Login with the root token.

$ vault login $VAULT_TOKEN

Revoke all tokens generated the github auth method.

$ vault token revoke -mode path auth/github

All tokens generated by logins to the path auth/github are revoked.

All authentication methods, except for the token auth method, can be disabled.

Display the github auth method.

$ vault auth disable github

Success! Disabled the auth method (if it existed) at: github/

All tokens generated by logins using this authentication method are revoked.

»Next

In this tutorial you learned how users can authenticate with Vault tokens and the GitHub authentication method. Vault provides a variety of authentication methods for the human operators and machines.

Next, you will learn about authorization and how to define policies.