Operations

OIDC Auth Method

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 guide.

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.

Although JWT auth method has been available since Vault 0.10.4, it does not handle the OAuth 2.0 flows required for a browser-assisted login with an authentication server. 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 guide, you need to have a Vault 1.1 or later. Refer to the Getting Started guide to install Vault. Make sure that your Vault server has been initialized and unsealed.

» Auth0 Account

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

» Policy requirements

To perform all tasks demonstrated in this guide, 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 secret engines to retrieve accessor ID
path "sys/mounts" {
  capabilities = [ "read" ]
}

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

» Steps

In this guide, you are going to perform the following steps:

  1. Get Auth0 credentials
  2. Create policies for the demo
  3. Enable OIDC auth method
  4. Login with OIDC
  5. Create a group in Auth0
  6. Create an external group

» Step 1: Get Auth0 credentials

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

  1. In the Auth0 dashboard, select Applications.

  2. Select Default App and Settings. Dashboard

  3. Copy the Domain and then save the value as AUTH0_DOMAIN environment variable. Dashboard

    Example:

    $ export AUTH0_DOMAIN=dev-2i513orw.auth0.com
    
  4. 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
    
  5. 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.

    For example, if you are running your Vault server locally: Callback

» 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.

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.

CLI command / API call using cURL / Web UI

» CLI command

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

» API call using cURL

Create manager and reader policies:

# Create HTTP request payload
$ tee payload-mgr.json <<EOF
{
  "policy": "path \"/secret/*\" {\n\tcapabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\"]\n}\n"
}
EOF

# Invoke sys/policies/acl endpoint to create a policy
# Be sure to pass your client token in the X-Vault-Token header
$ curl --header "X-Vault-Token: ..." --request PUT \
       --data @payload-mgr.json \
       http://127.0.0.1:8200/v1/sys/policies/acl/manager

# Create HTTP request payload
$ tee payload-reader.json <<EOF
{
 "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\"]\n}\n"
}
EOF

# Invoke sys/policies/acl endpoint to create a policy
# Be sure to pass your client token in the X-Vault-Token header
$ curl --header "X-Vault-Token: ..." --request PUT \
       --data @payload-reader.json \
       http://127.0.0.1:8200/v1/sys/policies/acl/reader

# List policies to verify
$ curl --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policies/acl?list=true | jq

» Web UI

  1. Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.

  2. Select the Policies tab and then select Create ACL policy.

  3. Toggle Upload file sliding switch, and click Choose a file to select your manager.hcl file you authored. This loads the policy and sets the Name to be manager.

  4. Click Create Policy to complete.

  5. Return to ACL Policies and then select Create ACL policy again.

  6. Toggle Upload file sliding switch, and click Choose a file to select your reader.hcl file you authored.

  7. Click Create Policy to complete.

» Step 3: Enable OIDC auth method

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

CLI command / API call using cURL

» CLI command

  1. Enable oidc auth method by executing the following command:

    $ vault auth enable oidc
    
  2. 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.

  3. 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.

» API call using cURL

  1. Enable oidc auth method by mounting its endpoint at /sys/auth/oidc:

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data <PARAMETERS> \
           <VAULT_ADDR>/v1/sys/auth/oidc
    

    Where <TOKEN> is your client token, and <PARAMETERS> holds configuration parameters of the method.

    Example:

    $ curl --header "X-Vault-Token: ..." \
           --request POST \
           --data '{"type": "oidc"}' \
           http://127.0.0.1:8200/v1/sys/auth/oidc
    

    The above example passes the type (oidc) in the request payload at the sys/auth/oidc endpoint.

  2. Configure the oidc auth method.

    Example:

    # Create an HTTP payload
    $ tee oidc_config.json <<EOF
    {
       "oidc_discovery_url": "https://$AUTH0_DOMAIN/",
       "oidc_client_id": "$AUTH0_CLIENT_ID",
       "oidc_client_secret": "$AUTH0_CLIENT_SECRET",
       "default_role": "reader"
     }
    EOF
    
    # Configure the oidc auth method
    $ curl --header "X-Vault-Token: ..." \
           --request POST \
           --data @oidc_config.json \
           http://127.0.0.1:8200/v1/auth/oidc/config
    

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

  3. 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:

    # Create an HTTP payload
    $ tee oidc_role.json <<EOF
    {
        "bound_audiences": "$AUTH0_CLIENT_ID",
        "allowed_redirect_uris": [
            "http://localhost:8200/ui/vault/auth/oidc/oidc/callback",
            "http://localhost:8250/oidc/callback"
        ],
        "user_claim": "sub",
        "policies": ["reader"]
     }
    EOF
    
    # Configure the oidc auth method
    $ curl --header "X-Vault-Token: ..." \
           --request POST \
           --data @oidc_role.json \
           http://127.0.0.1:8200/v1/auth/oidc/role/reader
    

» Step 4: Login with OIDC

CLI command / Web UI

» CLI command

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

» Web UI

  1. Sign out of the Vault UI if you are already logged in.

  2. Select OIDC from the Method drop-down list. Config OIDC

  3. In the Role, you can enter reader or since the default role is already set to "reader", you can leave it blank.

  4. Click Sign in with Auth0. If prompted, accept and authorize the Vault access to your Default App.
    Config OIDC

  1. Now, you should be logged in.

» Unauthorized Redirect URI Error

If you received unauthorized redirect_uri: redirect_uri=http://127.0.0.1:8200/ui/vault/auth/oidc/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://127.0.0.1:8200/ui/vault/auth/oidc/oidc/callback" \
        allowed_redirect_uris="http://localhost: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.

  1. In the Auth0 dashboard, select Users & Roles > Users.

  2. Click on your user name.

  3. Find the Metadata section and modify the app_metadata to add role "manager".

    {
      "roles": [
        "manager"
      ]
    }
    

    Then, click SAVE. Config OIDC

  4. Now, select Rules and click CREATE RULE.

  5. Select empty rule.

  6. 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);
    }
    
  7. Click SAVE. Config OIDC

    NOTE: Using a dummy domain, example.com for this demo.

» 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

CLI command / API call using cURL

» CLI command

  1. 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 4.

  2. 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"
    
  3. 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"
    
  4. 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.

» API call using cURL

  1. 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:

    # Create an HTTP payload
    $ tee oidc_role-2.json <<EOF
    {
        "bound_audiences": "$AUTH0_CLIENT_ID",
        "allowed_redirect_uris": [
            "http://localhost:8200/ui/vault/auth/oidc/oidc/callback",
            "http://127.0.0.1:8200/ui/vault/auth/oidc/oidc/callback",
            "http://localhost:8250/oidc/callback",
            "http://127.0.0.1:8250/oidc/callback"
        ],
        "user_claim": "sub",
        "policies": ["reader"],
        "groups_claim": "https://example.com/roles"
     }
    EOF
    
    # Configure the oidc auth method
    $ curl --header "X-Vault-Token: ..." \
           --request POST \
           --data @oidc_role-2.json \
           http://127.0.0.1:8200/v1/auth/oidc/role/kv-mgr
    
  2. Create an external group named, "manager" with manager policy attached.

    # API request message body
    $ tee payload-mgr.json <<EOF
    {
       "name": "manager",
       "policies": ["manager"],
       "type": "external",
       "metadata": {
         "responsibility": "Manage K/V Secrets"
       }
    }
    EOF
    
    # Create an external group named "manager"
    # Be sure to copy the group ID (id)
    $ curl --header "X-Vault-Token: ..." \
           --request POST \
           --data @payload-mgr.json \
           http://127.0.0.1:8200/v1/identity/group | jq
    {
       ...
       "data": {
         "id": "4d4e51c9-1f92-4109-49f7-db7b44764cad",
         "name": "manager"
       },
       ...
    }
    

    Copy and store the id value as GROUP_ID for convenience.

    $ export GROUP_ID="4d4e51c9-1f92-4109-49f7-db7b44764cad"
    
  3. 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
    $ curl --header "X-Vault-Token: ..." \
           http://127.0.0.1:8200/v1/sys/auth \
           | jq -r '."oidc/".accessor' > accessor.txt
    
    # API request msg payload to create a group aliases, "kv-mgr"
    $ tee payload-alias.json <<EOF
    {
      "canonical_id": "$GROUP_ID",
      "mount_accessor": "$(cat accessor.txt)",
      "name": "kv-mgr"
    }
    EOF
    
    # Create 'manager' group alias
    $ curl --header "X-Vault-Token: ..." \
           --request POST -s \
           --data @payload-alias.json \
           http://127.0.0.1:8200/v1/identity/group-alias | jq
    {
       ...
       "data": {
         "canonical_id": "4d4e51c9-1f92-4109-49f7-db7b44764cad",
         "id": "3c57cedf-2d9f-4f4d-b8fc-743255a2f6d6"
       },
       ...
    }
    
  4. Now, sign out of the Vault UI if you are already logged in.

  5. Select OIDC from the Method drop-down list.

  6. In the Role, you can enter kv-mgr.

  7. Click Sign in with Auth0. You should be logged in.

» 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.

Social Connections

NOTE: The client ID and client secret are unique to each application that you configured OIDC auth method with.

» Help and Reference