# 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](/en/lr/13977/). 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](/en/lr/52437/). To create an OAuth 2.0 / OpenID Connect profile: 1. Go to **Admin** > **Settings** > **OAuth 2.0 / OpenID Connect Profiles**. 2. Click **Create**. 3. Enter a **Label** and **Name** for the profile. 4. Choose a **Status** for the profile. It's best practice to leave the profile as _Inactive_ until configuration is complete. 5. Optional: Add a description of the profile. 6. Under **OAuth 2.0 / OpenID Connect Configuration**, upload your AS Metadata with the **Upload AS Metadata** button. See details [below][1]. 7. 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`. 8. 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. 9. 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][2]. 10. 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][3]. 11. Select a **User ID Type**, either _Vault User Name_ or _Federated ID_. See details [below][4]. 12. Optional: Select the **Perform strict Audience Restriction validation** checkbox to enable audience restriction validation. See details [below][5]. 13. 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][6]. 14. Click **Save**.
### About the PingFederate Authorization Server {#PingFederate} 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 {#upload_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: 1. Click the **Upload AS Metadata** button**.** 2. To import AS metadata by uploading a JSON file, select **Authorization Server Metadata** and then choose a file. 3. 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. 4. Click **Continue**. Vault validates the contents of the AS Metadata JSON and returns an error message if the information is invalid. 5. 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.
## Supported Signing Algorithms {#signing-algorithms} Vault supports the following signing algorithms: - `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` - (`ECDHE-ECDSA-CHACHA20-POLY1305`) - `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` - (`ECDHE-RSA-CHACHA20-POLY1305`) - `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` - (`ECDHE-ECDSA-AES256-GCM-SHA384`) - `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` - (`ECDHE-RSA-AES256-GCM-SHA384`) - `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` - (`ECDHE-ECDSA-AES128-GCM-SHA256`) - `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` - (`ECDHE-RSA-AES128-GCM-SHA256`) ## Identity Claims {#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 {#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 {#client-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](/en/lr/44346/), 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: 1. Click the **Add** button beneath the **Client Applications** section. 2. Enter an **Application Label** for the application. 3. Enter an **Application Client ID**. 4. Enter an **Authorization Server Client ID**. 5. Optional: Enter **Audience** value. This field is only applicable if audience restriction validation is enabled. 6. 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 {#audience_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: 1. Checks the presences of the aud claim in the tokens. If the claim is missing, Vault rejects the token. 2. 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. 3. 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. 4. 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. 5. 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 {#event_logging} 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][7] 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](/en/lr/14341/) log. ### Capturing Authentication Events To capture OAuth / OpenID Connect Authentication Events: 1. From the OAuth 2.0 / OpenID Connect Profile page, click the **Troubleshoot** tab. 2. 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. 3. 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. 4. 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. 5. 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 {#delete_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. [1]: #upload_metadata [2]: #PingFederate [3]: #identity-claims [4]: #user_id_types [5]: #audience_validation [6]: #client-mapping [7]: #delete_captured_events