Configuring OAuth 2.0 / OpenID Connect Profiles

In order to configure SSO, you must first create an OAuth 2.0 / OpenID Connect profile. Then, you must provision users to use the profile. The following article walks through the creation of an OAuth 2.0 / OpenID Connect profile.

Vault allows you to create multiple profiles and associate each with a different authorization server (AS). This allows users to authenticate with any AS configured on the security policy to which they are assigned. Note that Vault supports OpenID Connect with PingFederate, ADFS 4.0, and Okta Authorization Servers only.

Learn more about Supported IdPs/AS for Vault Products.

To create an OAuth 2.0 / OpenID Connect profile:

Go to Admin > Settings > OAuth 2.0 / OpenID Connect Profiles.
Click Create.
Enter a Label and Name for the profile.
Choose a Status for the profile. It’s best practice to leave the profile as Inactive until configuration is complete.
Optional: Add a description of the profile.
Under OAuth 2.0 / OpenID Connect Configuration, upload your AS Metadata with the Upload AS Metadata button. See details below.
Select an Authorization Server Provider from the drop-down. Starting with 20R2.2, the ADFS / Azure AD option is split into two: ADFS and Azure AD. ADFS exposes the value as ADFS, while Azure AD exposes the value as Azure.
Optional: If you selected ADFS in the previous step, you can choose the Preferred Authentication Library. The default value is MSAL (ADFS 2019 or later). We recommend selecting MSAL for ADFS 2019 or later, and ADAL otherwise. This setting is used by Vault File Manager to load the appropriate Microsoft Authentication Library at the runtime. Selecting the wrong option may prevent the use of advanced configurations options on the IDP side such as custom claims.
Optional: Enter an Access Token JWKS Endpoint. This option is only available when you select PingFederate in the previous step. This field has a 500-character limit. See details below.
Select an Identity Claim. Choose Identity is in the “sub” claim to allow the AS to provide the unique user identifier in the ‘sub” claim of the id_token or access_token by default. If you select Identity is in another claim, enter the alternative claim key in the Claim field. This field has a 100-character limit. See details below.
Select a User ID Type, either Vault User Name or Federated ID. See details below.
Optional: Select the Perform strict Audience Restriction validation checkbox to enable audience restriction validation. See details below.
Optional: Under Client Applications, click Add and complete the required fields to set up client ID mappings between Authorization Servers and client applications. See details below.
Click Save.

Note: It is recommended that customers use OAuth 2.0 with PKCE enabled. Customers accept and assume responsibility for risks associated with using an ADAL solution.

About the PingFederate Authorization Server

When you select PingFederate from the Authorization Server Provider drop-down, Vault displays the optional Access Token JWKS Endpoint field. This field accepts an HTTPS URL formatted string of the authorization server JSON Web Key Set (JWKS) that Vault uses to obtain signature validation keys for access_tokens. This endpoint is in addition to the JWKS endpoint specified in the AS Metadata, which Vault uses to validate signatures on id_tokens.

Upload Authentication Server Metadata

You can upload your Authentication Server metadata by either uploading an AS Metadata JSON file or specifying a URL where the data is available. Note that if you change your AS metadata, you’ll need to import the updated AS metadata to the Vault OAuth/OpenID Connect profile.

To upload AS metadata:

Click the Upload AS Metadata button.
To import AS metadata by uploading a JSON file, select Authorization Server Metadata and then choose a file.
To import AS metadata by specifying a URL, select Provide Authorization Server Metadata URL and then enter the location of the file. This URL must use the HTTPS protocol.
Click Continue. Vault validates the contents of the AS Metadata JSON and returns an error message if the information is invalid.
To complete the configuration, click Save.

The JSON file structure is defined in the AS Metadata specifications.

The following metadata is required:

Metadata	Description
`issuer`	The authorization server's issuer identifier, which is a URL that uses the "`https`" scheme and has no query or fragment components.
`authorization_endpoint`	URL of the authorization server's authorization endpoint.
`token_endpoint`	URL of the authorization server's token endpoint.
`introspection_endpoint`	URL of the authorization server's OAuth 2.0 introspection endpoint. This is not required if your Authorization Server Provider is set to ADFS.
`jwks_uri`	URL of the authorization server's JSON Web Key Set (JWKS). This contains a set of public keys that are used to verify the JSON Web Token (JWT) issued by the authorization server. Note that you can specify an additional JWKS endpoint for validating `access_tokens` when selecting PingFederate as the Authorization Server Provider.

You may include any other optional metadata. The following metadata is optional, but recommended:

Metadata	Description
`scopes_supported`	JSON array containing a list of the OAuth 2.0 [`RFC6749`] "scope" values that this authorization server supports. Servers may choose not to advertise some supported scope values even when this parameter is used.

Identity Claims

Identity claim within id_token or access_token contain the identifier of the authenticated user. Typically, Authorization Servers provide a value that uniquely identifies an authenticated user in the “sub” (Subject) claim. However, Vault allows you to set an alternative claim within id_token(s) or access_token(s) to obtain a user’s identifier.

About User ID Types

The two options for User ID Type are Vault User Name and Federated ID.

Vault User Name

Choose Vault User Name if you plan to store the Vault user names as an attribute in your IdP user directory, or if the Vault user names happen to exactly match your enterprise user names. Basically, this puts the burden on the IdP to map enterprise user names to Vault user names.

Federated ID

Choose Federated ID if you plan to store enterprise user names in the Federated ID field on the Vault user profile. This puts the burden on Vault to map from enterprise user names to Vault user names.

ClientID Mapping

ClientID mapping allows Vault to manage mapping between the OAuth client IDs defined by Authorization Servers and the client IDs defined in the client applications. This enables Vault applications with built-in static client IDs, such as Vault File Manager and Veeva Snap, to integrate with Authorization Servers where the client IDs must be uniquely generated for each app.

Add a Client Application

To add a new client application:

Click the Add button beneath the Client Applications section.
Enter an Application Label for the application.
Enter an Application Client ID.
Enter an Authorization Server Client ID.
Optional: Enter Audience value. This field is only applicable if audience restriction validation is enabled.
Click Ok.

Edit a Client Application

To edit an existing client application, hover over Application Label and click Edit from the Actions menu. The Edit menu allows you to update the required fields for the application. You can also choose Delete from the Actions menu to delete a client application.

Audience and Client ID Validation

During OAuth token validation, Vault uses audience restriction validation to ensure that tokens generated by Authorization Servers and presented by the client application are intended for a specific OAuth 2.0 / OpenID Connect profile. Tokens only pass validation if they are intended for use by client applications communicating with Vault.

To enable audience validation, select the Perform strict Audience Restriction validation checkbox from the OAuth 2.0 / OpenID Connect Profiles page.

How Audience Restriction Validation Works

The aud (audience) claim within a token specifies the intended recipient of the token. When an OAuth 2.0 / OpenID Connect profile receives a token, Vault reads the audience information from either the JWT (JSON Web Token) or from the token introspection response. We strongly recommend that Authorization Servers set the aud value to the client ID in the id_token and to the Resource Server URI in the access_token. In Vault, the Resource Server URI is unique for each OAuth 2.0 / OpenID Connect profile and is exposed as a Vault Session ID URL creating the profile.

Depending on whether an id_token or an access_token is presented to Vault for authentication, Vault uses either the Vault Session ID URL or an Audience value specified in the Client Applications mapping table to validate the audience restriction.

Vault executes the following validation steps during audience restriction validation:

Checks the presences of the aud claim in the tokens. If the claim is missing, Vault rejects the token.
Compares the Vault Session ID URL in the OAuth 2.0 / OpenID Connect profile receiving the request against the value extracted from the aud claim in the token. If the values don’t match, Vault proceeds validating the audience restriction against the Audience value specified in the Client Applications mapping table.
Reads the client ID and extracts it from the HTTP Request or the client_id claim in the token. If the client ID is missing, Vault rejects the token.
Attempt to locate a mapping record in the Client Applications mapping table in the OAuth 2.0 / OpenID Connect profile based on the client ID acquired in the previous step. Vault extracts the Audience value mapping record. If there is no matching mapping record based on the client ID, Vault rejects the token.
Lastly, Vault compares the Audience value to the value passed inside the aud claim in the token. If there is no Audience value in the mapping record, or if the value from the mapping record doesn’t match the value in the token, Vault rejects the token.

OAuth 2.0 / OpenID Connect Event Logging and Troubleshooting

Domain Administrators can capture the OAuth 2.0 / OpenID Connect authentication events to troubleshoot potential authentication or configuration issues through the Troubleshoot tab in the OAuth 2.0 / OpenID Connect Profile page. Each capture action logs events for up to ten (10) authentication requests.

Log Retention

Vault purges the captured log of events before each new capture action. Admins can manually purge the captured log of events as long as the capture action is not currently running.

Note that Vault no longer displays details of generic failed OAuth / OpenID Connect authentication attempts in Login History Audit logs. Vault logs the starting and stopping capturing in the Domain Audit History log.

Capturing Authentication Events

To capture OAuth / OpenID Connect Authentication Events:

From the OAuth 2.0 / OpenID Connect Profile page, click the Troubleshoot tab.
Optional: From the User field, select a user for which to capture a log of events. If you do not select a user, Vault captures the events for any user.
Optional: Enter a client ID in the Client ID field. If you do not provide a client ID, Vault captures the events for any client ID.
Click the Start Capture button to begin running the capturing process. If the profile contains events from a previous capture, Vault removes all existing events before the new capture starts and displays a dialog to confirm that you wish to continue. Vault logs any captured events in the Events table.
Optional: Click the Refresh button to refresh the Event table contents.

Stop Capturing Events

To stop capturing events, click the End Capture button and confirm in the dialog that you wish to continue.

About the Events Table

Vault displays any captured events in the Events table and includes the following columns:

Date UTC: The date and time of the request in UTC.
Transaction ID: The transaction ID of the event. The transaction ID is unique to each authentication request.
Message: The event description.
User: The user name associated with the captured event.
Client: The client ID associated with the captured event.
Event Data: The data used by the authentication event to perform validation. This column is only available for download as a CSV. You cannot add this column to the Event table.
Validation Status: The result of the event validation, or OK if validation succeeds.

Deleting Captured Events

To delete all captured events, select Delete All from the Actions menu. Click Yes in the dialog to confirm the action. You cannot undo this action.

CSV Exports

From the Event table’s Actions menu, you can choose to Export to CSV. The exported CSV includes all captured events, as well as the Event Data column, which does not exists in the Event table.