Managing OAuth 2.0 Client Credentials

Today, several security issues and concerns could exist with using a standard API key implementation. OneTrust is committed to providing more secure solutions and supports the OAuth 2.0 authorization framework for a more advanced approach to external application access.

Note:

A maximum of 500 OAuth 2.0 client credentials can be created per account.

Using Client Credentials

You can create and manage client credentials that utilize the OAuth 2.0 authorization framework using the Client credentials screen in Global Settings. When creating client credentials, you must be mindful of the organization in which you are creating them given that client credentials are assigned to the organization in which they are created. This means that APIs called using the client credentials will only be able to return objects accessible by the organizational group in which the client credentials were created.

Client credentials that appear on the Client credentials screen also depend on the organization in which you are currently logged in. For example, say your organizational hierarchy contains a root organization named Global and two child organizations named North America and Europe. If you are currently within the Global organization, you will be able to see all client credentials created within the Global, North America, and Europe organizations. However, if you navigate to the North America organization, you will only be able to see client credentials created in the North America organization and will not have visibility into client credentials created in the Europe organization or Global organization.

Note:

When viewing client credentials within the root organization, there is currently no way to identify in which organization each client credential was created on the Client credentials screen. However, you can navigate to other sub-organizations to locate specific client credentials to determine in which organization it was created. Alternatively, you can incorporate the organization name within the name of the client credential to help you identify those details in the future.



Field
Description
Name

Name of the client credential. Click the link in the Name field to access the Client credential details screen.

Creation date

Date and time that the client credential was created.

Created by

Name of the user who created the client credential.

Client ID

Unique identifier for the client credential.

To create OAuth 2.0 client credentials

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Click the Add button. The Client credentials section of the Add client credential screen appears.


  4. In the Name field, enter a name for the client credential.
    Note:

    The name cannot be modified once the client credential is created.

  5. Optional: In the Description field, enter a description for the client credential.
  6. In the Access token lifetime field, select the amount of time that should pass before the access token expires. The following options are available:

    • 1 Hour

    • 1 Day

    • 1 Week

    • 1 Month

    • 1 Year

  7. Optional: Turn on the Restrict IP addresses setting to restrict incoming communication to specific IP addresses. If this setting is enabled, enter an IP address in the Restrict IP addresses field that appears. You can enter multiple IP addresses by clicking the Add icon and entering an additional IP address in the field that appears.
  8. Click the Next button. The Scope section appears.


  9. Select one or multiple check boxes to indicate the scope that matches the level of access you want to grant to an application.
  10. Click the Create button. The Client ID and secret section appears.


  11. In the Download credential field, click the Download button. A .txt file containing the Client ID and Client Secret details will download to your local system.
    Attention:

    The Client ID and Client Secret details should be saved to a secure location.

  12. Click the Close button.

To edit a client credential

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Click the link in the Name field for the client credential that you want to edit. The Client credential details screen appears.

  4. Click the Edit button. Editable fields become available.


  5. Modify the client credential details on the Details tab and the Scope tab, as needed.
    Note:

    Changes made to the Access token lifetime and the Scope will only affect new access tokens and will not affect existing access tokens. Changes made to the Restricted IP addresses will apply to both existing and new access tokens. In addition, the client credential name and client ID cannot be modified.

  6. Click the Save button.

To upload a mutual authentication certificate

Site Admins can upload a Mutual Transport Layer Security (mTLS) certificate for generated client credentials when using a custom branded URL.

Note:

For more information on custom subdomains, see Customizing OneTrust with a Custom Subdomain.

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Click the link in the Name field for the client credential for which you want to upload a Mutual Transport Layer Security (mTLS) certificate. The Client credential details screen appears.

  4. Click the Edit button. Editable fields become available.
  5. Turn on the Enable mutual authentication setting. The Mutual authentication certificate field appears.


  6. Click the Upload button. The Upload certificate modal appears.

  7. Click the Select file button and upload a valid X.509 certificate.
  8. Click the Save button. The details of the uploaded certificate appear.

To generate a token

Access tokens are used to authorize applications to access an API. Since API responses can contain user information, access tokens must be kept confidential and secure.

Note:

The following procedure details how to generate a token from within Global Settings in the OneTrust application. Alternatively, you can generate a token using the Generate Access Token API in the OneTrust Developer Portal.

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Hover over the client credential for which you want to generate a token, and click the Context Menu icon that appears.
  4. On the Context menu, select Generate token. The Access token modal appears.


  5. In the Client secret field, enter the Client Secret details that you previously saved when the client credential was created.
  6. Click the Generate button. The Access token field appears with the access token.

  7. Click the Copy button. The access token is copied to your computer's clipboard.
  8. Click the Close button.

To reset the Client Secret details

Client Secrets can be revoked, if necessary. For example, if the Client Secret was unintentionally exposed, you can reset the current Client Secret and download a new Client Secret using the following steps.

Note:

Resetting a Client Secret will not invalidate any access tokens. However, any existing integrations that use the old Client Secret will no longer work and will need to be updated.

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Hover over the client credential that you want to reset secret for, and click the Context Menu icon that appears.
  4. On the Context menu, select Reset. The Reset secret modal appears.
    Note:

    The Reset secret modal can also be accessed by clicking the Reset secret button on the Client credential details screen.



  5. Click the Reset button. The Client Reset Secret modal appears.


  6. In the Download credentials field, click the Download button. A .txt file containing the Client ID and Client Secret details downloads to your local system.
    Attention:

    The Client ID and Client Secret details should be saved to a secure location.

To delete a client credential

Client credentials can be deleted, if necessary. For example, if all previous access tokens need to be invalidated, you can delete the client credential using the following steps.

Note:

Deleting client credentials will invalidate any access tokens. Any existing integrations using the old client credentials will no longer work and will need to be updated.

  1. Click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Hover over the client credential that you want to delete, and click the Context Menu icon that appears.
  4. On the Context menu, select Delete. The Delete client credential modal appears.


  5. Click the Delete button.
    Note:

    Client credentials can also be deleted by clicking the Delete button on the Client credential details screen.

To use OAuth 2.0 Client Credentials to make calls for external system integrations