Setting Up Mutual Transport Layer Security

Mutual Transport Layer Security (mTLS) offers a way for servers to verify the identity of the client application that is requesting information. With mTLS, the client application is required to send a client identity certificate to the server, which will be used to verify the client's identity. Mutual authentication adds an additional layer of security by ensuring that traffic is both secure and trusted in both directions between the client application and the server.

Terminology

The following are key terms used throughout this article:


Term	Description
Inbound	Traffic is coming into OneTrust APIs from client applications.
Outbound	Traffic is going to external client applications from OneTrust Integrations.

To configure inbound mTLS (into OneTrust)

Configuring inbound mTLS is an additional layer of security used when calling OneTrust APIs and Webhooks that allows the OneTrust Platform to verify that traffic coming into the OneTrust Platform is both secure and trusted. When mutual authentication is enabled, Site admins can upload a client identity certificate against the client credentials configuration. This allows OneTrust to achieve certificate pinning, which means that the certificate uploaded to OneTrust holds the public key used for digital signing at client side (using the corresponding private-public keypair). OneTrust makes use of standard mTLS at layer 4 (transport layer) and additionally completes certificate pinning verification in a callback at layer 7 (application layer) before allowing communication with the OneTrust Platform.

In order to configure inbound mTLS for when a client application initiates a connection with OneTrust, you must:

Have a custom domain targeted for the OneTrust Admin application instance: A custom domain is required to configure mTLS. You can either create a new account or convert an existing account to obtain a customer-specific custom domain. For more information, see Customizing OneTrust with a Custom Subdomain.
Update integrations with your custom URL: Once you have a custom domain, you must update your integrations to use your custom URL (i.e. youramazingcompany.my.onetrust.com) rather than the standard OneTrust assigned URL (i.e. app.onetrust.com).

JSON

curl --location --request GET 'https://trial.onetrust.com/api/scim/v2/Groups?startIndex=1&count=10' \

--header 'Authorization: Bearer {oauth_token}' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--cert /path/to/cert.pem \

--key /path/to/key.pem \

--pass {passcode}

curl --location --request GET 'https://trial.onetrust.com/api/scim/v2/Groups?startIndex=1&count=10' \

--header 'Authorization: Bearer {oauth_token}' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--cert /path/to/cert.pem \

--key /path/to/key.pem \

--pass {passcode}

Step 1: Create an OAuth 2.0 Client Credential

For more information, see Managing OAuth 2.0 Client Credentials.

Step 2: Upload a client identity certificate

Click the gear icon in the upper right-hand corner to access Global Settings.
On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.
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.
Click the Edit button. Editable fields become available.
Turn on the Enable Mutual Authentication setting. The Mutual Authentication Certificate field appears.
Click the Upload button. The Upload Certificate modal appears.
Click the Select File button and upload a valid X.509 certificate.
Click the Save button. The details of the uploaded certificate appear.

Step 3: Configure your API integration with the client credential

Configure your API integration to use the OAuth 2.0 Client Credential and sign all requests to the OneTrust Platform with the certificate you uploaded in step 2. If the signature matches that of the certificate uploaded for that client credential, access will be granted. If the signature does not match the uploaded certificate or is tampered, access will be denied.

The following is an example of a Client URL (cURL) request:

JSON

curl --location --request GET 'https://trial.onetrust.com/api/scim/v2/Groups?startIndex=1&count=10' \

--header 'Authorization: Bearer {oauth_token}' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--cert /path/to/cert.pem \

--key /path/to/key.pem \

--pass {passcode}

curl --location --request GET 'https://trial.onetrust.com/api/scim/v2/Groups?startIndex=1&count=10' \

--header 'Authorization: Bearer {oauth_token}' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--cert /path/to/cert.pem \

--key /path/to/key.pem \

--pass {passcode}

To configure outbound mTLS (from OneTrust Integrations module)

Configuring outbound mTLS allows external servers to verify that traffic coming from the OneTrust Platform is both secure and trusted. You can enable mTLS for all credentials with HTTP connector types to establish secure and trusted connections with external servers. This only applies to outbound connections made by actions in integrations which use this credential type.

In order to configure outbound mTLS for connections initiated by OneTrust, you must:

Step 1: Create an Integration Credential

Enable mutual transport layer security (mTLS) for any credential using the Web App connector type to establish secure and trusted connection with external servers. mTLS can be used as the only form of authentication by selecting Custom in the Auth Type field. Alternately, mTLS can be used as an additional form of authentication for any of the standard web app connector types.

For more information, see Configuring Integration Credentials.

Step 2: Configure mTLS authentication for the credential

Enable the mTLS enabled setting on the Enter Credential Details screen when creating an integration credential.

Note:
For existing credentials, navigate to the respective Credential Details screen for the integration credential, hover over the mTLS enabled field, and click the Edit icon. The fields become available. Then enable the mTLS enabled setting.
In the Client Certificate field, enter a RSA 2048 or above public key as X.509 v2/v3 in the PEM format.
In the Private Key field, enter an RSA PKCS#1 or PKCS#8 private key corresponding to your certificate.
(Optional) In the Private Key Passphrase field, provide a private key passphrase if the certificate is protected by a passphrase.
(Optional) In the Server Certificate Chain field, provide a server certificate chain in PEM format using SHA-256 or SHA-512 if the certificate is self-signed.
Click the Save button.

Step 3: Select the credential to authenticate one or more actions in your integration(s)

After you've configured credentials that will allow OneTrust to access the application for the integration, you can create integrations to bring together common actions in third-party systems with supplemental actions in the OneTrust Platform.

For more information, see Creating Integrations.

Note:

For outbound mTLS, OneTrust does not require the certificate to be signed by a trusted authority so long as the receiving end can accept it. For inbound mTLS, OneTrust requires the uploaded public keys to be signed by a trusted certificate authority.

Settings & Administration