SCIM

Integration overview

• The Unity SCIM API is a REST API. This API uses the JSON message structure.
• Unity's SCIM service uses basic authentication or authentication based on long-lived bearer tokens with a Unity service account. Your IdP must support one of these two authentication methods 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

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

Data mapping

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

  givenName

  and

  familyName

en_US

Important considerations

Data mapping

• 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

• 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

• 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

1. Configure SCIM with the IdP of your choice:
   • Configure SCIM with Okta
   • Configure SCIM with Entra
   • Configure SCIM with JumpCloud
2. Optionally, enforce SCIM provisioning