SCIM

To automate the exchange of user identity information with third-party identity providers (IdP), Unity uses the Cross-domain Identity Management (SCIM) standard.

Some IdPs support SCIM for the provisioning of users to Unity, such as Okta.

Integration overview

Integration overview

Unity implements the SCIM 2.0 protocol in this way:

• The Unity SCIM API is a REST API. This API uses the JSON message structure.
• Unity's SCIM service uses basic authentication with a Unity service account. Your IdP must support basic authentication as the method to authenticate to the SCIM service. When you create the service account, Unity generates the authentication token for it.
• Unity's SCIM listing endpoints follow the pagination guidelines by the Internet Engineering Task Force (IETF).

Supported resources and operations

Supported resources and operations

Unity's SCIM endpoints support user resources for these operations:

• Provision a user
• List users by email domain
• Retrieve user information
• Update or replace a user
• Delete a user

Unity's SCIM endpoints support all the operations that are listed in the Unity SCIM API documentation.

Data mapping

Data mapping

Unity profile fields are user attributes that are associated with a user's account, such as the username or display name. Users typically create or modify these values when creating a Unity account or when updating their profile.

Each IdP has its own attribute schema. In some cases, multiple user attributes in your IdP map to a single Unity profile field. For example, depending on your IdP, you can set the user's full name in one of these ways:

• A single attribute for the user's full name
• Multiple subattributes, such as givenName and familyName

All these practices work with SCIM, but attributes must carry the same information. For example, subattributes mustn't contain additional or optional information, such as a nickname for the user's full name.

This table shows the mapping from SCIM attributes to Unity's user profile fields:

Important considerations

Important considerations

Before configuring SCIM and automating the provisioning of users, consider the following important points.

Data mapping

Data mapping

Consider how data mapping affects syncing:

• You can set up SCIM for a particular email domain and for a single organization in Unity. This setup has these implications:

  • Unity adds, to this organization, all users whom the SCIM service has provisioned. If a user already has a Unity account, Unity adds the existing user to this organization and starts managing the user through SCIM.
  • After the SCIM service has provisioned a user, you can manually add this user to any other organization.

• The user email address in the IdP maps to the user email address in the Unity account. This setup has these implications:

  • The user email address must be unique. Requests to create a user who already has a Unity account result in an error.
  • The format of the user email address must be valid. Otherwise, Unity might reject provisioning and return an error. For example, in Okta, the userName attribute can contain an arbitrary string and the email address is optional.
  • If an email address is fake but its format is valid, Unity provisions the user but won't be able to send notifications to the user.
  • During syncing, Unity overwrites existing values, including the values that users have manually modified in their Unity profile.

Unverified user email addresses

Unverified user email addresses

Consider how Unity handles unverified user email addresses:

• If the SCIM service provisions a pre-existing Unity user whose primary email address is unverified, Unity ID purges the account password. This best practice prevents malicious actors from using a precreated password to sign in with a previously unverified account.

• The ListUser endpoint returns all accounts that belong to all domains that are verified for an organization. The list includes any unverified accounts that users have manually created before the organization began using SCIM or SSO.

Limitations

Limitations

Consider these limitations:

• Deletion of accounts

  Unity ID supports deleting accounts, but not deactivating accounts. Unity treats deactivation requests as deletion requests. To avoid losing user information on Unity's side, avoid attempting to temporarily deprovision a user who might want to reactivate their account later. Otherwise, you may have to recreate the account after deprovisioning.

• One-way syncing, from your IdP to Unity

  Unity doesn't support syncing from Unity to your IdP. If you sync data from Unity to your IdP, review all synced data. This data includes these users:

  • Users who have created their account directly in Unity ID
  • Users who utilize single sign-on (SSO) and whom you provision through SCIM and just-in-time (JIT)

Next steps

Next steps

Configure SCIM with Okta