You can configure the OneTrust application to leverage your company's Single Sign-On (SSO) protocols. This will enable users to access the application with their existing credentials. Configuring SSO is a multi-step process that involves configurations both within your Identity Provider (IdP) and within the OneTrust application.
In order to configure SSO, each of the following steps must be completed.
Note
SSO configuration is only available to Site Admin users.
Prior to beginning the configuration within both your IdP and the OneTrust application, please review the information below.
Organization Level
OneTrust recommends configuring SSO at the highest level of your organizational hierarchy. This ensures the configuration is easy to find and troubleshoot and that users throughout the hierarchy are provisioned correctly. However, SSO can also be configured at other levels of your organizational hierarchy.
Multi-Provider SSO Support
OneTrust supports the use of multiple Identity Providers (IdPs) within a single account as SSO can be configured at the organization level. If multiple IdPs are used, you can configure SSO for one IdP within one organization and separately configure SSO for another IdP within a different organization in your account.
Note
SAML settings are tied to an organization, so only one IdP can be configured per organization.
External Users
If SSO is enabled for an organization, external users can log in to the OneTrust application using a username and a password. However, if the external user is already a user in another OneTrust tenant/account with their work email, that user will be sent to their SSO provider. If these external users should be allowed to log in to your tenant/account with a username and password, contact OneTrust Support.
OneTrust Environment Metadata
You can use OneTrust's environment metadata to bypass manual SSO configuration if supported by your IdP. OneTrust's environment metadata can be downloaded directly from the Single Sign-On screen in Global Settings using the Download Metadata field on the Configuration tab.
Note
The Download Metadata field is only visible when Metadata is selected in the Setup Options field.
Alternatively, you can download a collection of OneTrust's metadata files in the following link: OneTrust Environment Metadata. On the File Details page, click the Download button to download the zip file. You will need to use the specific metadata file that corresponds with your application environment, which can be identified based on the URL as highlighted in the image below.
For example, if the URL used to log in to your application is app.onetrust.com, then you would use the app OneTrust Metadata file. If you are using a custom domain or custom subdomain, the metadata will remain the same. For example, if your custom subdomain youramazingcompany.my.onetrust.com was created on the uat-de.onetrust.com application environment, then you would use the uat-de OneTrust Metadata file.
OneTrust Signed Certificates
When creating a web application, you can import the OneTrust certificate for your respective application environment into your IdP. Your IdP may use this certificate for encrypting assertions or for verifying SLO requests signed by OneTrust (if the Sign SAML Requests setting on the Single Sign-On screen is enabled in the OneTrust application).
If you would like to complete this process, OneTrust Signed Certificates can be downloaded directly from the Single Sign-On screen in Global Settings using the Download Current OneTrust Certificate field on the Configuration tab or using the Certificates tab. Additionally, upcoming OneTrust Signed Certificates can be downloaded from the Certificates tab, if available.
Note
The Download Current OneTrust Certificate field and the Certificates tab only appear if the Sign SAML Requests setting is enabled. In addition, the Download Current OneTrust Certificate field is only visible when Manual is selected in the Setup Options field.
Domain Configuration
If you are using a custom domain or custom subdomain, the same email domain can be reused across multiple accounts. As shown in the diagram below, multiple custom domains or custom subdomains and a single shared environment account can use the same SSO email domain within an application environment.
Note
If you are using a custom subdomain, you will have to use the unique URL (i.e. youramazingcompany.my.onetrust.com) for logging in to the application with SSO as the old URL (i.e. app-eu.onetrust.com) will no longer work. For more information, see Customizing OneTrust with a Custom Subdomain.
Step 1: Create a SAML 2.0 Web Application in your IdP
The first step to configuring SSO is to create a web application corresponding to your OneTrust account in your IdP. During this process, you will use the OneTrust metadata for your respective application environment to set up the web application for SSO. Once you've created the web application in your IdP, you will then proceed to configure SSO in the OneTrust application.
Step 2: Configure SSO in the OneTrust Application
Next, you will need to configure SSO authentication to redirect URLs between your IdP and OneTrust. You will need to reference information found in your IdP's setup information to complete SSO configuration within the OneTrust application.
Click the gear icon in the upper right-hand corner to access Global Settings.
On the Global Settings menu, select Access Management > Single Sign-On. The Single Sign-On screen appears.
Enable the Single Sign-On setting. Additional SSO configuration fields appear.
In the Notification Recipient field, select the user(s) and/or user group(s) to be notified when action is required regarding the SSO configuration. User(s) or user group(s) must be selected in this field in order to save changes to your SSO configuration.
Note
The user(s) and/or user group(s) designated in this field will receive the following email notifications when action is required regarding the SSO configuration. If no user(s) or user group(s) are designated in this field, all Site Admins will receive these email notifications. These email templates are not customizable and will not appear on the Templates tab of the Email screen.
Email Template
Purpose
Trigger
Upcoming Renewal of OneTrust Signed Certificates for SSO
Notifies the designated recipient(s) that a new OneTrust signed certificate for SSO is available for download. The certificate will then need to be uploaded to their IdP on the renewal date.
A new OneTrust signed certificate for SSO is uploaded for a given environment.
24 Hours until Renewal of OneTrust Signed Certificates for SSO
Notifies the designated recipient(s) that OneTrust will renew the signed certificate for SSO in 24 hours. The certificate will then need to be uploaded to their IdP on the renewal date.
The renewal date for a new OneTrust signed certificate for SSO is within 24 hours.
Update SSO Notification Recipient field
Notifies Site Admins to add a designated notification recipient(s) to the SSO configuration.
There are no user(s) and/or user group(s) selected in the Notification Recipient field.
Failed SSO User Login Attempt
Notifies the designated recipient(s) when a SSO user login attempt fails on their OneTrust account. This email will contain details of the failed login attempt to help them investigate the issue.
A user's attempt to log in to the OneTrust application via SSO fails.
In the OneTrust Service Provider Details section, complete the following fields.
Field
Description
Response Binding Type
Select the method you want to use to exchange requests and responses.
HTTP Redirect Binding is the most secure method of exchanging requests and responses and is recommended by OneTrust.
Sign SAML Requests
Enable this setting to have OneTrust sign the AuthNRequest and Single Log Out (SLO) Request for additional security. When enabled, the Download Current OneTrust Certificate field appears within Setup Options - Manual. If this setting is enabled, ensure that the OneTrust Signed Certificate is uploaded in your IdP.
Setup Options
Select the option corresponding to how you will be configuring SSO within your IdP. The following options are available:
Manual - Configure SSO manually in your IdP using the provided OneTrust Service Provider Details. If selected, the Service Provider Name, Lockout URL, and Download Current OneTrust Certificate fields appear.
Note
The Download Current OneTrust Certificate field only appears if the Sign SAML Requests setting is enabled.
Metadata - Configure SSO by downloading OneTrust's environment metadata and uploading it into your IdP. If selected, the Download Metadata field appears.
Setup Options - Manual
Service Provider Name
Use the URL in this field to configure the entity ID or identifier for the OneTrust application in your IdP.
Lockout URL
This is the URL that Internal Site Admins in the root organization can use to disable SSO to resolve SSO Lockout. For more information, see Using the Lockout URL.
Note
The Lockout URL uses the following format: https://{$$.env.host}}/auth/validate/sso-lockout with {$$.env.host} representing your respective environment.
For example, the Lockout URL for the trial.onetrust.com environment would be https://trial.onetrust.com/auth/validate/sso-lockout.
Download Current OneTrust Certificate
Click the Download button to download the current OneTrust Signed Certificate for your environment. The OneTrust Signed Certificate will need to be uploaded in your IdP.
Note
Current OneTrust Signed Certificates can be downloaded from this field or from the Certificates tab that appears after the initial SSO configuration is saved.
This field and the Certificates tab only appear if the Sign SAML Requests setting is enabled.
Setup Options - Metadata
Download Metadata
Click the Download button to download OneTrust's environment metadata. The metadata can then be uploaded into your IdP to bypass manual SSO configuration, if supported by your IdP.
In the Identity Provider Configuration section, complete the following fields. You will enter details found within your IdP's setup instructions for the web application you created.
Field
Description
Request Binding Type
Select the method you want to use to exchange requests and responses.
HTTP Redirect Binding for the most secure method of exchanging requests and responses and is recommended by OneTrust.
Name
In your IdP, copy the entity ID or unique identifier associated with your IdP. Paste the contents into the Name field within the Identity Provider Configuration section on the Single Sign-On screen.
Note
Please ensure that the entity ID or unique identifier associated with your IdP is not already saved within another account in the same environment or within another organization in the organizational hierarchy.
SignOn URL
In your IdP, copy the Sign On URL associated with your IdP. This is the URL that you want users to use to log in through your IdP server. Paste the contents into the SignOn URL field within the Identity Provider Configuration section on the Single Sign-On screen. OneTrust will redirect users to this URL for authentication.
SignOut URL
(Optional)
In your IdP, copy the Sign Out URL associated with your IdP. This is the URL that you want to redirect users to when they click the Log out button in the OneTrust application. Paste the contents into the SignOut URL field within the Identity Provider Configuration section on the Single Sign-On screen.
In the Upload Certificate section, you will need to upload the authentication certificate issued by your IdP. OneTrust will validate messages from the IdP based on this certificate.
If available, you can download the certificate from your IdP in Base64 format.
If the authenticate certificate is unavailable to download from your IdP but you have the metadata, you can complete the following procedure to generate the certificate.
Open your SSO metadata file.
Copy the text between the following tags: <ds:X509Certificate></ds:X509Certificate>
Paste the text into a notepad.
Insert the following tags before and after the text:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
Save the file in a .crt or .cer format.
Once you have the certificate, navigate back to the Upload Certificate section on the Single Sign-On screen in the OneTrust application. Click the Upload button to upload the certificate downloaded from your IdP. The Subject, Issuer, and Thumbprint fields will populate with the certificate information and cannot be edited.
Click the Save button. The Confirm modal appears.
Click the Ok button to confirm your SSO configuration. The Attribute Mappings, Assignments, and Domains tab appear. The Certificates tab also appears if the Sign SAML Requests setting is enabled.
Step 3: Map Attributes between the IdP and the OneTrust Application
On the Attribute Mappings tab, you'll map attributes between your IdP and the OneTrust application. OneTrust supports Just-In-Time (JIT) provisioning, which allows users to be automatically created in the OneTrust application the first time they log in using SSO. You can configure whether to enable or disable use of JIT provisioning. The fields available on the Attribute Mappings tab will update based on your selected configuration.
Attribute Mappings
The following attribute mappings can be used to provision users in the OneTrust application. The mapping of these attributes will need to be jointly agreed on between OneTrust and your company.
Attribute
Description
First Name
Enter the associated attribute key in the Attribute Key field. The value in this field must be an identical match in both your IdP and the OneTrust application.
Note
A variable value must be entered for the First Name attribute.
Last Name
Enter the associated attribute key in the Attribute Key field. The value in this field must be an identical match in both your IdP and the OneTrust application.
Note
A variable value must be entered for the Last Name attribute.
Email
Enter the associated attribute key in the Attribute Key field. The value in this field must be an identical match in both your IdP and the OneTrust application.
Note
A variable value must be entered for the Email attribute.
Role
Enter either the associated attribute key in the Attribute Key field or a default value in the Default Value for Role field.
Default Value for Role - You must enter a default value for the Role attribute when JIT provisioning is enabled. All users who log in to the application via SSO for the first time will then be provisioned with this role. If an entry is made in both the Attribute Key and Default Value for Role fields, then the value in the Attribute Key field will take precedence and the Default Value for Role will not be acknowledged.
Attribute Key - If entering an attribute key, the value must be an identical match in both your IdP and the OneTrust application. If an attribute key is defined for the Role attribute, the role that a user is provisioned with will be determined by the role mapping you define on the Assignments tab. For more information, see To define role assignments.
Note
Please note that the Role attribute is updated dynamically if an attribute key is specified and the Sync on Each Login check box is selected. If the Sync on Each Login check box is selected and the user's role is manually changed within the OneTrust application, the user's role will be updated to align with the defined role assignment the next time the user logs in, rather than retaining that manual change. If multiple role values are included in the Role Attribute Key, all of those roles will be assigned to the user.
Organization
Enter either the associated attribute key in the Attribute Key field or a default value in the Default Value for Organization field.
Default Value for Organization - You must enter a default value for the Organization attribute when JIT provisioning is enabled. All users who log in to the application via SSO for the first time will then be provisioned as a user in this organization. If an entry is made in both the Attribute Key and Default Value for Organization fields, then the value in the Attribute Key field will take precedence and the Default Value for Organization will not be acknowledged.
Attribute Key - If entering an attribute key, the value must be an identical match in both your IdP and the OneTrust application. If an attribute key is defined for the Organization attribute, the organization that a user is provisioned with will be determined by the organization assignment you define on the Assignments tab. For more information, see To define organization assignments.
Note
Please note that the Organization attribute is updated dynamically if an attribute key is specified and the Sync on Each Login check box is selected. If the Sync on Each Login check box is selected and the user's organization is manually changed within the OneTrust application, the user's organization will be updated to align with the defined organization assignment the next time the user logs in, rather than retaining that manual change. If multiple values are included in the Organizations Attribute Key, only the first value with a valid mapping defined in the Organization Assignment section on the Assignments tab will be applied to the user.
User Group
Enter the associated attribute key in the Attribute Key field. The user group that the user is provisioned with will be determined by the group assignment you define on the Assignments tab. For more information, see To define group assignments.
Note
Please note that the User Group attribute is updated dynamically if an attribute key is specified and the Sync on Each Login check box is selected. If the Sync on Each Login check box is selected and the user's groups are manually changed within the OneTrust application, the user's groups will be updated to align with the defined group assignment the next time the user logs in, rather than retaining that manual change. If multiple group values are included in the User Group Attribute Key, the user will be added to those user groups.
To map attributes with JIT provisioning enabled
When JIT provisioning is enabled, a user account will automatically be created for users who log in to the application via SSO for the first time. These users will also be provisioned with the role and organization defined by the Attribute Mappings configuration.
Navigate to the Attribute Mappings tab.
Enable the Enable Just-In-Time Provisioning setting. The Default Value for Role and Default Value for Organization fields appear and are required.
In the Default Value for Role field, select the role with which you want to provision all users that log in via SSO.
Note
If an entry is made in both the Attribute Key and Default Value for Role fields, then the value in the Attribute Key field will take precedence and the Default Value for Role will not be acknowledged.
In the Default Value for Organization field, select the organization in which you want to provision all users that log in via SSO.
Note
If an entry is made in both the Attribute Key and Default Value for Organization fields, then the value in the Attribute Key field will take precedence and the Default Value for Organization will not be acknowledged.
In the Attribute Mappings section, you'll map attributes between your IdP and the OneTrust application.
Note
When JIT provisioning is enabled, entering a value in the Attribute Key field for the Role and Organization attributes is optional. For more information on the attributes, see Attribute Mappings above.
Use the Sync on Each Login check boxes to define whether each attribute should be synced each time the user logs in to the OneTrust application. This check box will determine whether user attributes are updated according to the value defined in the Attribute Key field each time they log in.
Click the Save button.
To map attributes with JIT provisioning disabled
When JIT provisioning is disabled, a user account will not automatically be created for anyone that is not currently a user in the application.
Navigate to the Attribute Mappings tab.
Disable the Enable Just-In-Time Provisioning setting.
In the Attribute Mappings section, you'll map attributes between your IdP and the OneTrust application.
Note
When JIT provisioning is disabled, entering a value in the Attribute Key field for the Role and Organization attributes is required. For more information on the attributes, see Attribute Mappings above.
Use the Sync on Each Login check boxes to define whether each attribute should be synced each time the user logs in to the OneTrust application. This check box will determine whether user attributes are updated according to the value defined in the Attribute Key field each time they log in.
Click the Save button.
Step 4: Define Role, Organization, and Group Assignments
OneTrust supports role, organization, and group assignments, which means that the application will read specific values in the SAML assertion that is sent from your IdP and assign those values to valid OneTrust values. If an Attribute Key is defined for the Role, Organization, and/or User Group attributes within the Attribute Mappings section on the Attribute Mappings tab, you will need to define role, organization, and/or user group assignments on the Assignments tab.
To define role, organization, and group assignments, you will copy the respective role, organization, and group values from within your IdP and map these values to roles, organizations, and user groups that exist within the OneTrust application. By defining this mapping, users will be provisioned with the mapped roles, organizations, and user groups when signing in to the OneTrust application via SSO.
To define role assignments
If an Attribute Key is defined for the Role attribute within the Attribute Mappings section on the Attribute Mappings tab, you will need to define role assignments on the Assignments tab.
Note
Multiple roles can be assigned to a user through role mapping. For example, the Roles Attribute Key for the user below contains three values: Okta_onetrust_auditor, Okta_onetrust_privacy_manager, and Okta_onetrust_site_admin. If there is a valid mapping defined in the Role Assignment section on the Assignments tab for each of these values, then the user will be provisioned with each of those roles in the application.
Attribute values can also be passed as comma separated values, as shown in the example below.
Navigate to the Assignments tab.
In the Role Assignment section, click the Add Role button. The Add New Role Assignment modal appears. On this modal, you will enter the roles configured within your IdP that you want to map to roles within the OneTrust application.
Field
Description
Role in Your Directory
Enter the name/value of the role that exists within your IdP that you want to map to a role within the OneTrust application.
Note
An attribute value can only be linked to a single role.
Maps to this Role in the OneTrust Application
Select the role within the OneTrust application that you want to map to the role within your IdP. Users will be provisioned with the role selected in this field when their user record within your IdP matches the value entered in the Role in Your Directory field.
Complete the fields, as needed.
Click the Save button. The role mapping appears within the Role Assignment section on the Assignments tab.
Note
If creating multiple new role assignments, click the Save and Add Another button.
To define organization assignments
If an Attribute Key is defined for the Organization attribute within the Attribute Mappings section on the Attribute Mappings tab, you will need to define organization assignments on the Assignments tab.
Note
Users can only be assigned to one organization through SSO. If multiple values are passed, OneTrust will assign the user to the first organization that has a valid mapping. For example, the Organization Attribute Key for the user below contains three values: 100, 101, and 102. If there is a valid mapping defined in the Organization Assignment section for 101 and 102, but no mapping defined for 100, then the user will be assigned to Gilbert Hughes & Company since it is mapped to 101.
Attribute values can also be passed as comma separated values, as shown in the example below.
Navigate to the Assignments tab.
In the Organization Assignment section, click the Add Organization button. The Add New Organization Assignment modal appears. On this modal, you will enter the organizations configured within your IdP that you want to map to organizations within the OneTrust application.
Field
Description
Org in Your Directory
Enter the name/value of the organization that exists within your IdP that you want to map to an organization within the OneTrust application.
Note
An attribute value can only be linked to a single organization group.
Maps to This Organization in OneTrust Application
Select the organization within the OneTrust application that you want to map to the organization within your IdP.
Click the Save button. The organization mapping appears within the Organization Assignment section on the Assignments tab.
Note
If creating multiple new organization assignments, click the Save and Next button.
To define group assignments
If an Attribute Key is defined for the User Group attribute within the Attribute Mappings section on the Attribute Mappings tab, you will need to define group assignments on the Assignments tab.
Note
Multiple groups can be assigned to a user through group mapping. For example, the Groups Attribute Key for the user below contains three values: Auditors, Consent Managers, and Site Admin. If there is a valid mapping defined in the Group Assignment section on the Assignments tab for each of these values, then the user will be provisioned with each of those user groups in the application.
Attribute values can also be passed as comma separated values, as shown in the example below.
Navigate to the Assignments tab.
In the Group Assignment section, click the Add Group button. The Add New Group Assignment modal appears. On this modal, you will enter the groups configured within your IdP that you want to map to user groups within the OneTrust application.
Field
Description
Group in Your Directory
Enter the name/value of the group that exists within your IdP that you want to map to a user group within the OneTrust application.
Note
An attribute value can only be linked to a single user group.
Maps to This User Group in OneTrust Application
Select the user group within the OneTrust application that you want to map to the group within your IdP. Users will be provisioned with the user group selected in this field when their user record within your IdP matches the value entered in the Group in Your Directory field.
Click the Save button. The user group mapping appears within the Group Assignment section on the Assignments tab.
Note
If creating multiple new group assignments, click the Save and Add Another button.
Step 5: Verify Domain Ownership
You will also need to add your domains and verify domain ownership on the Domains tab on the Single Sign-On screen within the OneTrust application to successfully complete the SSO Configuration process.
Note
For accounts with a custom subdomain or fully qualified domain name (FQDN), domains added on the Domains tab will be automatically placed in Accepted status.
Navigate to the Domains tab. The Domain Verification section appears.
Click the Add Domain button. The Add Domain modal appears.
In the Domain field, enter the domain to be claimed.
(Optional) In the Description field, enter a description for the domain.
Click the Add button. The Verification Token modal appears.
Note
If the entered domain is already in use in the environment, an error message will appear. If you believe this message was received in error, reach out to your consultant or submit a product support ticket.
In the TXT Token field, click the Copy button to copy the TXT validation token to your computer's clipboard.
Click the Close button. The domain appears in the Domain Verification section in Pending status.
Log in to your domain name system (DNS) provider.
Add the TXT validation token into a TXT record file in your DNS provider.
Return to the Domains tab in the OneTrust application.
Hover over the row of the domain you want to validate, and click the Context Menu icon that appears.
On the Context menu, select Verify. When the domain verification is successful, the domain displays in Verified status.
Note
If the domain is verified by you through this process, the domain will display in Verified status. If the domain is verified by OneTrust Support, the domain will display in Accepted status. Both statuses indicate verified domain ownership and no further action is needed.
(Optional) Using the Lockout URL
Single Sign-On (SSO) can be disabled to resolve issues caused by SSO misconfiguration and resulting in the inability to access the application. Internal Site Admins in the root organization can use the following self-service flow to disable SSO and resolve SSO lockout without having to contact OneTrust Support.
Note
Disabling SSO is restricted to Internal Site Admins within the root organization. OneTrust Consultants are generally External users and cannot perform this action within your account. You can reference the Users screen in Global Settings to identify whether a user is internal or external.
To obtain the Lockout URL
When configuring SSO, it is recommended that Site Admins copy and maintain the Lockout URL in a secure location outside of the application. In the event of SSO Lockout, Site Admins in the root organization can use this link to access a self-service workflow to resolve SSO Lockout issues.
Click the gear icon in the upper right-hand corner to access Global Settings.
On the Global Settings menu, select Access Management > Single Sign-On. The Single Sign-On screen appears.
Click the Copy button in the Lockout URL field. The link is copied to your computer's clipboard and can be saved to a secure location.
To disable SSO
Navigate to the Lockout URL copied from the Single Sign-On screen in your web browser.
Note
If the Lockout URL was not copied from the Single Sign-On screen, you can use https://{$$.env.host}/auth/validate/sso-lockout and replace {$$.env.host} with your respective environment. For example, the Lockout URL for the trial.onetrust.com environment would be https://trial.onetrust.com/auth/validate/sso-lockout.
If you are using a custom domain or custom subdomain, the {$$.env.host} portion of the Lockout URL will instead use your custom domain or custom subdomain. For example, if your custom subdomain is youramazingcompany.my.onetrust.com, then your Lockout URL would be https://youramazingcompany.my.onetrust.com/auth/validate/sso-lockout.
Enter the email address for a Internal Site Admin in the root organization.
Note
Only Internal Site Admins in the root organization have access to disabling SSO. OneTrust Consultants are generally External users and cannot perform this action within your account.
Click the Submit button. If the entered email address is authorized to disable SSO, an email will be sent to the email address.
Click the link within the email that you received to proceed with disabling SSO. A confirmation screen appears on a new tab in your web browser.
Note
The emailed link expires within 24 hours.
Verify the details for disabling SSO.
Click the Continue button to disable SSO. Once SSO is disabled, users will be required to set a new password to log in to the application.
