Documentation

Unity Cloud

Get Started

Asset Manager SDKs and services

Open Unity Dashboard

Unity Cloud

Set up Enterprise single sign-on with Microsoft Entra ID

Configure Microsoft Entra ID to work with a SAML identity provider for Enterprise single sign-on for your Unity organization
Read time 4 minutesLast updated 23 days ago
This page covers the Microsoft Entra ID side of setting up Enterprise single sign-on (SSO). It supplements Set up Enterprise single sign-on, which describes the Unity side of the same procedure and applies to every identity provider (IdP).

Prerequisites

Meet the prerequisites of the general guide, and these Microsoft Entra ID prerequisites:
  • You have administrative access to your Microsoft Entra 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:

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.
Note
This is separate from validating the domain in Unity, which the general guide requires as a prerequisite. Read Register and validate domains.
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

You can create only one SAML application for Unity per Microsoft Entra ID directory. Read the full restriction in Set up Enterprise single sign-on.
To create the application, 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.

Exchange metadata with Unity

This section covers the Microsoft Entra ID half of Configure Enterprise SSO. Metadata travels in both directions: Unity's settings go to Microsoft Entra ID, and Microsoft Entra ID's settings come back to Unity.
To exchange metadata, follow these steps:
  1. Copy the Entity ID and Login URL values from the Unity card, as described in Submit the Unity settings to your IdP.
  2. Paste these values to the IdP configuration in Microsoft Entra.
  3. To download the settings as an .xml file, select Federation Metadata XML.
  4. Go back to the Single Sign-on tab of the Unity Dashboard, find the Identity Provider card, and select Edit.
  5. Copy these values from the .xml file into the corresponding fields, and then save your changes:

    Microsoft Entra ID value in the .xml file

    Field on the Unity Identity Provider card

    Microsoft Entra ID IdentifierEntity ID
    Login URLSSO Login URL
    X.509 CertificateX.509 Certificate
    Note
    Microsoft Entra ID's Login URL is its sign-in endpoint, and it maps to Unity's SSO Login URL. Don't confuse it with Unity's own Login URL in step 1, which is the Assertion Consumer Service (ACS) URL that Microsoft Entra ID needs.

Add the email attribute in Microsoft Entra ID

Unity SAML SSO needs an Email attribute to authenticate the user. To map it 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 SSO.
  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

Before you can provision users, you must have added your company domain to 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.

Next steps

Your Microsoft Entra ID configuration is now complete. Go back to the general guide to finish the setup in Unity: