Authentication for people

Authentication in Vault is the process by which user- or machine-supplied information is verified against an internal or external system. Vault supports multiple auth methods(opens in new tab) including LDAP, OIDC, and more. Each auth method has a specific use case. In this section, you will configure your first auth method to allow human users to login to Vault.

Clients must authenticate against an auth method to interact with Vault. After successful authentication, a token is returned to the client. The token is associated with policies which control the resources and operations that the client can access.

The mapping between the token and policy is configured in the auth method. This process is described in detail in the policies concepts(opens in new tab) documentation.

Figure 1: Vault's authentication workflow

The token auth method(opens in new tab) is built-in and is at the core of client authentication. A client can authenticate with Vault through the token auth method. For example, a Vault admin logs in with Vault via token auth method using the initial root token(opens in new tab) (or admin token if you are running HCP Vault) so that the admin can configure other auth methods.

Configure admin policy

Policies form the basis of the role-based access control (RBAC) system for Vault. Logical operations in Vault are path-based, and policies provide a declarative way to grant or forbid access to certain paths and operations in Vault. If you are not familiar with the concept of Vault policies, we strongly encourage you to review the policies concept(opens in new tab) documentation and the getting started guide to policy writing(opens in new tab).

The first group of users to grant access to Vault are your operators who have full access to Vault. They are responsible for cluster level configurations and any requests to the restricted API(opens in new tab) that requires the root namespace. By default Vault does not include any administrative policies. In a new Vault installation, there is only a default policy that does not grant access to any functional resources in Vault. You will need to create an appropriate operator policy for this subset of users. Below is an example.

# * (glob) character matches any prefixes in the path and can only be used at the end
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Login to Vault using your root token and run the command below to create an operator policy under the root namespace.

$ export VAULT_TOKEN=<your root token>
$ vault policy write operator operator-policy.hcl
 
Success! Uploaded policy: operator

The second group of users to grant access to Vault are your tenant administrators. Tenant administrators are responsible for day to day Vault operations for their Vault tenant (a parent namespace and a number of subordinate application/environment namespaces). They only have access to their tenant namespace and below and do not have access to the root namespace. The paths that the tenant administrators can access are governed by the tenant admin policy. Below is an example of such a policy.

# List existing policies
path "sys/policies/acl"
{
  capabilities = ["list"]
}
 
# Create and manage ACL policies
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
# Manage auth methods broadly across Vault
path "auth/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
 
# Create, update, and delete auth methods
path "sys/auth/*"
{
  capabilities = ["create", "update", "delete", "sudo"]
}
 
# List auth methods
path "sys/auth"
{
  capabilities = ["read"]
}
 
# Managing identity
path "identity/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
# Enable and manage the key/value secrets engine at `secret/` path
path "secret/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
# Allow managing leases
path "sys/leases/*"
{
  capabilities = ["read", "update", "list"]
}
 
# Manage namespaces
path "sys/namespaces/*" {
   capabilities = ["create", "read", "update", "delete", "list"]
}
 
# Manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
# List existing secrets engines.
path "sys/mounts"
{
  capabilities = ["read"]
}
 
# Configure License
path "sys/license"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}
 
# Configure Vault UI
path "sys/config/ui"
{
  capabilities = ["read", "update", "delete", "list"]
}

This example policy is only a subset of Vault's API(opens in new tab). If additional administrative capabilities are necessary, edit the admin policy when the need arises.

Login to Vault using your root token and run the commands below to create an admin policy under the org-level namespace.

$ export VAULT_NAMESPACE=<org level namespace>
$ vault policy write admin admin-policy.hcl
 
Success! Uploaded policy: admin

Configure the first auth method

With the admin policies created, you are ready to configure your first auth method to allow your Vault super administrators to login.

There are many auth methods(opens in new tab) available in Vault, some auth methods are targeted towards human users while others are targeted towards machines. Which auth methods you enable depends on the type of clients (human or machine), and the existing processes and systems in place for identity management. For example, if an organization uses Microsoft Active Directory for user identity management, then it makes sense to enable the LDAP auth method for user authentication.

Depending on the use case, multiple auth methods can be enabled in Vault to provide access to the same data. For the initial configuration, you will enable one auth method for the operators in the root namespace and one auth method for all other users in the tenant admin namespaces.

For human user access, if your organization already has a user authentication system tied into the user lifecycle and Vault supports it (e.g. OIDC, LDAP), you should consider using this as an auth method. In this case, you only have one place to manage your users, and users are less likely to get stranded in Vault either in a group they have moved from or as a legacy user that no longer works in the organization.

Certain auth methods are more popular due to the widespread use of their associated technologies in modern organizations. This section focuses on the following common auth methods for human user access and how to use them.

• OIDC
• LDAP

OIDC auth method

The OIDC auth method allows authentication via a configured identity provider such as Okta or Azure AD, providing a single sign-on experience to Vault services. Authentication requests can be initiated using the Vault UI, CLI, or the API. The OIDC auth method allows a user's browser to be redirected to a configured identity provider, complete login, and then be routed back to Vault's UI with a newly-created Vault token. This workflow is depicted in Figure 2.

Figure 2: OIDC Auth Workflow

1. User requests authentication using the OIDC auth method via Vault's UI or CLI.
2. Vault launches a browser to the configured discovery URL for the OIDC provider.
3. User submits credentials to the OIDC provider.
4. OIDC provider validates credentials and returns an OAuth token to Vault. The OAuth token contains information about the user such as security groups that the user is a member of, which could map to an identity group within Vault.
5. Vault maps the security group claims in the OAuth token to pre-configured identity groups within Vault, which is attached to Vault policies.
6. Vault attaches policies associated with the identity groups to a Vault token.
7. A Vault token is returned.

Configuring OIDC auth method

The steps outlined below are the general workflow for configuring an OIDC auth method. You should perform these steps first in the root namespace for your Vault operators, then configure another OIDC auth method or a different human auth method in the org level namespace for tenant administrators and all other users. The code snippets in these steps will highlight distinctions between the configuration in the root namespace versus the org level namespace.

Step 1: Enable the auth method

Before you can use an auth method in Vault, you must enable it. You can enable and configure the auth method using the UI, CLI, or the API. We will focus on CLI commands in this document.

Configuration for root namespace

Using the Vault CLI, log in to Vault with your root token and enable the OIDC auth method under the root namespace using the code snippet below.

$ vault auth enable oidc

Configuration for tenant namespaces

Using the Vault CLI, log in to Vault with your root token and enable the OIDC auth method under the tenant level namespace using the code snippet below.

$ export VAULT_NAMESPACE=<org level namespace>
$ vault auth enable oidc

Step 2: Configure the auth method

Once the OIDC auth method has been enabled, you are now ready to configure the auth method itself. Vault needs to know how to connect to your identity provider and what credentials it should use. These settings include the oidc_discovery_url, oidc_client_id, and the oidc_client_secret. You can find more details about these settings in the JWT/OIDC auth method API(opens in new tab). Your Vault nodes will need the ability to connect to the specified oidc_discovery_url typically over TCP port 443 (HTTPS) to retrieve OIDC metadata. You must also provide a default Vault role name as part of the configuration. The role does not have to exist at this stage as it will be created in the next step.

Configure the OIDC auth method using the CLI command below. Set the oidc_discovery_ca_pem parameter to point to the CA certificate used to validate the connections to the OIDC discovery URL. If not set, the system certificates will be used.

$ vault write auth/oidc/config \
    oidc_discovery_url="https://sso.example.com" \
    oidc_client_id="vault" \
    oidc_client_secret="passw0rd" \
    oidc_discovery_ca_pem=@ca.pem \
    default_role="default"

Step 3: Create the default role

With the OIDC auth method configured, you can now create the default role named in the previous step.

Multiple roles can be created under a single auth method. Each role can be associated with different Vault policies, granting multiple levels of access. The default role created in this step is only used when the user does not specify a role during authentication.

The role contains information that Vault uses to uniquely identify users and the groups to which they are a member of, using claims within the OAuth token sent by the identity provider. The role also specifies which Vault policies should be attached to the tokens issued by this role when a user's OAuth token matches the claims defined within the role. The default role is commonly associated with Vault's default policy(opens in new tab), which is a built-in policy that cannot be removed and provides a set of limited capabilities. Below is an example CLI command to create the default role.

$ vault write auth/oidc/role/default -<<EOF
{
 "user_claim": "email",
 "groups_claim": "groups",
 "allowed_redirect_uris": [ "https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback", "https://vault.example.com:8250/oidc/callback" ],
 "token_policies": "default",
 "token_ttl": "1h",
 "token_max_ttl": "1h"
}
EOF

The user_claim parameter is the claim in the OAuth token used to uniquely identify the user. This will be used as the name for the identity entity alias created due to a successful login. The identity entity alias is a representation of a client for a specific auth method within Vault's identity system. Please refer to the Identity Secrets Engine(opens in new tab) documentation for more information.

The group_claim parameter is an optional field containing the claim used to uniquely identify the set of groups to which the user belongs. Vault will attempt to match the value from this claim to an external group(opens in new tab) created within Vault. If a match is found, Vault will add the entity to the external group as a member.

The allowed_redirect_uris is a list of allowed values where users are redirected after authenticating with the OIDC provider. The URI with port 8200 is for login via the UI whereas the URI with port 8250 is for login via the CLI. These URIs must match the configuration on the OIDC provider configuration.

The token_policies is the list of Vault policies that would be attached to the token upon a successful login.

The token_ttl is the duration of time before the generated token expires if not renewed. The format of this parameter follows the duration string format(opens in new tab). We recommend that you always provide a token TTL value to override the default token TTL of 32 days (768 hours). See our Vault Tokens(opens in new tab) documentation for more information.

The token_max_ttl is the maximum lifetime for the generated token. The token cannot be renewed past the allowed max TTL.

Step 4: Create an external group and policy mapping

Figure 3: Mapping of OIDC provider group to Vault identity group

The last configuration for OIDC auth is to map groups in your OIDC provider to Vault identity groups. This allows you to centrally manage group membership within your OIDC provider. Vault uses this information to assign the correct policies for each group within your OIDC provider.

The first step in implementing this mapping is to create a Vault external group(opens in new tab), which is a Vault representation of a group outside of its identity store. The external group is associated with a set of Vault policies that define the access allowed. The next step is to create a Vault group alias, which ties the Vault external group to a group in your OIDC provider. During authentication, Vault will attempt to match an OIDC provider group to an external group using the group claim specified in step 3. If a match is found, an entity is added as a member of the external group and a token is returned with the associated policy. If a user is removed from the group in your OIDC provider, that change gets reflected in Vault only upon a subsequent login or token renewal operation.

Configuration for root namespace

The commands below create an external group called vault-operators for the Vault operators team. This external group is tied to an OIDC group called vault-operators by the group alias created in the last command. You can find more details on each parameter in our identity secrets engine API(opens in new tab).

$ GROUP_ID=$(vault write -format=json identity/group \
  name="vault-operators" \
  type="external" \
  policies="operator" | jq -r ".data.id")
 
$ MOUNT_ACCESSOR=$(vault read -field=accessor sys/mounts/auth/oidc)
 
$ vault write identity/group-alias \
  name="vault-operators" \
  mount_accessor=$MOUNT_ACCESSOR \
  canonical_id=$GROUP_ID

Configuration for org namespace

Before enabling the below configuration, ensure that your Vault CLI is configured to point to the org namespace. Create an external group called vault-admins for your regular Vault administrators.

$ GROUP_ID=$(vault write -format=json identity/group \
  name="vault-admins" \
  type="external" \
  policies="admin" | jq -r ".data.id")
 
$ MOUNT_ACCESSOR=$(vault read -field=accessor sys/mounts/auth/oidc)
 
$ vault write identity/group-alias \
  name="vault-admins" \
  mount_accessor=$MOUNT_ACCESSOR \
  canonical_id=$GROUP_ID

Step 5: Validate OIDC auth configuration

You can validate the OIDC auth configuration with either the Vault UI or CLI. Login using the CLI with the following command in the next sections.

Configuration for root namespace

Login to the root namespace as a super administrator.

$ vault login -method=oidc

Configuration for tenant namespace

Login to the tenant namespace as a tenant administrator.

$ export VAULT_NAMESPACE=<tenant level namespace>
$ vault login -method=oidc

This command launches a browser window to your OIDC provider login page. The default role is used since no role is specified. Enter your credentials and you should be redirected back to Vault indicating that you have successfully signed in via OIDC. You can validate the policies attached to the returned token with the token information displayed on your CLI.

Waiting for OIDC authentication to complete...
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                  hvs.root.token
token_accessor         Igcq6WRvsPk8ViO9rUpEGlrk
token_duration         1h
token_renewable        true
token_policies         ["default"]
identity_policies      ["admin"]
policies               ["default" "admin"]
token_meta_email       nick@domain.com
token_meta_role        default
token_meta_username    nick

Useful resources

• OIDC configuration troubleshooting(opens in new tab)
• High-level configuration steps for various OIDC providers(opens in new tab)
• Azure AD with OIDC auth method tutorial(opens in new tab)
• OIDC authentication with Okta tutorial(opens in new tab)

LDAP auth method

The LDAP auth method allows authentication using an existing LDAP server and user/password credentials. This enables users to login to Vault using their existing LDAP credentials without having to create new user accounts in Vault. LDAP groups can be directly mapped to Vault policies, which control the paths in Vault that members of the LDAP group can access.

The LDAP auth method connects directly to your organizations' LDAP servers. Vault must be able to communicate with the LDAP server over TCP and UDP port 389, or on port 636 for LDAPS. When an authentication request is made through the auth method, Vault verifies the provided credentials with the backend LDAP server through a service account. After successful validation of the credentials, Vault issues a token, associates it with the appropriate Vault policy, and returns the token to the user.

Configuring LDAP auth method

The steps outlined below are the general workflow for configuring an LDAP auth method. You should perform these steps first in the root namespace for your super administrators, then configure another LDAP auth method or a different human auth method in the tenant namespace for regular administrators and all other users. The code snippets in these steps will highlight distinctions between the configuration in the root namespace versus the tenant namespace.

Step 1: Enable the auth method

First step is to enable the auth method. You can enable and configure the auth method using the UI, CLI, or the API (including via Terraform). We will focus on CLI commands in this document.

Configuration for root namespace

Using the Vault CLI, login to Vault with your root token and enable the LDAP auth method under the root namespace using the code snippet below.

$ vault auth enable ldap

Configuration for tenant namespace

Using the Vault CLI, login to Vault with your root token and enable the LDAP auth method under the tenant namespace using the code snippet below.

$ export VAULT_NAMESPACE=<tenant namespace>
$ vault auth enable ldap

Step 2: Configure the auth method

Next step is to configure the auth method to allow Vault to communicate with the backend LDAP server(s).

The command below shows an example of a basic LDAP configuration.

• LDAP server running on ldap.example.com, port 389.
• Server supports STARTTLS command to initiate encryption on the standard port.
• CA Certificate stored in file named ldap_ca_cert.pem
• Server does not allow anonymous binds for performing user search (discoverdn=false).
• Bind account used for searching is cn=vault,ou=users,dc=example,dc=com with password My$ecrt3tP4ss.
• User objects are under the ou=Users,dc=example,dc=com organizational unit.
• Username passed to Vault when authenticating maps to the sAMAccountName attribute.
• Group membership will be resolved via the cn attribute of group objects. That search will begin under ou=Groups,dc=example,dc=com.
• Generated Vault tokens expire 1 hour after creation.
• Generated Vault tokens can be renewed for up to 8 hours after creation.

vault write auth/ldap/config \
 url="ldap://ldap.example.com" \
 userattr="sAMAccountName" \
 userdn="ou=Users,dc=example,dc=com" \
 groupdn="ou=Groups,dc=example,dc=com" \
 groupattr="cn" \
 binddn="cn=vault,ou=users,dc=example,dc=com" \
 bindpass="My$ecr3tP4ss" \
 certificate=@ldap_ca_cert.pem \
 insecure_tls=false \
 starttls=true \
 discoverdn=false \
 token_ttl=1h \
 token_max_ttl=8h

For more example configurations, see the LDAP Auth Method documentation(opens in new tab). For details on specific parameters, see the LDAP Auth API(opens in new tab).

Step 3: Assign Vault policies to LDAP groups

Next, you will map existing LDAP groups to the appropriate Vault policies. This allows you to manage group membership and Vault access within LDAP, removing the need to create and manage groups within Vault.

Configuration for root namespace

The command below shows an example where the vault-operators group in LDAP is mapped to the operator policy created earlier in this document.

$ vault write auth/ldap/groups/vault-operators policies=operator

Configuration for tenant namespace

The command below shows an example where the vault-operators group in LDAP is mapped to the operator policy created earlier in this document.

$ vault write auth/ldap/groups/vault-operators policies=operator

Step 4: Validate LDAP auth configuration

You can validate the LDAP auth configuration with either the Vault UI, CLI, or API. Login using the CLI with the following command.

Configuration for root namespace

Login to the root namespace as a Vault cluster operator.

$ vault login -method=ldap username=my-operator password=passw0rd

Configuration for tenant namespace

Login to the tenant namespace as a tenant administrator and validate that the admin policy is attached to the returned token.

$ vault login -method=ldap username=nwong password=passw0rd
 
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                  hvs.root.token
token_accessor         EbPflE8su5iRb2qD8KydXsUf.7fKdt
token_duration         1h
token_renewable        true
token_policies         ["default" "admin"]
identity_policies      []
policies               ["default" "admin"]
token_meta_username    nwong

Reference material

• LDAP Auth Method documentation(opens in new tab)

Revoke the root token

For Vault Enterprise, the root token is attached to the root policy, which is capable of performing every operation for all paths in Vault. After you have validated that you can login using your first auth method, revoke the root token to eliminate the risk of exposure.

Revoke the root token using the following CLI command.

$ vault login <your root token>
 
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                hvs.root.token
token_accessor       JlM24NC1dk6MZLtup1XrKHYM
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]
 
 
$ vault token revoke <your root token>
Success! Revoked token (if it existed)