User's Guide to SCIM

📌 This feature is for our Enterprise Plan customers

If you wish to upgrade your plan to Enterprise, please book a demo

What is SCIM?

SCIM (System for Cross-domain Identity Management) is a protocol that serves as a universal method for sharing identity data between different entities. It is an openly accepted standard used to streamline the procedure of authorizing individuals or teams to use cloud-based programs.

Why do I need it?

With SCIM provisioning, your identity provider (IdP) automatically sends user data to connected apps whenever someone joins, leaves, or changes roles in your organization. Apps can then instantly create, update, or deactivate the user’s account and close any active sessions.

SCIM also supports bulk actions, so admins can create or update many user accounts at once—useful for large teams or moments like mergers where hundreds or thousands of accounts need adjustments.

This guide will show you how to set up SCIM sync using the WorkOS flow.

Requirements for a SCIM setup

To set up a SCIM v2.0 directory sync connection, you would need to have:

A Synthesia Organization
SSO enabled through our service provider WorkOS

✍️ If your SSO was configured before mid-July 2025, we will need to provision a new setup, please contact the Support Team

Once the requirements are met, please reach out to our Support Team who will send you a link with an individual directory sync setup guide.

Configuring Directory Sync

After the Support Team sends you the setup link, please click on it and follow the Admin Portal instructions
You’ll see a list of available IdPs. Select the one you’ve already set up SSO with, then follow its guidelines to configure your directory sync settings.
Once done, you will be able to test the sync.

Okta Configuration

Okta setup

Step 1: Add Provisioning to SAML Application

Go to the General tab of your existing Synthesia Okta SAML application, where you want to enable SCIM provisioning.
Click Edit under the App Settings tab.
Select the SCIM option and save.

Step 2: Configure API Integration

Select the Provisioning tab.
Under the SCIM Connection section, click Edit.
Copy and paste the values given in the setup guide into the SCIM connector base URL and Unique identifier field for users fields.
Under Supported provisioning actions, select the following options:
- Push new users
- Push profile updates
- Push groups
Select HTTP Header as the Authentication Mode. Copy the Authorization bearer token (given in the setup guide) into the Authorization field.
Click Test Connector Configuration to validate the credentials. Click Save.

Step 3: Set up Attribute Mapping

The Synthesia application expects certain attributes when syncing. Basic attributes like a user’s name or email are already mapped, and so are not present below.

To see the names of attributes that you can map from your Directory Provider:

Access the Provisioning tab in the Okta admin console.
Select To App in the left navigation menu.
Scroll down to the [Your Application’s Name] Attribute Mappings section. You should see a table containing attributes available to the application. Any of the camel-cased values can be used as a value for an application attribute.

For example, if you wanted to use the value of Username for an attribute mapping, you would enter userName as the Directory Provider Value. Map attributes from your directory provider’s responses to the attributes shown at this stage of the setup guide (the fields should look like below).

Step 4: Configure Provisioning Actions

With the Provisioning tab in the top menu navigation still selected
Select the To App tab in the left navigation menu.
Locate the Provisioning to App section.
Click Edit. Enable the following actions:
- Create Users
- Update User Attributes
- Deactivate Users

Step 5: Assign People and Groups

In the top navigation menu, select the Assignments tab.
Click the Assign button
Select Assign to People.
Locate those appropriate people and click the Assign button next to each.
To complete assigning the users, click Save and Go Back.

✍️ Users assigned to Synthesia in the IdP before setting up the directory sync won’t be automatically mapped, so they will need to be provisioned manually.

Step 6: Push Groups

Select the Push Groups tab in the top navigation menu.
Click the Push Groups button.
Select Find groups by name.

🚨 Okta advises using separate groups for push groups and group assignments⁠. Otherwise, memberships won’t be accurately reflected without manual group pushes for membership changes.

Locate the appropriate group, select it and click Save to push your group to Synthesia.

If there were SSO users that had been previously provisioned, you will need to provision these users again. Navigate to the Assignments tab, then click the Provision User button. This will start the job of re-provisioning all users.

Step 7: Test Directory Connection

Verify that the configuration is correct and start syncing the directories. A full sync usually takes a few minutes, but may be longer depending on the directory size.

Entra ID (Azure AD) Configuration

Entra ID (Azure AD) Setup

Step 1: Create an Entra ID Application

Sign in to the Microsoft Entra admin center⁠.
In the left navigation menu, expand the Identity section.
Expand the Applications sub-section.
Select the Enterprise applications tab. Click New application.
On the Browse Microsoft Entra Gallery page, click Create your own application.
Enter an appropriate app name, such as Synthesia.
Select the Integrate any other application you don’t find in the gallery (Non-gallery) option.
Click Create.

Step 2: Configure Admin Credentials

In the left navigation menu, select the Provisioning tab.
In the new left navigation menu, select the Overview (Preview) tab.
Click Connect Your Application.
Locate the Tenant URL and Secret Token fields.
Copy the values given in the setup guide and paste them into their respective fields in the Entra ID admin center.
- The aadOptscim062020 query param in the Tenant URL fixes known Entra ID SCIM 2.0 compatibility issues. To ensure reliable behavior, do not remove this from the Tenant URL.
Click Test Connection to confirm that your connection has been correctly configured.
Click Create.
Step 3: Configure Attribute Mapping

Scroll down and expand the Mappings section.
Ensure that the group and user attribute mappings are enabled and correct. The default mapping should work, but your specific Entra ID setup may require you to add a custom mapping.
Click on Provision Microsoft Entra ID Groups and Provision Microsoft Entra ID Users to validate the mappings.
Make sure that you are mapping objectId to externalId within the Attribute Mappings section.
Ensure the emails[type eq “work”].value SCIM attribute has a valid email value.
- For cloud-managed users, confirm that a known email attribute, such as UPN, is being pulled from the mail attribute in Exchange.
- If your directory has synchronized-users, make sure that the userPrincipalName attribute is mapped to emails[type eq "work"].value.

Step 4: Configure Application Attribute Mapping

You need to map additional attributes.

Return to the Provisioning tab.
Click on the Provision Microsoft Entra ID Users link to view the attributes that can be mapped from Entra ID.
For example, if you wanted to use the value of jobTitle, you would enter title in the Directory Provider Value field.

Step 5: Assign Users & Groups

In order for your users and groups to be synced to Synthesia you will need to assign them to your Entra ID Application.

In the left navigation menu, select the Enterprise applications tab.
Click the All application sub-tab.
Choose on your application.
In the left navigation menu, select the Users and groups tab.
Click Add user/group.
In the Users section, click on None selected.
In the drawer that opens on the right, select appropriate users to add. Click Select.
When finished, click Assign.
In the left navigation menu, select the Provisioning tab.
Scroll and expand the Settings section.
Ensure that the Scope is set to Sync only assigned users and groups.
Ensure the Provisioning Status is set to On.