Set up single sign-on

How to set up single-sign on (SSO) for your organization.

Read time

6 minutes

Last updated

3 months ago

With Unity single sign-on (SSO) integration, your users need only one set of credentials to access Unity products and services.

Leverage SSO capabilities:

  • Simplify the login process so that users can sign in with their company's credentials instead of a Unity ID and password.
  • Reduce the risk of lost or stolen passwords through a single authentication point.
  • Improve the administration workflow through user provisioning on the first user sign-in.

Prerequisites

Unity SSO uses the Security Assertion Markup Language (SAML) 2.0 protocol. Before you can configure SSO for your organization, you must first create a SAML application in your Identity Provider (IdP) service.

Unity SSO supports the following IdPs:

To create a SAML application in your IdP service, follow these steps:

  1. Go to your organization's IdP portal and create a new SAML 2.0 application.
  2. On a new tab, go to your Unity Dashboard.
  3. Go to Administration > Single sign on.
  4. Copy the values of the following metadata parameters from the Unity section:
    • Entity ID
    • Login (Assertion Consumer Service) URL
    • Certificate
  5. Go back to your IdP portal and paste the values in the corresponding fields of the SAML settings.
  6. Add custom user attribute mapping to your SAML 2.0 connector in your IdP:
    1. For the custom attribute name, enter Email.
    2. Select the user's email in the IdP as the field. To authenticate the user, Unity SAML SSO needs the Email attribute.

Configure SSO for your organization

To configure SSO for your organization, follow these steps:

  1. Go to your Unity Dashboard.
  2. Go to Administration > Single sign on, and then select Edit information next to the Identity Provider section.
  3. On a new tab, go to your organization's IdP portal.
  4. From the settings page for your SAML 2.0 application, generate the following metadata parameters of your SAML 2.0 application:
    • Entity ID: the IdP that you're using. This parameter is also sometimes named as follows:
      • Identity provider issuer
      • Issuer URL
    • SSO Login URL: the IdP login URL.
    • X.509: the IdP certificate.
  5. Go back to the Single sign on page of your Unity Dashboard and paste the values in the corresponding fields.
  6. Save your changes.

Validate domains for SSO

For Unity to recognize you as the domain owner, you must validate your organization's domain with Unity.

In the context of SSO integration, domain validation ensures the legitimate ownership and control of the domain. Domain validation also helps prevent domain impersonation and the fraudulent configuration of applications. Validation acts as a form of trust anchor. Other parties can't easily claim to represent the organization, for example your domain, and configure applications or services that could potentially lead to unauthorized access or misuse of the organization's identity.

Domain validation is mandatory for SSO to work.

To make sure that the list of validated domains in your IdP matches the list of validated domains in your Unity SSO, follow these steps:

  1. Go to your Unity Dashboard.
  2. Go to Administration > Single sign on, and then select Add domain.
  3. Enter the domain which you want to enable SSO for, 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 your Unity Dashboard, select Validate.

You can repeat this process to enable SSO for other domains. After a domain has been validated, other organizations can't claim it until you delete the record from your SSO configuration.

After the record has been created, the domain status in Unity Dashboard 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.

Disable SSO for specific domains

To disable SSO for a specific domain, follow these steps:

  1. Go to Single sign on > Domains.
  2. Select Delete next to the domain that you want to disable.

This action deletes the domain record from your SSO configuration.

To re-enable SSO for this domain, you must validate the domain again for SSO.

Test the SAML SSO integration

To test the SAML SSO integration, sign in to Unity using the SSO flow in one of the following ways:

  • Through your IdP application directory:

    1. Go to your IdP application directory.

    2. Use the IdP flow.

      This flow redirects you to the Unity SSO sign-in page.

    3. Enter the email for a test user, and then select Log in.

  • Through your Unity Dashboard:

    1. Sign out of the Unity Dashboard.
    2. Go to the Unity Dashboard sign-in page.
    3. Select Sign in with SSO.
    4. Enter the email for a test user, and then select Log in.

Known limitations

The following are known limitations of Unity's SSO integration:

  • When you sign in using SSO, you're automatically assigned to the organization that the SSO was configured for. You can switch organizations after signing in, and you still maintain access to other organizations that you belong to.
  • When you create a Unity ID account through SSO, your account is created without a personal organization. To be able to create new projects, you must manually create your own personal organization.
  • When you create a Unity ID account through SSO, your account is created without a password. To set up a password, you must select Forgot your password? from the login page and reset your password.
  • SSO isn't enforced by default.