Configuring OneTrust with Microsoft Entra ID for Single Sign-On (SSO) Authentication
UUID-a7b17766-2c40-02b1-89c9-17205192d513
Article Content
You can integrate OneTrust with Microsoft Entra ID through SAML 2.0 for Single Sign-On (SSO) authentication in a service provider-initiated workflow and IdP-initiated workflow. Prior to beginning the configuration within Microsoft Entra ID, please review the information in the Things to Know section below.
Things to Know
Microsoft Entra ID Interface
This documentation uses navigation instructions and screenshot references that were taken using Microsoft Entra ID.
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 you use to log in to the platform 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 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 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 platform).
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.
Step 1: Create a Web Application in Microsoft Entra ID
The first step to configuring OneTrust with Microsoft Entra ID for SSO authentication is to create a web application in Microsoft Entra ID with SAML 2.0 as a sign on method. During this process, you will use the OneTrust metadata for your respective environment to set up the web application for SSO. Once you've created the web application in Microsoft Entra ID, you will then proceed to configure SSO in the OneTrust platform.
To create a web application in Microsoft Entra ID
Note
Please download and open the metadata file for your respective environment to use alongside the following procedure. If you require a OneTrust certificate for signing purposes or would like to encrypt assertions, please download and open the OneTrust signed certificate file for your respective environment to use alongside steps 14 - 18 in the following procedure. For more information, review the Things to Know section above.
Log in to your Microsoft Entra admin center.
Click the View button under the Manage Microsoft Entra ID tile. The Overview screen for your account appears.
On the main navigation menu, click Enterprise applications. The Enterprise applications | All applications screen appears.
Click the New application button. The Browse Microsoft Entra Gallery screen appears.
Click the Create your own application button. The Create your own application pane appears.
In the What's the name of your app? field, enter a name for your new web application.
In the What are you looking to do with your application? field, select the Non-gallery option.
Click the Create button. The Overview screen for your newly added web application appears.
In the Getting Started section, click the Get started link for 2. Set up single sign on. The Single sign-on screen appears.
In the Select a single sign-on method section, select SAML. The SAML-based Sign-on screen appears. Using Microsoft Entra ID's steps in the Set up Single Sign-On with SAML section, you will set up the SSO configuration to integrate with the OneTrust platform.
Click the Edit button for step 1 Basic SAML Configuration. The Basic SAML Configuration pane appears. You will use the metadata that you downloaded for your respective environment to complete the fields on this pane. For more information, you can find a detailed description of the entries required for each field in the following table. Once complete, click the Save button.
Field
Description
Identifier (Entity ID)
Within the metadata file, locate the EntityDescriptor attribute. Copy the corresponding entityID URL and paste it into the Identifier (Entity ID) field.
Reply URL (Assertion Consumer Service URL)
Within the metadata file that you downloaded for your environment, locate the AssertionConsumerService attribute. Copy the corresponding URL and paste it into the Reply URL (Assertion Consumer Service URL) field.
Sign on URL
Leave this field blank if you want to perform IdP-Initiated SSO authentication.
Relay State
Leave this field blank.
Logout Url
Within the metadata file, locate the SingleLogoutService attribute. Copy the corresponding URL and paste it into the Logout Url field.
In step 2 Attributes & Claims, you can click the Edit button to access the Attributes & Claims screen. On this screen, you can find the claim names that will need to be mapped on the Attributes Mappings tab of the Single Sign-On screen within the OneTrust platform. This process will be completed within Step 3: Map Attributes between Microsoft Entra ID and the OneTrust Platform below. Click the X button to return to the SAML-based Sign-on screen.
Note
The following examples show potential variations in the claim names.
In step 3 SAML Certificates, click the Edit button in the Token signing certificate section. The SAML Certificates pane appears. For more information, you can find a detailed description of the entries required for each field in the following table. Once complete, click the Save button.
Field
Description
Signing Option
Select either Sign SAML response, Sign SAML assertion, or Sign SAML response and assertion. OneTrust supports all options, so you can select which option to use. However, OneTrust recommends using both a signed SAML response and assertion.
Note
If either the response or assertion is signed, you must ensure that the signed IdP certificate is uploaded within the OneTrust platform via the Single Sign-On screen in Global Settings.
Signing Algorithm
The option selected by default is SHA-256. OneTrust supports this signing algorithm.
If you require a OneTrust certificate for signing purposes, click the Edit button in the Verification certificates (optional) section in step 3 SAML Certificates. The Verification certificates pane appears.
On the Verification certificates pane, select the Require verification certificates check box, click the Upload certificate button, and upload OneTrust's certificate for your respective environment. Then click the Save button.
If you want the assertions to be encrypted, select Security > Token encryption. The Token encryption screen appears.
Note
Steps 16 - 18 are related to encrypting assertions. This process is optional.
On the Token encryption screen, click the Import Certificate button and select the OneTrust certificate to import. Then click the Add button. The OneTrust certificate will appear on the Token encryption screen. You will now need to activate the OneTrust certificate.
Click the Context Menu icon for the respective certificate and select Activate token encryption certificate. Then click Yes to confirm activation of the token encryption certificate. If successful, you will receive a message confirming that Token encryption is enabled.
Step 2: Configure SSO in OneTrust with Microsoft Entra ID
Next, you will need to configure SSO authentication to redirect URLs between your IdP and OneTrust. You will need to reference information found on Microsoft Entra ID's SAML-based Sign-on screen for the web application you created in the procedure above to complete SSO configuration within the OneTrust platform.
To configure SSO in OneTrust with Microsoft Entra ID
Note
Please ensure that you have Microsoft Entra ID's SAML-based Sign-on screen open while you complete the following procedure.
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.
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.
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 platform 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.
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 the issuer details found within step 4 on Microsoft Entra ID's SAML-based Sign-on screen for the web application you created above.
Note
The first example image below shows issuer details captured within Microsoft Entra ID. The second image shows the corresponding fields within the OneTrust platform that you will be configuring with these details.
OneTrust Field
Description
Request Binding Type
Select the method you want to use to exchange requests and responses.
Name
In Microsoft Entra ID, click the Copy to clipboard icon in the Microsoft Entra Identifier field. Navigate to the OneTrust platform and paste the contents into the Name field within the Identity Provider Configuration section on the Single Sign-On screen.
Note
Please ensure that the Microsoft Entra Identifier is not already saved within another account in the same environment or within another organization in the organizational hierarchy.
SignOn URL
In Microsoft Entra ID, click the Copy to clipboard icon in the Login URL field and paste it into the SignOn URL field within the Identity Provider Configuration section on the Single Sign-On screen.
SignOut URL
In Microsoft Entra ID, click the Copy to clipboard icon in the Logout URL field and paste it 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 certificate for your IdP.
You can download your IdP certificate from step 3 on Microsoft Entra ID's SAML-based Sign-on screen. In step 3 SAML Certificates, click the Download link corresponding to Certificate (Base64). The file will download to your local system.
Navigate back to the Upload Certificate section on the Single Sign-On screen in the OneTrust platform. Click the Upload button to upload the certificate downloaded from Microsoft Entra ID. The Subject, Issuer, and Thumbprint fields will populate with the certificate information and cannot be edited.
Note
You can verify that the correct certificate was uploaded by comparing the contents in the Thumbprint fields in both Microsoft Entra ID and the OneTrust platform.
Click the Save button. The Attribute Mappings, Assignments, and Domains tab appear.
Step 3: Map Attributes between Microsoft Entra ID and the OneTrust Platform
On the Attribute Mappings tab, you'll map attributes between your Microsoft Entra ID and the OneTrust platform. OneTrust supports Just-In-Time (JIT) provisioning, which allows users to be automatically created in the OneTrust platform 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.
Note
For more information on the available attribute mappings and JIT provisioning, see Step 3: Map Attributes between the IdP and the OneTrust Plaform within the Managing Single Sign-On (SSO) article.
On the Attributes Mappings tab, you will need to enter the claim name URLs found within Microsoft Entra ID.
In step 2 on Microsoft Entra ID's SAML-based Sign-on screen, click the Edit button. The Attributes & Claims screen appears, where you can find the claim name URLs that will need to be mapped to the attributes in the Attributes Mappings tab of the Single Sign-On screen within the OneTrust platform.
Once complete, click the X button on Microsoft Entra ID's Attributes & Claims screen to return to the SAML-based Sign-on screen.
Note
The first example image below shows claim name URLs captured within Microsoft Entra ID. The second image shows the corresponding fields within the OneTrust platform that you will be configuring with these details.
Section
Value
Description
Additional Claims
user.mail
If you choose to use email addresses to authenticate to OneTrust, copy the claim name for the user.mail value (such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress or emailaddress) and paste the claim name into the Attribute Key field for the Email attribute on the Attributes Mappings tab.
Note
Microsoft Entra ID has both the user.mail and user.userprincipalname values that can be used to authenticate to OneTrust. It is up to you to choose which value to use.
user.givenname
Copy the claim name for the user.givenname value (such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname or givenname) and paste the claim name into the Attribute Key field for the First Name attribute on the Attributes Mappings tab.
user.userprincipalname
If you choose to use user principal names to authenticate to OneTrust, copy the claim name for the user.userprincipalname value (such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name or name) and paste the claim name into the Attribute Key field for the Email attribute on the Attributes Mappings tab.
Note
Microsoft Entra ID has both the user.mail and user.userprincipalname values that can be used to authenticate to OneTrust. It is up to you to choose which value to use.
user.surname
Copy the claim name for the user.surname value (such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname or surname) and paste the claim name into the Attribute Key field for the Last Name attribute on the Attributes Mappings tab.
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 platform. 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 platform will read specific values in the SAML assertion that is sent from Microsoft Entra ID 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 the Attributes Mappings tab, you will need to define role, organization, and/or user group assignments on the Assignments tab of the Single Sign-On screen in the OneTrust platform. For more information, see Step 4: Define Role, Organization, and Group Assignments within the Managing Single Sign-On (SSO) article.
Step 5: Verify Domain Ownership
The next step will be to verify domain ownership on the Domains tab on the Single Sign-On screen in the OneTrust platform. For more information, see Step 5: Verify Domain Ownership within the Managing Single Sign-On (SSO) article.
Step 6: Assign Users in Microsoft Entra ID
Once you have completed your SSO configuration, you can begin assigning users within Microsoft Entra ID.
Caution
Please note that if you are not using Just-In-Time provisioning, new users that are added to the OneTrust platform but are not assigned to the Enterprise application within Microsoft Entra ID may experience a login error, such as AADSTS50105 EntitlementGrantsNotFound. To resolve this error, an administrator will need to assign the necessary access to the user within Microsoft Entra ID.
To assign users in Microsoft Entra ID
In Microsoft Entra ID, click 1. Assign users and groups within the Getting Started section on the Overview screen for the web application you created. Alternatively, you can select Manage > Users and groups on the main navigation menu. The Users and groups screen appears.
Click the Add user/group button. The Add Assignment screen appears. Click the link below the Users heading. The Users pane appears.
Note
If groups are available for assignment, this heading and corresponding pane would be titled Users and groups.
On the Users pane, search for and select the users you want to add. Users that you click will appear within the Selected section on the pane. Once you've added the necessary users, click the Select button. The link below the Users heading will update to include the number of users you selected and the Assign button will become available.
Click the Assign button. The user(s) will then appear on the Users and groups screen.
Additional Resources
For additional information, you can reference the following resources from Microsoft:
