OIDC Auth Method | Vault - HashiCorp Learn

Before a client can interact with Vault, it must authenticate against an auth method to acquire a token. This token has policies attached so that the behavior of the client can be governed.

Auth Concept

NOTE: To learn the basics of Vault tokens, go through the Tokens tutorial.

Auth methods perform authentication to verify the user or machine-supplied information. Some of the supported auth methods are targeted towards users while others are targeted toward machines or apps.

»Challenge

Vault supports a number of auth methods for users or system to prove their identity so that a token with appropriate policies can be obtained. Delegated authorization methods based on OAuth 2.0 are convenient for users and have become increasingly common, but the identity semantics are vague and vary between providers.

»Solution

Vault 1.1 introduced its support for OpenID Connect (OIDC). OIDC provides an identity layer on top of OAuth 2.0 to address the shortcomings of using OAuth 2.0 for establishing identity. 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 method is familiar for most users. For operators, the types of identity data that can be provided as part of OIDC allow for flexible mapping to Vault's identity system.

»Prerequisites

To perform the tasks described in this tutorial, you need to have a Vault 1.1 or later. Refer to the Getting Started tutorial to install Vault. Make sure that your Vault server has been initialized and unsealed.

»Auth0 Account

To demonstrate an end-to-end workflow, this tutorial uses Auth0, so create an account if you don't have one.

NOTE: If you prefer to try the OIDC auth method using Google OAuth, refer to Vault OpenID Demo. For other provider configuration steps, refer to the OIDC Provider Setup documentation.

»Policy requirements

NOTE: For the purpose of this tutorial, you can use the root token to work with Vault. However, it is recommended that root tokens are only used for just enough initial setup or in emergencies. As a best practice, use tokens with an appropriate set of policies based on your role in the organization.

To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:

# Mount the OIDC auth method
path "sys/auth/oidc" {
  capabilities = [ "create", "read", "update", "delete", "sudo" ]
}

# Configure the OIDC auth method
path "auth/oidc/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Write ACL policies
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# List available secrets engines to retrieve accessor ID
path "sys/mounts" {
  capabilities = [ "read" ]
}

If you are not familiar with policies, complete the policies tutorial.

»Start Vault

In another terminal, start a Vault dev server with root as the root token.

$ vault server -dev -dev-root-token-id root

The Vault dev server defaults to running at 127.0.0.1:8200. The server is initialized and unsealed.

Insecure operation: Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.

Export an environment variable for the vault CLI to address the Vault server.

$ export VAULT_ADDR=http://127.0.0.1:8200

Export an environment variable for the vault CLI to address the Vault server through the OIDC interface.

$ export VAULT_OIDC_ADDR=http://127.0.0.1:8250

Export an environment variable for the vault CLI to authenticate with the Vault server.

$ export VAULT_TOKEN=root

NOTE: For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.

The Vault server is ready.

»Get Auth0 credentials

If you do not have an account with Auth0, sign up to create one first.

In the Auth0 dashboard, select Applications.
Select Default App and Settings.
Copy the Domain.
In a terminal, set the variable AUTH0_DOMAIN to the Domain.
```
$ export AUTH0_DOMAIN=<Domain>
```
Copy the Client ID.
In a terminal, set the variable AUTH0_CLIENT_ID to the Client ID.
```
$ export AUTH0_CLIENT_ID=<Client ID>
```
Copy the Client Secret.
In a terminal, set the variable AUTH0_CLIENT_SECRET to the Client Secret.
```
$ export AUTH0_CLIENT_SECRET=<Client Secret>
```
In the Allowed Callback URLs field, enter the following:
```
https://localhost:8250/oidc/callback
https://localhost:8200/ui/vault/auth/oidc/oidc/callback,
```
The https://localhost:8250/oidc/callback address enables the Vault CLI to login via the OIDC method. The https://localhost:8200/ui/vault/auth/oidc/oidc/callback address enables the Vault web UI to login via the OIDC method.
NOTE: The callback URLs must be comma-separated.
For example, if you are running your Vault server locally:

»Create Vault policies

Within an organization personas with different capabilities are required to interact with the secrets stored in Vault. Each persona requires a different set of capabilities. These are expressed in policies. If you are not familiar with policies, complete the policies tutorial.

Create the policy file named manager.hcl.

$ tee manager.hcl <<EOF
# Manage k/v secrets
path "/secret/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

This policy grants almost all capabilities to all paths in KV secrets engine enabled at the secret path.

Create the policy file named reader.hcl.

$ tee reader.hcl <<EOF
# Read permission on the k/v secrets
path "/secret/*" {
    capabilities = ["read", "list"]
}
EOF

This policy grants read and list capabilities to all paths in the KV secrets engine enabled at the secret path.

Create a policy named manager with the policy defined in manager.hcl.

$ vault policy write manager manager.hcl

Create a policy named reader with the policy defined in reader.hcl.

$ vault policy write reader reader.hcl

List all the policies.

$ vault policy list
default
manager
reader
root

The manager and reader policies are present in the list alongside the policies that Vault automatically creates.

»Enable OIDC auth method

OIDC must be enabled and configured before it can be used.

Enable the oidc auth method at the default path.

$ vault auth enable oidc

The OIDC auth method is enabled at the path oidc.

Configure the oidc auth method.

$ vault write auth/oidc/config \
         oidc_discovery_url="https://$AUTH0_DOMAIN/" \
         oidc_client_id="$AUTH0_CLIENT_ID" \
         oidc_client_secret="$AUTH0_CLIENT_SECRET" \
         default_role="reader"

The oidc_discovery_url, oidc_client_id, and oidc_client_secret are set to the variables defined in the Get Auth0 credentials step.

The default_role is set to reader. This is a role defined for the authentication method that assigns the reader policy.

Create the reader role.

$ vault write auth/oidc/role/reader \
      bound_audiences="$AUTH0_CLIENT_ID" \
      allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback" \
      allowed_redirect_uris="http://localhost:8250/oidc/callback" \
      user_claim="sub" \
      policies="reader"

The allowed_redirect_uris and allowed_redirect_uris use the Allowed Callback URLs defined in the Get Auth0 credentials step. The user_claim sets the claim to use to uniquely identify the user.

»Login with OIDC

$ vault login -method=oidc role="reader"

When prompted, accept and authorize the Vault access to your Default App.

Config OIDC

Expected output looks like:

Complete the login via your OIDC provider. Launching browser to:

    https://dev-2i513orw.auth0.com/authorize?client_id=FFXlsY2atr_wfNaF_hMtsE-zTAeTZnu8&nonce=73fe4c11828d3c4eb8c2c270aa1b3ab45ebda490&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid&state=965d81adcfad9d83a29659891cee37358c8d45cc

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.mefxZpkwUzGirhakGtQZoez0
token_accessor       oGB9LqtSGxiEWp2zz4DLlIBD
token_duration       768h
token_renewable      true
token_policies       ["default" "reader"]
identity_policies    []
policies             ["default" "reader"]
token_meta_role      reader

»Unauthorized Redirect URI Error

If you received unauthorized redirect_uri: redirect_uri=http://127.0.0.1:8250/oidc/callback error, update the oidc configuration for the reader role.

Update the reader role.

$ vault write auth/oidc/role/reader \
        bound_audiences="$AUTH0_CLIENT_ID" \
        allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback" \
        allowed_redirect_uris="http://127.0.0.1:8250/oidc/callback" \
        user_claim="sub" \
        policies="reader"

The user logs in to Vault through OIDC vith Auth0. The token issued to the user is assigned through the reader role which grants it the capabilities defined in the reader role.

»Create an Auth0 group

A user that authenticates through OIDC with Auth0 may also have their Vault role assigned through metadata defined in Auth0.

In the Auth0 dashboard, select Users & Roles > Users.
Click on your user name.
Enter the following metatada in the app_metadata.
```
{
  "roles": ["kv-mgr"]
}
```
When this user authenticates, this metadata is provided to Vault in the callback. Vault requests a token from the Vault group named kv-mgr.
Click SAVE.
From the side navigation, select Rules.
Click CREATE RULE.
Select empty rule.
Enter Set user role in the Name field.
Enter the following script in the Script field.
```
function (user, context, callback) {
  user.app_metadata = user.app_metadata || {};
  context.idToken["https://example.com/roles"] = user.app_metadata.roles || [];
  callback(null, user, context);
}
```
This script ensures that the user has the app_metadata field; creating one if none exists. Then assigns to the context.idToken all of the roles defined for the user; or an empty list if none exist.
Click SAVE CHANGES.
NOTE: The use of example.com is used here for demonstration.
For an extended details about creating and managing roles in Auth0, refer to the online documentation.

»Create an external Vault group

A group claim is used to uniquely identify a set of groups to which the user belongs (this will be used as the names for the identity group aliases created after a successful login).

Config OIDC

NOTE: If you are unfamiliar with Vault Identity, refer to the Identity: Entities and Groups tutorial.

The Login with OIDC step has you authenticate with the capabilites of the reader policy. This token is unable to configure the OIDC auth method.

$ vault login $VAULT_TOKEN

Create a role named kv-mgr.

$ vault write auth/oidc/role/kv-mgr \
         bound_audiences="$AUTH0_CLIENT_ID" \
         allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback" \
         allowed_redirect_uris="http://localhost:8250/oidc/callback" \
         user_claim="sub" \
         policies="reader" \
         groups_claim="https://example.com/roles"

This role is defined similarly to the previously created role. The reader capapbility is assigned to the token. Additional policies are assigned through any groups that the user claims to belong. The groups_claim field defines the value of https://example.com/roles. This value is the key in the context.idToken that stores all the roles defined in the metadata for the user.

Create an external group, named manager with the manager policy.

$ vault write identity/group name="manager" type="external" \
         policies="manager" \
         metadata=responsibility="Manage K/V Secrets"

Example output:

Key     Value
---     -----
id      1713c9c1-42c1-de6a-5d13-44f7c06f113f
name    manager

Create a variable named GROUP_ID to store the id of the manager group.

$ GROUP_ID=$(vault write -field=id identity/group name="manager" type="external" \
         policies="manager" \
         metadata=responsibility="Manage K/V Secrets")

As of Vault 1.7, if the group already exists, you will need to obtain the id from a read.

$ GROUP_ID=$(vault read -field=id identity/group/name/manager)

Create a variable named OIDC_AUTH_ACCESSOR to store the accessor of the oidc authentication method.

$ OIDC_AUTH_ACCESSOR=$(vault auth list -format=json  | jq -r '."oidc/".accessor')

This displays all authentication methods in JSON and then parses that list, throught jq, to extract the accessor field of the oidc authentication method.

Create a group alias named kv-mgr.

$ vault write identity/group-alias name="kv-mgr" \
         mount_accessor="$OIDC_AUTH_ACCESSOR" \
         canonical_id="$GROUP_ID"

The kv-mgr group alias connects the oidc authentication method and the manager group with the manager policy.

$ vault login -method=oidc role="kv-mgr"

Complete the login via your OIDC provider. Launching browser to:

      https://dev-2i513orw.auth0.com/authorize?client_id=FFXlsY2atr_wfNaF_hMtsE-zTAeTZnu8&nonce=5ad8af6eab5146d355ab5b25712b0d7776b384f7&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid&state=721184bf8d5abe295a617d1cb98ab75c1a7d39fc

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.WlmlH2yPid7sSKYbBlimD4MD
token_accessor       zd4MBqI9HD4YVhIWQKU6tz0b
token_duration       768h
token_renewable      true
token_policies       ["default" "reader"]
identity_policies    ["manager"]
policies             ["default" "manager" "reader"]
token_meta_role      kv-mgr

The returned token inherits the default, manager and reader policies. The manager policy is assigned because the value kv-mgr, defined in the metadata, has an alias that belongs to the manager group. The reader policy is assigned to the kv-mgr role.

»Leveraging Social Accounts

To enable your users login with their Google OAuth or any other social connections, select Connections > Social from the Auth0 dashboard to configure them.

Social Connections

Select your application, and under the Connections tab, you can select which social connection to enable for the particular application.