A new platform for documentation and tutorials is launching soon.

We are migrating Vault documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»OIDC Provider Configuration

This page collects high-level setup steps on how to configure an OIDC application for various providers. For more general usage and operation information, see the Vault JWT/OIDC method documentation.

OIDC providers are often highly configurable and you should become familiar with their recommended settings and best practices. The instructions below are largely community-driven and intended to help you get started. Corrections and additions may be submitted via the Vault Github repository.

»Azure Active Directory (AAD)

Note: Azure Active Directory Applications that have custom signing keys as a result of using the claims-mapping feature are currently not supported for OIDC authentication.

Reference: Azure Active Directory v2.0 and the OpenID Connect protocol

  1. Choose your Azure tenant.

  2. Go to Azure Active Directory and register an application for Vault.

  3. Add Redirect URIs with the "Web" type. You may include two redirect URIs, one for CLI access another one for Vault UI access.

  4. Record the "Application (client) ID" as you will need it as the oidc_client_id.

  5. Under Endpoints, copy the OpenID Connect metadata document URL, omitting the /well-known... portion.

  6. Under Certificates & secrets, add a client secret Record the secret's value as you will need it as the oidc_client_secret for Vault.

»Connect AD group with Vault external group

Reference: Azure Active Directory with OIDC Auth Method and External Groups

To connect the AD group with a Vault external groups, you will need Azure AD v2.0 endpoints. You should set up a Vault policy for the Azure AD group to use.

  1. Go to Azure Active Directory and choose your Vault application.

  2. Go to Token configuration and Add groups claim. Select "All" or "SecurityGroup" based on which groups for a user you want returned in the claim.

  3. In Vault, enable the OIDC auth method.

  4. Configure the OIDC auth method with the oidc_client_id (application ID), oidc_client_secret (client secret), and oidc_discovery_url (endpoint URL) you recorded from Azure.

    vault write auth/oidc/config \
   oidc_client_id="your_client_id" \
   oidc_client_secret="your_client_secret" \
   default_role="your_default_role" \
   oidc_discovery_url="https://login.microsoftonline.com/tenant_id/v2.0"

    vault write auth/oidc/config \
   oidc_client_id="your_client_id" \
   oidc_client_secret="your_client_secret" \
   default_role="your_default_role" \
   oidc_discovery_url="https://login.microsoftonline.com/tenant_id/v2.0"

  5. Configure the OIDC Role with the following:

    vault write auth/oidc/role/your_default_role \
   user_claim="email" \
   allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
   groups_claim="groups" \
   oidc_scopes="https://graph.microsoft.com/.default" \
   policies=default

    vault write auth/oidc/role/your_default_role \
   user_claim="email" \
   allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
   groups_claim="groups" \
   oidc_scopes="https://graph.microsoft.com/.default" \
   policies=default

  6. In Vault, create the external group. Record the group ID as you will need it for the group alias.

  7. From Vault, retrieve the OIDC accessor ID from the OIDC auth method as you will need it for the group alias's mount_accessor.

  8. Go to the Azure AD Group you want to attach to Vault's external group. Record the objectId as you will need it as the group alias name in Vault.

  9. In Vault, create a group alias for the external group and set the objectId as the group alias name.

    vault write identity/group-alias \
   name="your_ad_group_object_id" \
   mount_accessor="vault_oidc_accessor_id" \
   canonical_id="vault_external_group_id"

    vault write identity/group-alias \
   name="your_ad_group_object_id" \
   mount_accessor="vault_oidc_accessor_id" \
   canonical_id="vault_external_group_id"

»Optional Azure-specific Configuration

If a user is a member of more than 200 groups (directly or indirectly), extra configuration is required so that Vault can fetch the groups properly.

  • In Azure, under the applications API Permissions, grant the following permissions:

  • In Vault, set "provider_config" to Azure.

    vault write auth/oidc/config -<<"EOH"
{
   "oidc_client_id": "your_client_id",
   "oidc_client_secret": "your_client_secret",
   "default_role": "your_default_role",
   "oidc_discovery_url": "https://login.microsoftonline.com/tenant_id/v2.0",
   "provider_config": {
      "provider": "azure"
   }
}
EOH

    vault write auth/oidc/config -<<"EOH"
{
   "oidc_client_id": "your_client_id",
   "oidc_client_secret": "your_client_secret",
   "default_role": "your_default_role",
   "oidc_discovery_url": "https://login.microsoftonline.com/tenant_id/v2.0",
   "provider_config": {
      "provider": "azure"
   }
}
EOH

  • In Vault, add "profile" to oidc_scopes so the user's id comes back on the JWT.

    vault write auth/oidc/role/your_default_role \
 user_claim="email" \
 allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
 groups_claim="groups" \
 oidc_scopes="profile" \
 policies="default"

    vault write auth/oidc/role/your_default_role \
 user_claim="email" \
 allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
 groups_claim="groups" \
 oidc_scopes="profile" \
 policies="default"

»Auth0

  1. Select Create Application (Regular Web App).
  2. Configure Allowed Callback URLs.
  3. Copy client ID and secret.
  4. If you see Vault errors involving signature, check the application's Advanced > OAuth settings and verify that signing algorithm is "RS256".

»ForgeRock

  1. Navigate to Applications -> OAuth 2.0 -> Clients in ForgeRock Access Management.
  2. Create new client.
  3. Configure Client ID, Client Secret, Scopes and Redirection URIs.
  4. Save Client ID and Client Secret.

»Configuration

  1. In Vault, enable the OIDC auth method.

  2. Configure the OIDC auth method with the oidc_client_id (client ID), oidc_client_secret (client secret), and oidc_discovery_url (endpoint URL) from ForgeRock.

    vault write auth/oidc/config \
   oidc_client_id="your_client_id" \
   oidc_client_secret="your_client_secret" \
   default_role="your_default_role" \
   oidc_discovery_url="https://openam.example.com:8443/openam/oauth2"

    vault write auth/oidc/config \
   oidc_client_id="your_client_id" \
   oidc_client_secret="your_client_secret" \
   default_role="your_default_role" \
   oidc_discovery_url="https://openam.example.com:8443/openam/oauth2"

  3. Configure the OIDC Role with the following:

    vault write auth/oidc/role/your_default_role \
   user_claim="sub" \
   allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
   oidc_scopes="your_oidc_scopes" \
   policies=default

    vault write auth/oidc/role/your_default_role \
   user_claim="sub" \
   allowed_redirect_uris="http://localhost:8250/oidc/callback,https://online_version_hostname:port_number/ui/vault/auth/oidc/oidc/callback"  \
   oidc_scopes="your_oidc_scopes" \
   policies=default

»Gitlab

  1. Visit Settings > Applications.
  2. Fill out Name and Redirect URIs.
  3. Making sure to select the "openid" scope.
  4. Copy client ID and secret.

»Google

Main reference: Using OAuth 2.0 to Access Google APIs

  1. Visit the Google API Console.
  2. Create or a select a project.
  3. Create a new credential via Credentials > Create Credentials > OAuth Client ID.
  4. Configure the OAuth Consent Screen. Application Name is required. Save.
  5. Select application type: "Web Application".
  6. Configure Authorized Redirect URIs.
  7. Save client ID and secret.

»Optional Google-specific Configuration

Google-specific configuration is available when using Google as an identity provider from the Vault JWT/OIDC auth method. The configuration allows Vault to obtain Google Workspace group membership and user information during the JWT/OIDC authentication flow. The group membership obtained from Google Workspace may be used for Identity group alias association. The user information obtained from Google Workspace can be used to copy claims data into resulting auth token and alias metadata via claim_mappings.

»Setup

To set up the Google-specific handling, you'll need:

The Google-specific handling that's used to fetch Google Workspace groups and user information in Vault uses Google Workspace Domain-Wide Delegation of Authority for authentication and authorization. You need to follow all steps in the guide to obtain the key file for a Google service account capable of making requests to the Google Workspace User Accounts and Groups APIs.

In step 5 within the section titled Delegate domain-wide authority to your service account, the only OAuth scopes that should be granted are:

This is an important security step in order to give the service account the least set of privileges that enable the feature.

The Google service account key file obtained from the steps in the guide must be made available on the host that Vault is running on.

»Configuration

  • provider (string: <required>) - Name of the provider. Must be set to "gsuite".
  • gsuite_service_account (string: <required>) - Either the path to or the contents of a Google service account key file in JSON format. If given as a file path, it must refer to a file that's readable on the host that Vault is running on. If given directly as JSON contents, the JSON must be properly escaped.
  • gsuite_admin_impersonate (string: <required>) - Email address of a Google Workspace admin to impersonate.
  • fetch_groups (bool: false) - If set to true, groups will be fetched from Google Workspace.
  • fetch_user_info (bool: false) - If set to true, user info will be fetched from Google Workspace using the configured user_custom_schemas.
  • groups_recurse_max_depth (int: <optional>) - Group membership recursion max depth. Defaults to 0, which means don't recurse.
  • user_custom_schemas (string: <optional>) - Comma-separated list of Google Workspace custom schemas. Values set for Google Workspace users using custom schema fields will be fetched and made available as claims that can be used with claim_mappings. Required if fetch_user_info is set to true.

Example configuration:

vault write auth/oidc/config -<<EOF
{
    "oidc_discovery_url": "https://accounts.google.com",
    "oidc_client_id": "your_client_id",
    "oidc_client_secret": "your_client_secret",
    "default_role": "your_default_role",
    "provider_config": {
        "provider": "gsuite",
        "gsuite_service_account": "/path/to/service-account.json",
        "gsuite_admin_impersonate": "admin@gsuitedomain.com",
        "fetch_groups": true,
        "fetch_user_info": true,
        "groups_recurse_max_depth": 5,
        "user_custom_schemas": "Education,Preferences"
    }
}
EOF

vault write auth/oidc/config -<<EOF
{
    "oidc_discovery_url": "https://accounts.google.com",
    "oidc_client_id": "your_client_id",
    "oidc_client_secret": "your_client_secret",
    "default_role": "your_default_role",
    "provider_config": {
        "provider": "gsuite",
        "gsuite_service_account": "/path/to/service-account.json",
        "gsuite_admin_impersonate": "admin@gsuitedomain.com",
        "fetch_groups": true,
        "fetch_user_info": true,
        "groups_recurse_max_depth": 5,
        "user_custom_schemas": "Education,Preferences"
    }
}
EOF

»Role

The user_claim value of the role must be set to one of either sub or email for the Google Workspace group and user information queries to succeed.

Example role:

vault write auth/oidc/role/your_default_role \
    allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback" \
    user_claim="sub" \
    groups_claim="groups" \
    claim_mappings="/Education/graduation_date"="graduation_date" \
    claim_mappings="/Preferences/shirt_size"="shirt_size"

vault write auth/oidc/role/your_default_role \
    allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback" \
    user_claim="sub" \
    groups_claim="groups" \
    claim_mappings="/Education/graduation_date"="graduation_date" \
    claim_mappings="/Preferences/shirt_size"="shirt_size"

»Keycloak

  1. Select/create a Realm and Client. Select a Client and visit Settings.
  2. Client Protocol: openid-connect
  3. Access Type: confidential
  4. Standard Flow Enabled: On
  5. Configure Valid Redirect URIs.
  6. Save.
  7. Visit Credentials. Select Client ID and Secret and note the generated secret.

»Kubernetes

Kubernetes can function as an OIDC provider such that Vault can validate its service account tokens using JWT/OIDC auth.

Note: The JWT auth engine does not use Kubernetes' TokenReview API during authentication, and instead uses public key cryptography to verify the contents of JWTs. This means tokens that have been revoked by Kubernetes will still be considered valid by Vault until their expiry time. To mitigate this risk, use short TTLs for service account tokens or use Kubernetes auth which does use the TokenReview API.

»Using service account issuer discovery

When using service account issuer discovery, you only need to provide the JWT auth mount with an OIDC discovery URL, and sometimes a TLS certificate authority to trust. This makes it the most straightforward method to configure if your Kubernetes cluster meets the requirements.

Kubernetes cluster requirements:

  • ServiceAccountIssuerDiscovery feature enabled.
    • Present from 1.18, defaults to enabled from 1.20.
  • kube-apiserver's --service-account-issuer flag is set to a URL that is reachable from Vault. Public by default for most managed Kubernetes solutions.
  • Must use short-lived service account tokens when logging in.
    • Tokens mounted into pods default to short-lived from 1.21.

Configuration steps:

  1. Ensure OIDC discovery URLs do not require authentication, as detailed here:

    kubectl create clusterrolebinding oidc-reviewer  \
   --clusterrole=system:service-account-issuer-discovery \
   --group=system:unauthenticated

    kubectl create clusterrolebinding oidc-reviewer  \
   --clusterrole=system:service-account-issuer-discovery \
   --group=system:unauthenticated

  2. Find the issuer URL of the cluster.

    ISSUER="$(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')"

    ISSUER="$(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')"

  3. Enable and configure JWT auth in Vault.

    1. If Vault is running in Kubernetes:

      kubectl exec vault-0 -- vault auth enable jwt
kubectl exec vault-0 -- vault write auth/jwt/config \
   oidc_discovery_url=https://kubernetes.default.svc.cluster.local \
   oidc_discovery_ca_pem=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

      kubectl exec vault-0 -- vault auth enable jwt
kubectl exec vault-0 -- vault write auth/jwt/config \
   oidc_discovery_url=https://kubernetes.default.svc.cluster.local \
   oidc_discovery_ca_pem=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

    2. Alternatively, if Vault is not running in Kubernetes:

      Note: When Vault is outside the cluster, the $ISSUER endpoint below may or may not be reachable. If not, you can configure JWT auth using jwt_validation_pubkeys instead.

      vault auth enable jwt
vault write auth/jwt/config oidc_discovery_url="${ISSUER}"

      vault auth enable jwt
vault write auth/jwt/config oidc_discovery_url="${ISSUER}"

  4. Configure a role and log in as detailed below.

»Using JWT validation public keys

This method can be useful if Kubernetes' API is not reachable from Vault or if you would like a single JWT auth mount to service multiple Kubernetes clusters by chaining their public signing keys.

Kubernetes cluster requirements:

  • ServiceAccountIssuerDiscovery feature enabled.
    • Present from 1.18, defaults to enabled from 1.20.
    • This requirement can be avoided if you can access the Kubernetes master nodes to read the public signing key directly from disk at /etc/kubernetes/pki/sa.pub. In this case, you can skip the steps to retrieve and then convert the key as it will already be in PEM format.
  • Must use short-lived service account tokens when logging in.
    • Tokens mounted into pods default to short-lived from 1.21.

Configuration steps:

  1. Fetch the service account signing public key from your cluster's JWKS URI.

    # Query the jwks_uri specified in /.well-known/openid-configuration
kubectl get --raw "$(kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri' | sed -r 's/.*\.[^/]+(.*)/\1/')"

    # Query the jwks_uri specified in /.well-known/openid-configuration
kubectl get --raw "$(kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri' | sed -r 's/.*\.[^/]+(.*)/\1/')"

  2. Convert the keys from JWK format to PEM. You can use a CLI tool or an online converter such as this one.

  3. Configure the JWT auth mount with those public keys.

    vault write auth/jwt/config \
   jwt_validation_pubkeys="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9...
-----END PUBLIC KEY-----","-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9...
-----END PUBLIC KEY-----"

    vault write auth/jwt/config \
   jwt_validation_pubkeys="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9...
-----END PUBLIC KEY-----","-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9...
-----END PUBLIC KEY-----"

  4. Configure a role and log in as detailed below.

»Creating a role and logging in

Once your JWT auth mount is configured, you're ready to configure a role and log in. The following assumes you use the projected service account token available in all pods by default. See Specifying TTL and audience below if you'd like to control the audience or TTL.

  1. Choose any value from the array of default audiences. In these examples, there is only one audience in the aud array, https://kubernetes.default.svc.cluster.local.

    To find the default audiences, either create a fresh token (requires kubectl v1.24.0+):

    $ kubectl create token default | cut -f2 -d. | base64 --decode
{"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

    $ kubectl create token default | cut -f2 -d. | base64 --decode
{"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

    Or read a token from a running pod's filesystem:

    $ kubectl exec my-pod -- cat /var/run/secrets/kubernetes.io/serviceaccount/token | cut -f2 -d. | base64 --decode
{"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

    $ kubectl exec my-pod -- cat /var/run/secrets/kubernetes.io/serviceaccount/token | cut -f2 -d. | base64 --decode
{"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

  2. Create a role for JWT auth that the default service account from the default namespace can use.

    vault write auth/jwt/role/my-role \
   role_type="jwt" \
   bound_audiences="<AUDIENCE-FROM-PREVIOUS-STEP>" \
   user_claim="sub" \
   bound_subject="system:serviceaccount:default:default" \
   policies="default" \
   ttl="1h"

    vault write auth/jwt/role/my-role \
   role_type="jwt" \
   bound_audiences="<AUDIENCE-FROM-PREVIOUS-STEP>" \
   user_claim="sub" \
   bound_subject="system:serviceaccount:default:default" \
   policies="default" \
   ttl="1h"

  3. Pods or other clients with access to a service account JWT can then log in.

    vault write auth/jwt/login \
   role=my-role \
   jwt=@/var/run/secrets/kubernetes.io/serviceaccount/token
# OR equivalent to:
curl \
   --fail \
   --request POST \
   --header "X-Vault-Request: true" \
   --data '{"jwt":"<JWT-TOKEN-HERE>","role":"my-role"}' \
   "${VAULT_ADDR}/v1/auth/jwt/login"

    vault write auth/jwt/login \
   role=my-role \
   jwt=@/var/run/secrets/kubernetes.io/serviceaccount/token
# OR equivalent to:
curl \
   --fail \
   --request POST \
   --header "X-Vault-Request: true" \
   --data '{"jwt":"<JWT-TOKEN-HERE>","role":"my-role"}' \
   "${VAULT_ADDR}/v1/auth/jwt/login"

»Specifying TTL and audience

If you would like to specify a custom TTL or audience for service account tokens, the following pod spec illustrates a volume mount that overrides the default admission injected token. This is especially relevant if you are unable to disable the --service-account-extend-token-expiration flag for kube-apiserver and want to use short TTLs.

When using the resulting token, you will need to set bound_audiences=vault when creating roles in Vault's JWT auth mount.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  # automountServiceAccountToken is redundant in this example because the
  # mountPath used overlaps with the default path. The overlap stops the default
  # admission injected token from being created. You can use this option to
  # ensure only a single token is mounted if you choose a different mount path.
  automountServiceAccountToken: false
  containers:
    - name: nginx
      image: nginx
      volumeMounts:
      - name: custom-token
        mountPath: /var/run/secrets/kubernetes.io/serviceaccount
  volumes:
  - name: custom-token
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          expirationSeconds: 600 # 10 minutes is the minimum TTL
          audience: vault        # Must match your JWT role's `bound_audiences`
      # The remaining sources are included to mimic the rest of the default
      # admission injected volume.
      - configMap:
          name: kube-root-ca.crt
          items:
          - key: ca.crt
            path: ca.crt
      - downwardAPI:
          items:
          - fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
            path: namespace

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  # automountServiceAccountToken is redundant in this example because the
  # mountPath used overlaps with the default path. The overlap stops the default
  # admission injected token from being created. You can use this option to
  # ensure only a single token is mounted if you choose a different mount path.
  automountServiceAccountToken: false
  containers:
    - name: nginx
      image: nginx
      volumeMounts:
      - name: custom-token
        mountPath: /var/run/secrets/kubernetes.io/serviceaccount
  volumes:
  - name: custom-token
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          expirationSeconds: 600 # 10 minutes is the minimum TTL
          audience: vault        # Must match your JWT role's `bound_audiences`
      # The remaining sources are included to mimic the rest of the default
      # admission injected volume.
      - configMap:
          name: kube-root-ca.crt
          items:
          - key: ca.crt
            path: ca.crt
      - downwardAPI:
          items:
          - fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
            path: namespace

»Okta

  1. Make sure an Authorization Server has been created. The "Issuer" field shown on the Setting page will be used as the oidc_discovery_url.
  2. Visit Applications > Add Application (Web).
  3. Configure Login redirect URIs. Save.
  4. Save client ID and secret.

Note your policy will need oidc_scopes to include profile to get a full profile ("Fat Token"). You will also need to configure bound audience along the lines of "bound_audiences": ["api://default", "0a4........."] if you are using the default authorization server.