SCIM provisioning – Assembled

Plans and permissions:

Set up and manage SCIM provisioning: Admin role
SCIM provisioning must be turned on for your company. To turn it on, contact our team.
You also need administrator access to your identity provider.

Use SCIM provisioning to keep Assembled accounts in step with your identity provider (IdP), such as Okta, Microsoft Entra ID, or OneLogin. When you add, change, or remove someone in your IdP, Assembled creates, updates, or deactivates their account, so you don’t have to do it by hand.

To open it, go to Configure > SCIM provisioning.

What SCIM provisioning does

In your IdP	In Assembled
Assign a person to the Assembled app	Creates their account, or updates the active account that has the same email address
Change their name or email address	Updates their name or email address
Change their groups	Updates their role, if your groups are mapped to Assembled roles
Remove them from the app, or deprovision them	Deactivates their account, the same as deactivating them in Assembled

SCIM provisioning manages sign-in accounts and roles. It doesn’t:

Set up team member details, such as site, teams, channels, queues, or schedules. Add those in People management after people are provisioned.
Send invitation emails, because people sign in with single sign-on. See SAML single sign-on.
Sync custom SCIM attributes.

How sync works

Assembled connects to your IdP through WorkOS Directory Sync. Your IdP sends SCIM updates to WorkOS, and Assembled picks them up from WorkOS and applies them. You don’t point a SCIM endpoint at Assembled directly.

Assembled checks WorkOS for new changes regularly. Changes usually appear in Assembled within a few minutes, not instantly.
Changes are applied in the order they happened. A sync finishes only when every change in it is applied.
If a change fails, SCIM provisioning shows the error, and Assembled tries again in the next sync.

For help with people who don’t sync as expected, see Changes in your IdP don’t show up in Assembled.

What syncs from your IdP

Attribute	When it’s applied	Notes
Email	When a person is created or updated	How Assembled finds the person. When an email address changes in your IdP, Assembled uses the previous one to find the account, then updates it.
First name, Last name	When a person is created or updated	Updated only when the value changes.
Role	When a person is created or updated	Comes from your group-to-role mapping. See How roles are assigned.
Group membership	When a person is created or updated	Used only to choose the role. Groups aren’t stored in Assembled.

How roles are assigned

Your IdP sends each person’s groups to WorkOS.
Assembled uses your group-to-role mapping to choose their role.
When someone’s groups change in your IdP, their Assembled role updates to match.

If someone belongs to a mapped group, they get that group’s role. A new person who isn’t in any mapped group, or who’s added before you have a mapping, gets the Basic role. Someone who already has an account keeps their current role. To change your mapping, contact our team.

What happens when you remove someone

When you remove someone from the Assembled app in your IdP, or deprovision them, Assembled deactivates their account, the same as deactivating them in Assembled. Their account, team member details, past schedules, and metrics are kept, not deleted. If they’re staffable, their End date is set to the day they’re deactivated, unless it’s already earlier.

Suspending someone in your IdP doesn’t deactivate them in Assembled unless your IdP also deprovisions them. To remove access, remove them from the Assembled app or deprovision them.

What happens when you add someone back

If you add someone back in your IdP after SCIM deactivated them, Assembled creates a new account for them instead of restoring their deactivated account. If you need their earlier history or settings, restore their earlier account in Assembled before you add them back, or contact our team.

Before you start

SCIM provisioning must be turned on for your company. If you don’t see SCIM provisioning in the Configure menu, contact our team.
You need to be an administrator in your IdP.
Your IdP must support SCIM 2.0. Okta, Microsoft Entra ID, OneLogin, and the other providers that WorkOS Directory Sync supports all work.

Set up SCIM provisioning

Turn on SCIM provisioning

Go to Configure > SCIM provisioning. The status shows Not configured.
Select Enable SCIM provisioning.

Assembled prepares the connection and copies your Assembled roles to WorkOS, so they can be mapped to your groups. The page then shows that directory sync is being set up.

Connect your IdP

On SCIM provisioning, select Set up integration. You’re taken to the WorkOS Admin Portal.
Connect your IdP and finish the SCIM setup, following the steps in the portal for your provider. For provider-specific details, see the WorkOS Directory Sync documentation.
In your IdP, assign at least one person to the Assembled app, so there’s something to sync.

To change the connection later, select Manage SCIM configuration on SCIM provisioning.

Map groups to roles

To give people their Assembled role based on their groups in your IdP, you need a group-to-role mapping. Our team sets it up for you. Contact our team with:

The IdP group names you want to map
The Assembled role each group should get

Important: Without a mapping, new people are added with the Basic role. You can change roles by hand in Assembled, but a mapping set up later can replace them.

Check that sync is working

Go to Configure > SCIM provisioning and check the message under Directory sync (SCIM):

You see	What it means
Not configured and Enable SCIM provisioning	SCIM provisioning isn’t turned on yet.
Setting up directory sync	It’s turned on, but no sync has finished yet.
Synced, with how long ago	Sync is working. This is when the last sync finished.
An error occurred while syncing directory data.	The last sync failed. Hover over the message to see the error. See Changes in your IdP don’t show up in Assembled.

Troubleshooting

Changes in your IdP don’t show up in Assembled

Changes you make in your IdP should appear in Assembled within a few minutes. Sometimes they don’t: the SCIM provisioning page is missing, setup doesn’t finish, a sync fails, someone isn’t created or deactivated, or someone has the wrong role. Each of these has a cause you can check.

Cause	How to tell	What to do
SCIM provisioning isn’t turned on for your company, or you aren’t an Admin	SCIM provisioning isn’t in the Configure menu. Only Admins see it, so check your Role in Manage team > People management, or ask an Admin.	If you’re an Admin and don’t see it, contact our team to turn it on.
Setup isn’t finished in the WorkOS Admin Portal	Configure > SCIM provisioning still shows Setting up directory sync.	Finish setup.
The last sync failed	Under Directory sync (SCIM) on Configure > SCIM provisioning, you see An error occurred while syncing directory data. instead of Synced and how long ago the last sync finished. Hover over the message to read the error.	Select Manage SCIM configuration and check your IdP connection in the WorkOS Admin Portal. Assembled tries again in the next sync, and if the error stays, contact our team with the error message and roughly when it started.
The person isn’t assigned to the Assembled app in your IdP	One person is missing but others sync, and Configure > SCIM provisioning shows a recent Synced time. In your IdP, the person isn’t assigned to the Assembled app.	Assign the person to the Assembled app in your IdP, and wait for the next sync.
The person has a deactivated account in Assembled	One person is missing but others sync. In Manage team > People management, with the Status filter set to Inactive, they have an older, deactivated account with the same email address.	When someone SCIM deactivated is added back, Assembled creates a new account for them. To keep their history, restore their earlier account before you add them back: see Deactivate, delete, and restore people.
There’s no group-to-role mapping, or the person isn’t in a mapped group	The person has the Basic role, or a role you didn’t expect. In your IdP, check which groups they’re in: without a group-to-role mapping, everyone SCIM adds gets the Basic role.	To set up or change the mapping, contact our team with your IdP group names and the Assembled role for each. If the mapping is set up and the person is in the group you expect, wait a few minutes for the next sync.
The person was suspended instead of removed in your IdP	The person is still active in Assembled, and in your IdP they were suspended rather than removed from the Assembled app or deprovisioned. Suspending someone doesn’t always send a change that Assembled acts on.	Remove them from the Assembled app, or deprovision them, in your IdP, then check SCIM provisioning for a sync error and wait for the next sync. To remove access right away, deactivate them in Assembled.

If it still doesn’t look right, chat with our team and include the email address of the person who isn’t syncing as expected, what you changed in your IdP and when, the message on Configure > SCIM provisioning with any error details or a screenshot of it, and what you’ve already tried.

Finish setup in the WorkOS Admin Portal

On SCIM provisioning, select Set up integration and finish connecting your IdP in the WorkOS Admin Portal.
In your IdP, assign at least one person to the Assembled app. Nothing syncs until someone is assigned.
Check SCIM provisioning again after a few minutes.