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 simple and 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.

»Step 1: 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 and then save the value as AUTH0_DOMAIN environment variable.
Example:
```
$ export AUTH0_DOMAIN=dev-2i513orw.auth0.com
```

Similarly, copy the Client ID and Client Secret values and save them as AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET environment variables.

Example:

# Set client ID
$ export AUTH0_CLIENT_ID=FFXlsY2atr_aaaa_hMtsE-zTAeTZnu8

# Set client secret
$ export AUTH0_CLIENT_SECRET=1O7f9JQkv6b25Jf1m4io25h340rendfjfweoprjw-0-1284

In the Allowed Callback URLs field, enter the following:
```
https://<vault_server_address>:8200/ui/vault/auth/oidc/oidc/callback,
https://<vault_server_address>:8250/oidc/callback
```
The https://<vault_server_address>:8200/ui/vault/auth/oidc/oidc/callback address will be used by Vault UI when you login with OIDC auth method. The https://<vault_server_address>:8250/oidc/callback address will be used by the CLI when you login via vault login -method=oidc command.
NOTE: The callback URLs must be comma-separated.
For example, if you are running your Vault server locally:

»Step 2: Create policies for the demo

As described in the introduction, every client token has policies attached to it to control its secret access. So, first author policy files and save them as manager.hcl and reader.hcl.

NOTE: If you are unfamiliar with Vault policies, refer to the policies tutorial.

manager.hcl

# Manage k/v secrets
path "/secret/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}

reader.hcl

# Read permission on the k/v secrets
path "/secret/*" {
    capabilities = ["read", "list"]
}

Now, create manager and reader policies.

Create manager policy.

$ vault policy write manager manager.hcl

Create reader policy.

$ vault policy write reader reader.hcl

List policies to verify.
```
$ vault policy list
```

»Step 3: Enable OIDC auth method

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

Enable oidc auth method by executing the following command.
```
$ vault auth enable 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"

You set the AUTH0_DOMAIN, AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET environment variables in Step 1.

Now, create the "reader" role you set as the default_role in the previous step. You specified the Allowed Callback URLs in Auth0 (Step 1). Now, you need to set the matching URLs as an allowed_redirect_uris parameter.
Example: If you are running your Vault server locally:
```
$ 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 user_claim sets the claim to use to uniquely identify the user.

»Step 4: 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 as follow (refer to Step 3).

$ 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"

»Step 5: Create a group in Auth0

This step demonstrates a simple way to create and use a group.

In the Auth0 dashboard, select Users & Roles > Users.
Click on your user name.
Find the Metadata section and modify the app_metadata to add role "manager".
```
{
  "roles": [
    "kv-mgr"
  ]
}
```
Then, click SAVE.
Now, select Rules and click CREATE RULE.
Select empty rule.

Set the rule name to be Set user role and modify the rule as follow.

function (user, context, callback) {
  user.app_metadata = user.app_metadata || {};
  context.idToken["https://example.com/roles"] = user.app_metadata.roles || [];
  callback(null, user, context);
}

Click SAVE.
NOTE: Using a dummy domain, example.com for this demo.
For an extended details about creating and managing roles in Auth0, refer to the online documentation.

»Step 6: Create an external 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.

Create another role named "kv-mgr". Its parameters are pretty much the same as to the "reader" role you created in Step 2; however, you specify the groups_claim in addition.
Example: If you are running your Vault server locally:
```
$ vault write auth/oidc/role/kv-mgr \
        bound_audiences="$AUTH0_CLIENT_ID" \
        allowed_redirect_uris="http://127.0.0.1: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"
```
NOTE: Remember that you set context.idToken["https://example.com/roles"] = user.app_metadata.roles in the Set user role rule in Auth0 in Step 5.

Create an external group named, "manager" with manager policy attached.

$ 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

Copy and store the id value as GROUP_ID for convenience.

$ export GROUP_ID="1713c9c1-42c1-de6a-5d13-44f7c06f113f"

Create a group alias, "kv-mgr" to be added to the "manager" group.

# Get the mount accessor value of the oidc auth method and save it in accessor.txt file
$ vault auth list -format=json  \
        | jq -r '."oidc/".accessor' > accessor.txt

# Create a group alias named "kv-mgr"
$ vault write identity/group-alias name="kv-mgr" \
        mount_accessor=$(cat accessor.txt) \
        canonical_id="$GROUP_ID"

Now, try log in with "kv-mgr" role.

$ 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

Notice that the returned token inherited the manager policy from the manager group since the kv-mgr belongs to the manager group. The reader policy was attached 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.