• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Try Cloud(opens in new tab)
  • Sign up
HCP Vault Operations

Skip to main content
12 tutorials
  • Peering an AWS VPC with HashiCorp Cloud Platform (HCP)
  • Connect an Amazon Transit Gateway to your HashiCorp Virtual Network
  • HCP Vault Namespace Considerations
  • HCP Vault Performance Replication
  • Set up AWS Auth Method for HCP Vault
  • OIDC Authentication with Okta
  • Deploy HCP Vault with Terraform
  • Codify Management of HCP Vault
  • HCP Vault with AWS EKS and JWT Auth Method
  • HCP Vault with Amazon Elastic Kubernetes Service
  • Deploy HCP Vault Performance Replication with Terraform
  • Manage Codified Vault on HCP Vault with Terraform

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Tutorials
  4. HCP Vault Operations
  5. OIDC Authentication with Okta

OIDC Authentication with Okta

  • 37min

  • VaultVault

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

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 systems 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 supports 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 or CLI with a new 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.

In this tutorial, you will create and configure the necessary resources in Okta to support the Vault OIDC auth method to allow policies to be assigned based on an Okta users group membership.

okta-vault-resource-relationship

Prerequisites

To complete this tutorial you should have familiarity with, and access to HCP Vault or open source Vault, and Okta.

Visit the Getting Started with HCP Vault tutorials for a refresher on how to deploy and configure HCP Vault.

The following items must be deployed and configured before you begin:

  • Administrator access to an Okta account (Okta Developer Edition can be used for this tutorial).
  • HashiCorp Vault binary installed on your local system. Please see the Install Vault tutorial for more information.

If you are using HCP Vault:

  • HashiCorp Virtual Network (HVN) created in the HCP Portal.
  • A Vault cluster (Development tier or higher) with a public address (Refer to the Create a Vault Cluster on HCP tutorial tutorial).

Making your HCP Vault cluster publicly accessible is not recommended, however for ease of completing this tutorial we suggest you have it enabled.

If you are using open source Vault:

  • Vault started in dev server mode. (Refer to the Vault tab in the lab setup section).

Lab setup

Note: If you do not have access to an HCP Vault cluster, visit the Create a Vault Cluster on HCP tutorial.

  1. Launch the HCP Portal and login.

  2. Click Vault in the left navigation pane.

  3. In the Vault clusters pane, click vault-cluster.

  4. Under Cluster URLs, click Public Cluster URL. Public Cluster URL

  5. In a terminal, set the VAULT_ADDR environment variable to the copied address.

    $ export VAULT_ADDR=<Public_Cluster_URL>
    
  6. Return to the Overview page and click Generate token. Generate a Token

    Within a few moments, a new token will be generated.

  7. Copy the Admin Token. Generated Token

  8. Return to the terminal and set the VAULT_TOKEN environment variable.

    $ export VAULT_TOKEN=<token>
    
  9. Set the VAULT_NAMESPACE environment variable to admin.

    $ export VAULT_NAMESPACE=admin
    
  10. Type vault status to verify your connectivity to the Vault cluster.

    $ vault status
    
    Key                      Value
    ---                      -----
    Recovery Seal Type       shamir
    Initialized              true
    Sealed                   false
    Total Recovery Shares    1
    Threshold                1
    Version                  1.9.2+ent
    Storage Type             raft
    ...snipped...
    
  11. With the VAULT_TOKEN environment variable set, you can now explore your Vault cluster. Type vault auth list to view the list of available auth methods.

    $ vault auth list
    
    Path      Type        Accessor                  Description
    ----      ----        --------                  -----------
    token/    ns_token    auth_ns_token_d6310fa6    token based credentials
    

    All new Vault clusters will have the token auth method enabled.

  1. Open a new terminal window and 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.

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

    $ export VAULT_ADDR=http://127.0.0.1:8200
    
  3. 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.

The Vault server is ready.

Okta setup

If you do not have an Okta account, sign up for an Okta Developer Edition account.

Okta users and groups

To demonstrate authentication and policy assignment based on group membership you will create two users, and two groups in Okta.

  1. Launch the Okta portal and login.

  2. In the Okta dashboard, expand Directory in the left navigation menu and click People.

  3. Click the Add person button and enter the following:

    • User type: User
    • First name: Thea
    • Last name: Example
    • Username: thea@example.com
    • Password: Set by admin
    • Enter password: Password1!
    • Uncheck the User must change password on first login checkbox
  4. Click the Save and Add Another button and enter the following:

    • User type: User
    • First name: Bill
    • Last name: Example
    • Username: bill@example.com
    • Password: Set by admin
    • Enter password: Password1!
    • Uncheck the User must change password on first login checkbox
  5. Click the Save button.

  6. Click Groups in the left navigation menu.

  7. Click the Add Group button, name the group okta-group-vault-admins and click the Save button.

  8. Click the Add Group button, name the group okta-group-vault-developer and click the Save button.

  9. Click on okta-group-vault-admins and click the Assign People button.

  10. Click Thea Example to add that user to the Members list and click the Save button.

  11. Click the <- Back to Groups link.

  12. Click on okta-group-vault-developer and click the Assign People button.

  13. Click Bill Example to add that user to the Members list and click the Save button.

You have created two users - Thea and Bill and assigned each to an Okta group - okta-group-vault-admins and okta-group-vault-developer.

Okta OIDC configuration

  1. Expand Security in the left navigation menu and click API.

  2. Click default and then click the Claims tab.

    NOTE: If you are using the default authorization server for other applications, consider creating an additional authorization server specifically for Vault.

  3. Click the + Add Claim button and enter the following:

    • Name: groups
    • Include in token type: ID Token / Always
    • Value type: Groups
    • Filter: Starts with / okta-group-vault
    • Include in: Click the The following scopes: radio button
    • In the text box below The following scopes: type profile and click profile when it appears.
  4. Click the Create button.

    You have updated the default authorization server to include groups with the token ID. Adding groups to the token ID will allow you to assign a Vault policy based on the Okta group membership.

  5. Expand Applications in the left navigation menu and click Applications.

  6. Click the Create App Integration button.

  7. Click the OIDC - OpenID Connect radio button, a new section will appear.

  8. Click the Web Application radio button and then click the Next button.

  9. In the App integration name text box enter hc-vault.

  10. In the Grant type section click the checkbox for Implicit (hybrid).

  11. Remove any existing Sign-in redirect URIs by clicking the X button.

  12. Click the + Add URI button - an empty text box will appear.

  13. Retrieve and copy the address of the Vault cluster stored in the VAULT_ADDR environment variable.

    $ echo $VAULT_ADDR
    
  14. Enter the address of your Vault cluster followed by /ui/vault/auth/oidc/oidc/callback. okta-signin-redirect1

    This URI will support authenticating a user via the Vault UI.

    NOTE: The URI has oidc twice - the first instance of oidc is the path where the OIDC auth method is enabled. If you change the default path of the auth method, you will need to change this in the URL. For example, if you enable the OIDC auth method at a path of okta the corresponding path would be /ui/vault/auth/okta/oidc/callback.

  15. Click the + Add URI button again. Enter http://localhost:8250/oidc/callback.

    This URI supports authenticating a user via the Vault CLI. For more information visit the JWT/OIDC auth method documentation.

  16. Scroll to the bottom of the form.

  17. In the Assignments section, click the Limit access to selected groups radio button.

  18. In the Selected group(s) text box, enter okta-group and click okta-group-vault-admins.

  19. Enter okta-group again and click okta-group-vault-developer.

  20. Click the Save button.

  21. Click the Sign On tab.

  22. In the OpenID Connect ID Token section, click Edit

  23. In the Groups claim filter text box enter okta-group-vault.

  24. Click the Save button.

  25. Click the Okta API Scopes tab.

  26. Find okta.groups.read in the list and click Grant.

  27. Find okta.users.read.self in the list and click Grant.

    You have created an application integration that will support OIDC and assigned the user groups you created to this integration.

Collect Okta configuration settings

  1. Click the General tab.

  2. Copy the Client ID.

  3. Switch to your terminal and set an environment variable named OKTA_CLIENT_ID.

    $ export OKTA_CLIENT_ID=<CLIENT_ID>
    
  4. Switch back to the Okta hc-vault configuration page and copy the Client secret.

  5. Switch to your terminal and set an environment variable named OKTA_CLIENT_SECRET.

    $ export OKTA_CLIENT_SECRET=<CLIENT_SECRET>
    
  6. Switch back to the Okta hc-vault configuration page. Click the user pull down menu at the top right of the Okta dashboard and copy the Okta domain.

  7. Switch to your terminal and set an environment variable named OKTA_DOMAIN.

    $ export OKTA_DOMAIN=<OKTA_DOMAIN>
    

    NOTE: The Okta specific environment variables were created to save the Okta configuration items that will be used later to configure Vault. It is not a requirement to have these environment variables set to use Okta with the Vault OIDC auth method beyond the scope of this tutorial.

  8. Switch back to the Okta hcp-vault configuration page. Click the user pull down menu at the top right of the Okta dashboard and select Sign out.

Configure Vault

You have now configured your local workstation and Okta with enough sample data to start the Vault OIDC auth method configuration.

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.

During the Okta configuration, you created two users - Thea and Bill. Thea was added to the okta-group-vault-admins group and Bill was added to the okta-group-vault-developer group. You will now create a policy that allows read access to the k/v secrets engine for Bill, and a policy that allows admin/super user access for Thea.

  1. Create the policy file named vault-policy-developer-read.hcl.

    $ tee vault-policy-developer-read.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.

  2. Create a Vault policy named vault-policy-developer-read using the the file vault-policy-developer-read.hcl.

    $ vault policy write vault-policy-developer-read vault-policy-developer-read.hcl
    
    Success! Uploaded policy: vault-policy-developer-read
    
  3. Create the policy file named vault-policy-admin.hcl.

    $ tee vault-policy-admin.hcl <<EOF
    # Admin policy
    path "*" {
            capabilities = ["sudo","read","create","update","delete","list","patch"]
    }
    EOF
    
  4. Create a Vault policy named vault-policy-admin using the file vault-policy-admin.hcl.

    $ vault policy write vault-policy-admin vault-policy-admin.hcl
    
    Success! Uploaded policy: vault-policy-admin
    
  5. List all the policies.

    $ vault policy list
    
    default
    hcp-root
    vault-policy-admin
    vault-policy-developer-read
    

    The vault-policy-developer-read and vault-policy-admin policies are available alongside the default policies that Vault automatically creates.

  1. Create an API request payload containing the JSON formatted vault-policy-developer-read policy.

    $ tee vault-policy-developer-read.json <<EOF
    {
    "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\"]\n}\n"
    }
    EOF
    
  2. Create a policy named vault-policy-developer-read with the policy defined in vault-policy-developer-read.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request PUT \
          --data @vault-policy-developer-read.json \
          $VAULT_ADDR/v1/sys/policies/acl/vault-policy-developer-read
    
  3. Create an API request payload containing the JSON formatted vault-policy-admin policy.

    $ tee vault-policy-admin.json <<EOF
    {
    "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\", \"sudo\", \"create\", \"update\", \"delete\", \"patch\"]\n}\n"
    }
    EOF
    
  4. Create a policy named vault-policy-admin with the policy defined in vault-policy-admin.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request PUT \
          --data @vault-policy-admin.json \
          $VAULT_ADDR/v1/sys/policies/acl/vault-policy-admin
    
  5. List all the policies.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          $VAULT_ADDR/v1/sys/policy | jq '.data | .policies'
    

    Example output:

    [
    "default",
    "hcp-root",
    "vault-policy-admin",
    "vault-policy-developer-read"
    ]
    

    The vault-policy-developer-read and vault-policy-admin policies are available alongside the default policies that Vault automatically creates.

  1. Create an API request payload containing the JSON formatted vault-policy-developer-read policy.

    $ tee vault-policy-developer-read.json <<EOF
    {
    "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\"]\n}\n"
    }
    EOF
    
  2. Create a policy named vault-policy-developer-read with the policy defined in vault-policy-developer-read.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request PUT \
          --data @vault-policy-developer-read.json \
          $VAULT_ADDR/v1/sys/policies/acl/vault-policy-developer-read
    
  3. Create an API request payload containing the JSON formatted vault-policy-admin policy.

    $ tee vault-policy-admin.json <<EOF
    {
    "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\", \"sudo\", \"create\", \"update\", \"delete\", \"patch\"]\n}\n"
    }
    EOF
    
  4. Create a policy named vault-policy-admin with the policy defined in vault-policy-admin.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request PUT \
          --data @vault-policy-admin.json \
          $VAULT_ADDR/v1/sys/policies/acl/vault-policy-admin
    
  5. List all the policies.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          $VAULT_ADDR/v1/sys/policy | jq '.data | .policies'
    

    Example output:

    [
    "default",
    "root",
    "vault-policy-admin",
    "vault-policy-developer-read"
    ]
    

    The vault-policy-developer-read and vault-policy-admin policies are available alongside the default policies that Vault automatically creates.

Enable OIDC auth method

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

  1. Enable the oidc auth method at the default path.

    $ vault auth enable oidc
    
    Success! Enabled oidc auth method at: oidc/
    

    The OIDC auth method is enabled at the path oidc.

  2. Create a role named vault-role-okta-default.

    $ vault write auth/oidc/role/vault-role-okta-default \
          bound_audiences="$OKTA_CLIENT_ID" \
          allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \
          allowed_redirect_uris="http://localhost:8250/oidc/callback" \
          user_claim="sub" \
          token_policies="default"
    

    The allowed_redirect_uris use the Allowed Callback URLs defined in the Okta OIDC configuration section. The user_claim sets the claim to use to uniquely identify the user.

  3. Configure the oidc auth method.

    $ vault write auth/oidc/config \
             oidc_discovery_url="https://$OKTA_DOMAIN" \
             oidc_client_id="$OKTA_CLIENT_ID" \
             oidc_client_secret="$OKTA_CLIENT_SECRET" \
             default_role="vault-role-okta-default"
    

    Example output:

    Success! Data written to: auth/oidc/config
    

    The oidc_discovery_url, oidc_client_id, and oidc_client_secret are set to the variables defined in the Collect Okta configuration settings section.

    The default_role is set to vault-role-okta-default. This role and default policy provide a limited set of access to anyone authenticating via Okta.

  4. List the enabled auth methods.

    $ vault auth list
    
    Path      Type        Accessor                  Description
    ----      ----        --------                  -----------
    oidc/     oidc        auth_oidc_99c6e954        n/a
    token/    ns_token    auth_ns_token_41ec2357    token based credentials
    

    The OIDC auth method is now enabled.

  1. Enable the oidc auth method at the path auth/oidc.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data '{"type": "oidc"}' \
          $VAULT_ADDR/v1/sys/auth/oidc
    

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

  2. Create an API request payload containing the definition of the vault-role-okta-default role.

    $ tee vault-role-okta-default.json <<EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"]
    }
    EOF
    

    The allowed_redirect_uris use the Allowed Callback URLs defined in the Okta OIDC configuration section. The user_claim sets the claim to use to uniquely identify the user.

  3. Create the vault-role-okta-default role.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @vault-role-okta-default.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-default
    
  4. Create an API request payload containing the definition of the OIDC configuration.

    $ tee oidc_config.json <<EOF
    {
       "oidc_discovery_url": "https://$OKTA_DOMAIN",
       "oidc_client_id": "$OKTA_CLIENT_ID",
       "oidc_client_secret": "$OKTA_CLIENT_SECRET",
       "default_role": "vault-role-okta-default"
    }
    EOF
    

    The oidc_discovery_url, oidc_client_id, and oidc_client_secret are set to the variables defined in the Collect Okta configuration settings step.

    The default_role is set to vault-role-okta-default. This role and default policy provide a limited set of access to anyone authenticating via Okta.

  5. Configure the oidc auth method.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @oidc_config.json \
          $VAULT_ADDR/v1/auth/oidc/config
    

    The OIDC auth method is now enabled.

  1. Enable the oidc auth method at the path auth/oidc.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data '{"type": "oidc"}' \
          $VAULT_ADDR/v1/sys/auth/oidc
    

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

  2. Create an API request payload containing the definition of the vault-role-okta-default role.

    $ tee vault-role-okta-default.json <<EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"]
    }
    EOF
    

    The allowed_redirect_uris use the Allowed Callback URLs defined in the Okta OIDC configuration section. The user_claim sets the claim to use to uniquely identify the user.

  3. Create the vault-role-okta-default role.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @vault-role-okta-default.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-default
    
  4. Create an API request payload containing the definition of the OIDC configuration.

    $ tee oidc_config.json <<EOF
    {
       "oidc_discovery_url": "https://$OKTA_DOMAIN",
       "oidc_client_id": "$OKTA_CLIENT_ID",
       "oidc_client_secret": "$OKTA_CLIENT_SECRET",
       "default_role": "vault-role-okta-default"
    }
    EOF
    

    The oidc_discovery_url, oidc_client_id, and oidc_client_secret are set to the variables defined in the Collect Okta configuration settings step.

    The default_role is set to vault-role-okta-default. This role and default policy provide a limited set of access to anyone authenticating via Okta.

  5. Configure the oidc auth method.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @oidc_config.json \
          $VAULT_ADDR/v1/auth/oidc/config
    

    The OIDC auth method is now enabled.

Login with OIDC

  1. Log in with the oidc method as role of a vault-role-okta-default.

    $ vault login -method=oidc role="vault-role-okta-default"
    
  2. A new browser window will open. Log in as bill@example.com and the password Password1!.

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
    https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa49ktuo8SwLMNOP7&code_challenge=KjgG1w8Jn1ISUvOwz0B6ttqQvPD6GxRuRHIJKLMNOSA&code_challenge_method=S256&nonce=n_8nHzOTkMJkDqUZlYuQA8&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid&state=st_CqJh1giiQ3DGDUtJJycS
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.Q6BTVufoPaw5EoHIJKL4c9Em.uRvAl
    token_accessor       uciNV8ZBaUPdrkLMNOPYLS4.uRvAl
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    []
    policies             ["default"]
    token_meta_role      vault-role-okta-default
    

    You were able to authenticate using Okta and received the default policy which provides limited access to Vault.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  1. Launch the Vault UI.

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

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

  4. Click Sign in with Okta.

  5. A new browser window will open. Log in as bill@example.com and the password Password1!.

    NOTE: If your web browser has pop-up blocker enabled, you may need to allow your Vault server address from the blocked list.

  6. You are now logged in to the Vault UI.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

Create an external Vault group

To assign different policies to different users based on their Okta group membership you will now configure Vault to match the Okta group membership of the user and assign a more permissive Vault role and policy.

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

  1. Create a role named vault-role-okta-group-vault-developer.

    $ vault write auth/oidc/role/vault-role-okta-group-vault-developer \
          bound_audiences="$OKTA_CLIENT_ID" \
          allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \
          allowed_redirect_uris="http://localhost:8250/oidc/callback" \
          user_claim="sub" \
          token_policies="default" \
          oidc_scopes="groups" \
          groups_claim="groups"
    

    This role is defined similarly to the previously created role. The default policy 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 groups. This value is the key in the ID token.

  2. Create an external group, named okta-group-vault-developer with the vault-policy-developer-read policy.

    $ vault write identity/group name="okta-group-vault-developer" type="external" \
          policies="vault-policy-developer-read" \
          metadata=responsibility="okta-group-vault-developer"
    

    Example output:

    Key     Value
    ---     -----
    id      1713c9c1-42c1-de6a-5d13-44f7c06f113f
    name    okta-group-vault-developer
    
  3. Create a variable named GROUP_ID to store the id of the okta-group-vault-developer group.

    $ GROUP_ID=$(vault read -field=id identity/group/name/okta-group-vault-developer)
    
  4. 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, through jq, to extract the accessor field of the oidc authentication method.

  5. Create a group alias named okta-group-vault-developer.

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

    Example output:

    Key             Value
    ---             -----
    canonical_id    5417a83d-4df6-2a3d-0f3e-f1a3e79cd187
    id              933df803-c174-58ab-3dde-3e71a9a223a9
    

    The okta-group-vault-developer Vault group alias connects the oidc authentication method and the okta-group-vault-developer Vault group with the vault-policy-developer-read policy.

  6. Log in with the oidc method as role of a vault-role-okta-group-vault-developer.

    $ vault login -method=oidc role="vault-role-okta-group-vault-developer"
    
    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=cv9SljXoZuIZyWoSnueacarQNCxMiBkbu_bQ8TgqOBM&code_challenge_method=S256&nonce=n_Su1rUN67CCE1vbqnFvT8&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_KvZmAniXE8ho86R1NT6f
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.i2iYpiAtgjBWzw7VdZiXlf45.6XHz9
    token_accessor       XMRLItHWKNvqZCEJCEQwQXkd.6XHz9
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-developer-read"]
    policies             ["default" "vault-policy-developer-read"]
    token_meta_role      vault-role-okta-group-vault-developer
    

    The returned token inherits the default policy and is assigned the vault-policy-developer-read policy because the value okta-group-vault-developer matches the Okta group the user is assigned. The browser session inherited the previous Okta login for the user bill@example.com.

    NOTE: If your Okta organization settings have a short time out, you may be prompted for Okta credentials again. Log in as bill@example.com and the password Password1!.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  7. Because you will be logging in as a new user to demonstrate different policies being used for different groups you need to log out of the Okta session in your browser.

    Navigate to your Okta domain. You can retrieve this from the Okta dashboard or run echo $OKTA_DOMAIN to retrieve the environment variable. You should be automatically logged into the My Apps page for the user bill@example.com. Click on bill in the top right corner of the page and then click Sign out.

  8. Create a role named vault-role-okta-group-vault-admins.

    $ vault write auth/oidc/role/vault-role-okta-group-vault-admins \
          bound_audiences="$OKTA_CLIENT_ID" \
          allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \
          allowed_redirect_uris="http://localhost:8250/oidc/callback" \
          user_claim="sub" \
          token_policies="default" \
          oidc_scopes="groups" \
          groups_claim="groups"
    
  9. Create an external group, named okta-group-vault-admins with the vault-policy-admin policy.

    $ vault write identity/group name="okta-group-vault-admins" type="external" \
          policies="vault-policy-admin" \
          metadata=responsibility="okta-group-vault-admins"
    

    Example output:

    Key     Value
    ---     -----
    id      1713c9c1-42c1-de6a-5d13-44f7c06f113f
    name    okta-group-vault-admins
    
  10. Create a variable named GROUP_ID to store the id of the okta-group-vault-admins group.

    $ GROUP_ID=$(vault read -field=id identity/group/name/okta-group-vault-admins)
    
  11. 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')
    
  12. Create a group alias named okta-group-vault-admins.

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

    Example output:

    Key             Value
    ---             -----
    canonical_id    c255f65d-8828-6bd6-43d4-d51558b5af55
    id              ebe3d072-3942-b085-3a2c-65ac8e1904e8
    

    The okta-group-vault-admins group alias connects the oidc authentication method and the vault-group-admins group with the vault-policy-admin policy.

  13. Log in with the oidc method as role of a vault-role-okta-group-vault-admins.

    $ vault login -method=oidc role="vault-role-okta-group-vault-admins"
    
  14. A new browser window will open. Log in as thea@example.com and the password Password1!.

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=Gt_sFmEEET1ecuuxNJCUbGx4dzYPn-s25sXz0sPGq8I&code_challenge_method=S256&nonce=n_fQvQ39jUYFrglTUTD1bU&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_XB9OQNfAWVDTldI4zpkq
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.SlzaIGkaYeuzHTTLwb1j3DVu.6XHz9
    token_accessor       jmuZQsNJcH8l7S08F1rM1V82.6XHz9
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-admin"]
    policies             ["default" "vault-policy-admin"]
    token_meta_role      vault-role-okta-group-vault-admins
    

    The returned token inherits the default policy and is assigned the vault-policy-admin policy because the value okta-group-vault-admins matches the Okta group the user is assigned.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  1. Create an API request payload for the okta-group-vault-developer role.

    $ tee vault-role-okta-group-vault-developer.json << EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"],
          "oidc_scopes": "groups",
          "groups_claim": "groups"
    }
    EOF
    

    This role is defined similarly to the previously created role. The default policy 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 groups. This value is the key in the ID token.

  2. Create a role named vault-role-okta-group-vault-developer.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @vault-role-okta-group-vault-developer.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-developer
    
  3. Create an API request payload that defines a Vault group named okta-group-vault-developer that is assigned the vault-policy-developer-read policy.

    $ tee okta-group-vault-developer.json <<EOF
    {
       "name": "okta-group-vault-developer",
       "policies": ["vault-policy-developer-read"],
       "type": "external",
       "metadata": {
          "responsibility": "okta-group-vault-developer"
       }
    }
    EOF
    
  4. Create an external group with the group definition in okta-group-vault-developer.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @okta-group-vault-developer.json \
          $VAULT_ADDR/v1/identity/group | jq
    

    Example output:

    {
      "request_id": "d838f77e-78a8-a99d-11c5-1207af5fee71",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "name": "okta-group-vault-developer"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  5. Create a variable named GROUP_ID to store the id of the okta-group-vault-developer group.

    $ GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --request GET \
       $VAULT_ADDR/v1/identity/group/name/okta-group-vault-developer | jq '.data | .id' -r)
    
  6. Create a variable named OIDC_AUTH_ACCESSOR to store the accessor of the oidc authentication method.

    $ OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
    
  7. Create an API request payload to create a group aliases named okta-group-vault-developer.

    $ tee alias-okta-group-vault-developer.json <<EOF
    {
       "canonical_id": "$GROUP_ID",
       "mount_accessor": "$OIDC_AUTH_ACCESSOR",
       "name": "okta-group-vault-developer"
    }
    EOF
    
  8. Create the okta-group-vault-developer group alias.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST -s \
          --data @alias-okta-group-vault-developer.json \
          $VAULT_ADDR/v1/identity/group-alias | jq
    

    Example output:

    {
      "request_id": "47ac206f-a8f0-4a5a-9a6c-dc47c9dad13c",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "canonical_id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "id": "4a162d55-6251-d06a-9ca5-44989ea51bbc"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  9. Log in with the oidc method as role of a vault-role-okta-group-vault-developer.

    $ vault login -method=oidc role="vault-role-okta-group-vault-developer"
    

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=nrGkYnADoppFFE178nqAFCEWVgdAtfI4dfPUCq02-XQ&code_challenge_method=S256&nonce=n_3wJiZO1Cw7RAkAlJPopT&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_SgutWmHE7iYI77OJADjq
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.BD3wle0TOEQjUtLMNOPQ4g.sbjr6
    token_accessor       ouO1ITwC3YlxI4rfRSTUVh37.sbjr6
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-developer-read"]
    policies             ["default" "vault-policy-developer-read"]
    token_meta_role      vault-role-okta-group-vault-developer
    

    The returned token inherits the default policy and is assigned the vault-policy-developer-read policy because the value okta-group-vault-developer matches the Okta group the user is assigned. The browser session inherited the previous Okta login for the user bill@example.com.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  10. Because you will be logging in as a new user to demonstrate different policies being used for different groups you need to log out of the Okta session in your browser.

    Navigate to your Okta domain. You can retrieve this from the Okta dashboard or run echo $OKTA_DOMAIN to retrieve the environment variable. You should be automatically logged into the My Apps page for the user bill@example.com. Click on bill in the top right corner of the page and then click Sign out.

  11. Create an API request payload for the okta-group-vault-admins role.

    $ tee vault-role-okta-group-vault-admins.json << EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"],
          "oidc_scopes": "groups",
          "groups_claim": "groups"
    }
    EOF
    
  12. Create a role named vault-role-okta-group-vault-admins.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @vault-role-okta-group-vault-admins.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-admins
    
  13. Create an API request payload that defines a Vault group named okta-group-vault-admins that is assigned the vault-policy-admin policy.

    $ tee okta-group-vault-admins.json <<EOF
    {
       "name": "okta-group-vault-admins",
       "policies": ["vault-policy-admin"],
       "type": "external",
       "metadata": {
          "responsibility": "okta-group-vault-admins"
       }
    }
    EOF
    
  14. Create an external group with the group definition in okta-group-vault-admins.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST \
          --data @okta-group-vault-admins.json \
          $VAULT_ADDR/v1/identity/group | jq
    

    Example output:

    {
      "request_id": "d838f77e-78a8-a99d-1234-1207abcde71",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "name": "okta-group-vault-admins"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  15. Create a variable named GROUP_ID to store the id of the okta-group-vault-admins group.

    $ GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --request GET \
       $VAULT_ADDR/v1/identity/group/name/okta-group-vault-admins | jq '.data | .id' -r)
    
  16. Create a variable named OIDC_AUTH_ACCESSOR to store the accessor of the oidc authentication method.

    $ OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
    
  17. Create an API request payload to create a group alias named okta-group-vault-admins.

    $ tee alias-okta-group-vault-admins.json <<EOF
    {
       "canonical_id": "$GROUP_ID",
       "mount_accessor": "$OIDC_AUTH_ACCESSOR",
       "name": "okta-group-vault-admins"
    }
    EOF
    
  18. Create the okta-group-vault-admins group alias.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
          --request POST -s \
          --data @alias-okta-group-vault-admins.json \
          $VAULT_ADDR/v1/identity/group-alias | jq
    

    Example output:

    {
      "request_id": "47ac206f-a8f0-1b3d-9a6c-dc47c9dad13c",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "canonical_id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "id": "4a162d55-6251-d06a-9ca5-44989ea51bbc"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  19. Log in with the oidc method as role of a vault-role-okta-group-vault-admins.

    $ vault login -method=oidc role="vault-role-okta-group-vault-admins"
    
  20. A new browser window will open. Log in as thea@example.com and the password Password1!.

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=nrGkYnADoppFFE178nqAFCEWVgdAtfI4dfPUCq02-XQ&code_challenge_method=S256&nonce=n_3wJiZO1Cw7RAkAlJPopT&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_SgutWmHE7iYI77OJADjq
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.BD3wle0TOEQjUtLMNOPQ4g.sbjr6
    token_accessor       ouO1ITwC3YlxI4rfRSTUVh37.sbjr6
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-admin"]
    policies             ["default" "vault-policy-admin"]
    token_meta_role      vault-role-okta-group-vault-admins
    

    The returned token inherits the default policy and is assigned the vault-policy-admin policy because the value okta-group-vault-admins matches the Okta group the user is assigned.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  1. Create an API request payload for the okta-group-vault-developer role.

    $ tee vault-role-okta-group-vault-developer.json << EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"],
          "oidc_scopes": "groups",
          "groups_claim": "groups"
    }
    EOF
    

    This role is defined similarly to the previously created role. The default policy 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 groups. This value is the key in the ID token.

  2. Create a role named vault-role-okta-group-vault-developer.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @vault-role-okta-group-vault-developer.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-developer
    
  3. Create an API request payload that defines a Vault group named okta-group-vault-developer that is assigned the vault-policy-developer-read policy.

    $ tee okta-group-vault-developer.json <<EOF
    {
       "name": "okta-group-vault-developer",
       "policies": ["vault-policy-developer-read"],
       "type": "external",
       "metadata": {
          "responsibility": "okta-group-vault-developer"
       }
    }
    EOF
    
  4. Create an external group with the group definition in okta-group-vault-developer.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @okta-group-vault-developer.json \
          $VAULT_ADDR/v1/identity/group | jq
    

    Example output:

    {
      "request_id": "d838f77e-78a8-a99d-11c5-1207af5fee71",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "name": "okta-group-vault-developer"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  5. Create a variable named GROUP_ID to store the id of the okta-group-vault-developer group.

    $ GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/identity/group/name/okta-group-vault-developer | jq '.data | .id' -r)
    
  6. Create a variable named OIDC_AUTH_ACCESSOR to store the accessor of the oidc authentication method.

    $ OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
    
  7. Create an API request payload to create a group aliases named okta-group-vault-developer.

    $ tee alias-okta-group-vault-developer.json <<EOF
    {
       "canonical_id": "$GROUP_ID",
       "mount_accessor": "$OIDC_AUTH_ACCESSOR",
       "name": "okta-group-vault-developer"
    }
    EOF
    
  8. Create the okta-group-vault-developer group alias.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST -s \
          --data @alias-okta-group-vault-developer.json \
          $VAULT_ADDR/v1/identity/group-alias | jq
    

    Example output:

    {
      "request_id": "47ac206f-a8f0-4a5a-9a6c-dc47c9dad13c",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "canonical_id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "id": "4a162d55-6251-d06a-9ca5-44989ea51bbc"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  9. Log in with the oidc method as role of a vault-role-okta-group-vault-developer.

    $ vault login -method=oidc role="vault-role-okta-group-vault-developer"
    

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=nrGkYnADoppFFE178nqAFCEWVgdAtfI4dfPUCq02-XQ&code_challenge_method=S256&nonce=n_3wJiZO1Cw7RAkAlJPopT&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_SgutWmHE7iYI77OJADjq
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.BD3wle0TOEQjUtLMNOPQ4g.sbjr6
    token_accessor       ouO1ITwC3YlxI4rfRSTUVh37.sbjr6
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-developer-read"]
    policies             ["default" "vault-policy-developer-read"]
    token_meta_role      vault-role-okta-group-vault-developer
    

    The returned token inherits the default policy and is assigned the vault-policy-developer-read policy because the value okta-group-vault-developer matches the Okta group the user is assigned. The browser session inherited the previous Okta login for the user bill@example.com.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

  10. Because you will be logging in as a new user to demonstrate different policies being used for different groups you need to log out of the Okta session in your browser.

    Navigate to your Okta domain. You can retrieve this from the Okta dashboard or run echo $OKTA_DOMAIN to retrieve the environment variable. You should be automatically logged into the My Apps page for the user bill@example.com. Click on bill in the top right corner of the page and then click Sign out.

  11. Create an API request payload for the okta-group-vault-admins role.

    $ tee vault-role-okta-group-vault-admins.json << EOF
    {
          "bound_audiences": "$OKTA_CLIENT_ID",
          "allowed_redirect_uris": [
             "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback",
             "http://localhost:8250/oidc/callback"
          ],
          "user_claim": "sub",
          "token_policies": ["default"],
          "oidc_scopes": "groups",
          "groups_claim": "groups"
    }
    EOF
    
  12. Create a role named vault-role-okta-group-vault-admins.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @vault-role-okta-group-vault-admins.json \
          $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-admins
    
  13. Create an API request payload that defines a Vault group named okta-group-vault-admins that is assigned the vault-policy-admin policy.

    $ tee okta-group-vault-admins.json <<EOF
    {
       "name": "okta-group-vault-admins",
       "policies": ["vault-policy-admin"],
       "type": "external",
       "metadata": {
          "responsibility": "okta-group-vault-admins"
       }
    }
    EOF
    
  14. Create an external group with the group definition in okta-group-vault-admins.json.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST \
          --data @okta-group-vault-admins.json \
          $VAULT_ADDR/v1/identity/group | jq
    

    Example output:

    {
      "request_id": "d838f77e-78a8-a99d-1234-1207abcde71",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "name": "okta-group-vault-admins"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  15. Create a variable named GROUP_ID to store the id of the okta-group-vault-admins group.

    $ GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/identity/group/name/okta-group-vault-admins | jq '.data | .id' -r)
    
  16. Create a variable named OIDC_AUTH_ACCESSOR to store the accessor of the oidc authentication method.

    $ OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
       $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
    
  17. Create an API request payload to create a group alias named okta-group-vault-admins.

    $ tee alias-okta-group-vault-admins.json <<EOF
    {
       "canonical_id": "$GROUP_ID",
       "mount_accessor": "$OIDC_AUTH_ACCESSOR",
       "name": "okta-group-vault-admins"
    }
    EOF
    
  18. Create the okta-group-vault-admins group alias.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
          --request POST -s \
          --data @alias-okta-group-vault-admins.json \
          $VAULT_ADDR/v1/identity/group-alias | jq
    

    Example output:

    {
      "request_id": "47ac206f-a8f0-1b3d-9a6c-dc47c9dad13c",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "canonical_id": "c6ec755e-4c0f-5fdf-b5da-1cb05a599cea",
        "id": "4a162d55-6251-d06a-9ca5-44989ea51bbc"
      },
      "wrap_info": null,
      "warnings": null,
      "auth": null
    }
    
  19. Log in with the oidc method as role of a vault-role-okta-group-vault-admins.

    $ vault login -method=oidc role="vault-role-okta-group-vault-admins"
    
  20. A new browser window will open. Log in as thea@example.com and the password Password1!.

    Example output:

    Complete the login via your OIDC provider. Launching browser to:
    
        https://<youroktaurl>.okta.com/oauth2/v1/authorize?client_id=0oa4e2310bkQSHsUO5d7&code_challenge=nrGkYnADoppFFE178nqAFCEWVgdAtfI4dfPUCq02-XQ&code_challenge_method=S256&nonce=n_3wJiZO1Cw7RAkAlJPopT&redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&response_type=code&scope=openid+groups&state=st_SgutWmHE7iYI77OJADjq
    
    WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
    over the value set by this command. To use the value set by this command,
    unset the VAULT_TOKEN environment variable or set it to the token displayed
    below.
    
    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.BD3wle0TOEQjUtLMNOPQ4g.sbjr6
    token_accessor       ouO1ITwC3YlxI4rfRSTUVh37.sbjr6
    token_duration       1h
    token_renewable      true
    token_policies       ["default"]
    identity_policies    ["vault-policy-admin"]
    policies             ["default" "vault-policy-admin"]
    token_meta_role      vault-role-okta-group-vault-admins
    

    The returned token inherits the default policy and is assigned the vault-policy-admin policy because the value okta-group-vault-admins matches the Okta group the user is assigned.

    If you receive an error message, please refer to the Troubleshooting section at the end of this tutorial.

Troubleshooting

When configuring OIDC, configuration settings must be configured as documented, otherwise you may experience errors when authenticating. Below are some common error messages and how to troubleshoot them.

Error authenticating: Error making API request.

Namespace: admin/
URL: GET https:/<yourvaultdomain>:8200/v1/auth/oidc/oidc/callback?client_nonce=grOGC4BQQfBiPyp3u2Ke&code=rsGK0Wza8MNTEGSAj02dfmb1Gn9qfCCpWLPZHEKSbB0&id_token=&state=st_1YRKVLiTrbwiLOVjlmEU
Code: 400. Errors:

* Vault login failed. Error exchanging oidc code: "Provider.Exchange: unable to exchange auth code with provider: oauth2: cannot fetch token: 401 Unauthorized\nResponse: {\"error\":\"invalid_client\",\"error_description\":\"The client secret supplied for a confidential client is invalid.\"}".

Problem: Client ID or client secret from Okta does not match config for the Vault role.
echo $OKTA_CLIENT_ID

Problem: This error can occur if the configuration for the Vault OIDC provider does not match the configuration provided by Okta.

Troubleshooting steps:

  1. Check the Okta client ID.

    echo $OKTA_CLIENT_ID
    

    Verify it matches the client ID from the Okta admin portal > Applications > Applications > hcp-vault.

  2. Check the Okta client secret.

    echo $OKTA_CLIENT_SECRET
    

    Verify it matches the client ID from the Okta admin portal > Applications > Applications > hcp-vault.

  3. Check the Okta domain.

    echo $OKTA_DOMAIN
    

    Verify it matches the client ID from the Okta admin portal > Applications > Applications > hcp-vault.

Error authenticating: Error making API request

Namespace: admin/
URL: GET https://<yourvaultdomain>:8200/v1/auth/oidc/oidc/callback?client_nonce=LKJDKLSJLKJFKLD<snip>_token=&state=st_klasjflkasjflkdas
Code: 400. Errors: failed to fetch groups" "groups" claim not found in token

Problem: This error can occur for several reasons. The most common is you are logged into your Okta domain with a user that is not assigned to the hcp-vault application or assigned to one of the groups.

For example, you may be logged into your Okta domain as bill@example.com and trying to login in as with okta-group-vault-admins group which Bill is not a member of, or you are logged in as an Okta administrator user that was performing the OIDC configuration but trying to log in to Vault with the OIDC auth method.

Troubleshooting steps:

  1. Verify you are not logged into Okta by opening a browser tab and navigating to https://<youroktadomain>.okta.com.

  2. If you are presented with a login form, proceed to the next step. If you are logged into Okta, click the user menu in the top right and select Sign out.

  3. To verify your claims are setup properly, log into Okta as an administrator and navigate to Security > API and click on the default authorization server.

  4. Click the Token preview tab. Fill in the Request Properties tab as follows:

    • OAuth/OIDC client: hcp-vault (type, then click the tile when it appears)
    • Grant type: Implicit (hybrid)
    • User: Thea Example (thea@example.com) (type, the click the tile when it appears)
    • Response type: id_token
    • Scopes: profile (type, then click the tile when it appears), openid (type, then click the tile when it appears)
  5. Click the Preview Token button.

    The "Payload" section should display JSON that includes the groups key.

    "groups": [
       "okta-group-vault-admins"
       ]
    

    If the groups claim appears, you may have not included the claim in the okta role configuration, or you may have duplicate applications with the same name.

Cleanup

To avoid any additional charges or access to your accounts you should consider following:

  • Delete any HCP Vault clusters used only for this tutorial.
  • Delete the Okta users thea@example.com and bill@example.com.
  • Delete the hc-vault Okta application.
  • Delete the groups claim added to the default Okta authorization server.
  • Unset the OKTA_DOMAIN, OKTA_CLIENT_ID, and OKTA_CLIENT_SECRET environment variables.
  • Unset the VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables for any deleted/unused HCP Vault clusters.

Next steps

In this tutorial, you learned how to create Okta groups and update the default authorization server to include a user's group membership in the ID Token, create and configure a new Okta application integration to support OpenID Connect, and configured HCP Vault to authenticate users and assign unique policies to users based on their Okta group membership.

To learn more about other auth methods, refer to the Auth Methods tutorial collection.

Help and reference

  • OIDC Auth Method
  • Vault OpenID Demo
 Previous
 Next

This tutorial also appears in:

  •  
    14 tutorials
    Auth Methods
    Vault clients must authenticate with Vault first and acquire a valid token. Learn available auth methods.
    • Vault

On this page

  1. OIDC Authentication with Okta
  2. Challenge
  3. Solution
  4. Prerequisites
  5. Lab setup
  6. Okta setup
  7. Configure Vault
  8. Login with OIDC
  9. Create an external Vault group
  10. Troubleshooting
  11. Cleanup
  12. Next steps
  13. Help and reference
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)