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

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

  1. Register or select an AAD application. Visit Overview page.
  2. Configure Redirect URIs ("Web" type).
    • You may include two redirect URIs, one for CLI access another one for Vault UI access.
      • http://localhost:8250/oidc/callback
      • https://hostname:port_number/ui/vault/auth/oidc/oidc/callback
  3. Record "Application (client) ID" as you will need it as the oidc_client_id
  4. Under API Permissions grant the following permission:
  5. Under "Endpoints", copy the OpenID Connect metadata document URL, omitting the /well-known... portion.
  6. Switch to Certificates & Secrets. Create a new client secret and record the generated value as it will not be accessible after you leave the page.

Please note Azure AD v2.0 endpoints are required for external groups to work.

  • groupMembershipClaims should be changed from none in the App registration manifest. Options are "All" or "SecurityGroup"

  • In the OIDC Role config the scope "https://graph.microsoft.com/.default" should be added to add groups to the jwt token and groups_claim should be set to groups.

  • Finally Azure AD group can be referenced by using the groups objectId as the group alias name for the external group.

»CLI setup instructions:

You have to fill in the following values make sure to use the correct vault secret path that matches the name of the authentication method such as /oidc/

  • oidc_client_id = Application Client ID
  • oidc_client_secret = Secret obtained from the Certificates & Secrets Section
  • default_role = default role the user will be using when connecting. (see the second command)
  • oidc_discovery_url = Open ID endpoint retrieved from the App Registration sections.
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/role/demo 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" \
    policies=default

»Azure-specific handling 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.

  • Set "provider_config" to azure (see below)
  • Grant the AAD application Directory.Read.All permission under "Azure Active Directory Graph" API Permissions (legacy API).
  • Add "profile" to oidc_scopes so the user's id comes back on the jwt token.
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/role/demo \
   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".

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

»Google-specific handling configuration

Provider specific configuration is available when using Google as an identity provider from the Vault JWT/OIDC auth method. The configuration allows Vault to obtain G Suite group membership and user information during the JWT/OIDC authentication flow. The group membership obtained from G Suite may be used for Identity group alias association. The user information obtained from G Suite 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 G Suite groups and user information in Vault uses G Suite 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 G Suite 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:

»Configuration

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

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"

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

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