Set up single sign-on with Microsoft Entra ID

Configure Microsoft Entra ID to work with a SAML identity provider (IdP) for single sign-on (SSO) for your Unity organization.

To do so, follow these steps:

1. Check the prerequisites.
2. Add your domain to Microsoft Entra ID.
3. Create a SAML application in Microsoft Entra ID.
4. Set metadata in Microsoft Entra ID and in Unity Cloud.
5. Validate your organization domain.
6. Add the email attribute in Microsoft Entra ID.
7. Provision users.
8. Test the SAML SSO integration.

Prerequisites

Prerequisites

Before you begin, ensure that you meet these prerequisites:

• You have administrative access to your Microsoft Azure account.

• You have the required permissions to configure Microsoft Entra ID.

• The admin user has these Microsoft Entra roles:

  • Cloud Application Administrator
  • Global Administrator
  • User Administrator

To access Microsoft Entra ID, follow these steps:

1. Sign in to the Microsoft Entra admin center as an IT administrator.

2. On the home page, select Microsoft Entra ID.

   If you can't access Microsoft Entra ID, try these alternatives:

   • Follow this Microsoft tutorial.
   • Sign in to a different page in the Microsoft Entra ID admin center.

Add your domain to Microsoft Entra ID

Add your domain to Microsoft Entra ID

If you haven't already added your company domain to Microsoft Entra ID, you must do so. Otherwise, you can't provision users with your domain.

To add your domain to Microsoft Entra ID, follow these steps:

1. From the Microsoft Entra ID admin center, search for the Domain Names service and select it.

2. Select Add custom domain and add your domain.

3. Copy the DNS information.

4. In your domain registrar, create a TXT record based on the copied DNS information.

   It may take between 48 to 72 hours for your TXT record to propagate.

Read more about managing domains in Microsoft Entra ID, in the Microsoft documentation.

Create a SAML application in Microsoft Entra ID

Create a SAML application in Microsoft Entra ID

Follow these steps:

1. From the Microsoft Entra ID admin center, search for the Enterprise applications service and select it.
2. Select New application, and then select Create your own application.
3. Enter the name of your application, and then select Non-gallery.
4. Select Create.

Set metadata in Microsoft Entra ID and Unity Cloud

Set metadata in Microsoft Entra ID and Unity Cloud

You must copy metadata from Unity Cloud to Microsoft Entra ID, and other metadata from Microsoft Entra ID to Unity Cloud.

Follow these steps:

1. In Unity Cloud, go to Administration > Single sign on.

2. Copy the values from these fields:

   • Entity ID
   • ACS URL

3. Paste these values to the IdP configuration in Microsoft Entra.

4. To download the settings as an .xml file, select Federation Metadata XML.

5. Copy the X.509 Certificate text from the .xml file and paste it into Unity Cloud's SSO settings. Copy and paste these values:

Validate your organization domain

Validate your organization domain

Before you can work with SSO, you must validate your domain with Unity so that Unity recognizes you as the domain owner of your organization.

Unity uses domain validation for these purposes:

• Domain ownership: domain validation ensures legitimate ownership and control of the domain.

• Fraudulent activity: domain validation helps prevent domain impersonation and the fraudulent configuration of applications.

• Trust anchor: domain validation acts as a form of trust anchor.

  Other parties can't easily perform these actions:

  • Claim to represent the organization, for example, your domain.
  • Configure applications or services for unauthorized access or misuse of the organization's identity.

To ensure that the validated domains in your IdP and in your Unity SSO match, follow these steps:

1. Sign in to Unity Cloud as the SSO configuration IT administrator.
2. Go to Administration > Single sign on, and then select Add domain.
3. Enter the domain for which you want to turn on SSO, and then select Add and validate.
4. Copy the entire DNS TXT record from the domain information window.
5. Go to the DNS management panel of your domain registrar.
6. Create a DNS record of TXT type and paste the copied content into it.
7. In Unity Cloud, select Validate.
8. To turn on SSO for other domains, repeat this procedure.

After the record has been created, the domain status in Unity Cloud changes from Pending Verification to Active.

It may take up to 48 hours for Unity to validate your domain through DNS propagation. This process informs upstream providers about domain information before it arrives at where the hosting region is. Unity SSO doesn't work for that domain until the domain is fully validated.

After a domain has been validated, other organizations can't claim it until you delete the record from your SSO configuration.

Add the email attribute in Microsoft Entra ID

Add the email attribute in Microsoft Entra ID

Follow these steps:

1. Go to Microsoft Entra ID admin center.

2. On the configuration page of your new application, select Single Sign-on.

3. In the Attributes & Claims section, select Edit.

4. If no email or mail attribute exists, select Add new claim.

5. Set this information:

   • Set Name to email.
   • Set Source attribute to user.userprincipalname. This value represents the user's email in Microsoft Entra ID.

   Leave the other fields blank.

6. Select Save.

   The Attribute & Claims section shows the email attribute.

Provision your users

Provision your users

Before you can provision users, you must have verified your company domain with Microsoft Entra ID.

To provision users, follow these steps:

1. Create a user:

   1. From the Microsoft Entra ID admin center, search for the Users service and select it.
   2. Create an SSO user.
   3. Set User principal name to the user's email address that has been assigned by the IT admin.
   4. In the user's properties, set Email to the user's email address. If you don't enter an email address, then SAML responses don't include a SAML attribute and SSO fails for this user.

2. Grant the user access to the SAML application:

   1. From the user configuration page, go to Manage > Applications.
   2. Assign the SAML application to the user.

Test the SAML SSO integration

Test the SAML SSO integration

To test the SAML SSO integration, sign in to Unity using the enterprise username that you have created and assigned to the SAML SSO application of Microsoft Entra ID.