Provision users with SCIM

Automate the provisioning and deprovisioning of users

읽는 시간 6분

최근 업데이트: 10일 전

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

Implement SCIM provisioning for these purposes:

Onboard users without manual work. When you add a user to your IdP, your IdP provisions a Unity account for them.
Offboard users reliably. When you remove a user from your IdP, your IdP deprovisions their Unity account.
Keep user data consistent. Your IdP remains the single source of truth for the profile fields that Unity syncs.

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

Prerequisites

Before you can set up SCIM provisioning, ensure that you meet these prerequisites:

You must have the Owner or Manager user type within your organization. Read more about user types, roles, and permissions.
You must have at least one validated domain.
You must have enabled Enterprise SSO. SCIM provisioning builds on Enterprise SSO, so you can't enable it until Enterprise SSO is enabled.

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 authenticates as a Unity service account, using either an API key with basic authentication or a long-lived bearer token. Your IdP must support one of these two authentication methods. Read Configure a service account for SCIM.
Unity's SCIM listing endpoints follow the pagination guidelines by the Internet Engineering Task Force (IETF).

Configure SCIM

Setting up SCIM provisioning takes four steps:

Configure a service account for SCIM. This is the identity that your IdP authenticates as.
Configure SCIM in your IdP, using the SCIM base connector URL from the Unity card and your service account credentials: Okta, Microsoft Entra, or JumpCloud.
Enable SCIM in Unity.
Optionally, enforce SCIM provisioning, which makes SCIM the only way to provision and deprovision the users in your validated domains.

Enable SCIM

Enabling SCIM lets your IdP provision and deprovision Unity accounts for the users in your validated domains, based on your IdP settings. No syncing happens until you enable it. Until then, your configuration is in place but your IdP can't create, update, or delete Unity accounts.

To enable SCIM, complete these steps:

In the Unity Dashboard, open the Account menu and select Manage organization.
In the Administration menu, select SSO & SCIM.
On the SCIM Provisioning & Enforcement tab, under step 3, Enable SCIM Provisioning, turn on the setting.

The status changes from Disabled to Enabled.
To check that your SCIM connection works, test syncs from your IdP.

Disable SCIM provisioning

To stop your IdP from managing Unity accounts, turn off the setting under step 3, Enable SCIM Provisioning, on the SCIM Provisioning & Enforcement tab. Syncing stops, and the accounts that SCIM has already provisioned remain in your organization.

Turning off SCIM provisioning also turns off SCIM provisioning enforcement, because there is nothing left to enforce.

Turning off Enterprise SSO turns off SCIM provisioning as well, along with everything else that depends on Enterprise SSO.

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

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:

SCIM attribute	Unity profile field	Comment
userName	Primary email	This SCIM attribute must contain the primary email address of the user.
displayName	Full Name	This SCIM attribute must contain the first name and the last name of the user.
locale	Location / Preferred language	If no value is provided, Unity sets the field to `en_US` by default.
active	Not applicable	This SCIM attribute indicates whether the account is active. If the account is inactive, Unity deletes it.

참고

In the Unity Dashboard, the user profile doesn't show all user attributes. For example, the user profile doesn't show the active attribute that the SCIM service populates from the IdP.

Important considerations

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

How data mapping affects syncing

Consider how data mapping affects syncing:

SCIM is configured 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 from the IdP, Unity overwrites existing values, including the values that users have manually modified in their Unity profile.

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 validated for an organization. The list includes any unverified accounts that users have manually created before the organization began using SCIM or SSO.

Limitations

Consider these 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)

기술 자료

Development

User Acquisition

Monetization

산업 분야

Unity Cloud

Get Started

Asset Manager SDKs and services