Directory provisioning (SCIM)

Directory provisioning uses SCIM 2.0, a standard protocol for syncing accounts, to create, update, and deactivate organization members from your identity provider. Map directory groups to workspace access, permission groups, or the organization admin role.

Configure SSO separately for authentication. SCIM can manage membership without a saved SSO provider.

Before you start

• On Sim Cloud, use an Enterprise organization and an organization owner or admin account.
• Verify every email domain you will provision. Sim refuses account creation or an email change to an unverified domain.
• On self-hosted deployments, enable SSO to reach Single sign-on → Provisioning, and enable SCIM. The enterprise master pair enables both; individual setup uses SSO_ENABLED, NEXT_PUBLIC_SSO_ENABLED, SCIM_ENABLED, and NEXT_PUBLIC_SCIM_ENABLED. See Self-hosted SSO setup and Deployment and upgrades.

Plan membership and access

If your organization already uses SAML or OIDC, keep that sign-in configuration. SCIM adds directory synchronization alongside it. Configure these four controls separately:

Create the workspaces and permission groups in Sim before mapping directory groups. For example, map a pushed Finance group to Finance workspace → Write and to a dedicated Finance policy permission group scoped to that workspace. These can be two mappings on the same directory group.

Configure a restrictive organization default permission group for people who retain workspace access after leaving a mapped policy group. Sim selects one governing policy per person and workspace; it does not intersect every policy attached to their directory groups. Review policy selection and conflicts before rolling out overlapping groups.

What it does

Deactivation itself does not withdraw grants. Group or mapping changes can still withdraw access and reassign ownership while someone is suspended. A deactivated member keeps their seat until removed from the organization.

Deactivation stops the person's active Chat runs. Reactivation permits new runs; it does not resume runs stopped during suspension.

Deactivation deletes the member's sessions and stops personal API-key authentication when it completes. Organization security-version invalidation reaches cached browser sessions on other application instances within up to 60 seconds.

Sim refuses directory suspension or removal of an organization owner. Transfer ownership in Sim first.

Match an existing account

Sim links an account already in your organization or in no organization, using its verified-domain email. An account in another organization causes a conflict: a Sim account can belong to only one organization, so remove it there before provisioning here.

New members follow the organization's seat policy. Fixed-seat plans reject a join when full; add seats and let the provider retry. Team seat policies grow the billed seat count with membership. Cloud SCIM availability still requires Enterprise.

Enable provisioning

1. 1

   Verify domains

   Verify each provisioned email domain under Settings → Organization → Single sign-on → Domains. This prevents a directory from claiming addresses its organization does not own.

2. 2

   Enable the connection

   Open Single sign-on → Provisioning and turn on Enable directory provisioning. Copy the Base URL under Connection:

   https://<your-sim-domain>/api/scim/v2
   

3. 3

   Issue a token

   Under Tokens, choose Never expires, Expires in 90 days, or Expires in 1 year, then select Issue token. Copy the token before closing the dialog; Sim shows it once.

   At most two tokens can be active. To rotate, issue a replacement, update the provider, confirm a successful provisioning request, then revoke the old token.

4. 4

   Configure the provider

   OktaMicrosoft Entra IDOneLoginJumpCloud

   Follow Okta provisioning for integration selection, setup, and lifecycle checks. The evaluation SCIM 2.0 Test App (Header Auth) template expects the complete Authorization header in API Token:

   Bearer <your-sim-token>
   

   Classic OIDC apps need a separate provisioning integration; OIDC apps created in the newer Okta Integration Wizard can support SCIM. The guide separates evaluation templates from production integration requirements. Keep app-assignment groups separate from Group Push groups.

   Okta sends deactivation rather than SCIM user DELETE, so offboarding suspends access while retaining membership and the seat.

5. 5

   Map directory groups

   Under Provisioning → Group mappings, map each synced group to one or more targets:

   • A Permission group, which governs models, integrations, and capabilities in its selected workspaces. Create and configure it in Sim first; this mapping does not grant workspace access.
   • A Workspace, with Read, Write, or Admin access.
   • The Organization admin role.

   When multiple groups grant the same workspace at different levels, the strongest grant wins. The organization's default permission group cannot be a mapping target.

   Under Provisioning rules → Manage rules, Match permission groups by name maps new or renamed directory groups to existing non-default permission groups with an exact, case-sensitive name match. Sim does not create permission groups. These mappings are labeled Automatic. A rename updates automatic mappings and preserves manually added ones.

   For groups already synced before enabling name matching, select Reconcile now or wait for scheduled reconciliation.

   Turning off name matching stops future automatic matching; it does not remove existing mappings. Before removing a mapping whose target still has the same name, turn off Match permission groups by name or change the names so they no longer match. Otherwise a later group push or reconciliation can recreate it. A manually added mapping keeps its target when the directory group is renamed.

   A person can belong to only one explicit permission group for a given workspace. A conflicting policy assignment can be skipped even when the directory group itself synchronizes successfully. Group mappings shows how many directory members are not assigned to each mapped policy. Open Permission groups, resolve the overlapping membership or workspace scope, then select Reconcile now. Confirm the warning clears and the person's effective restrictions are correct.

   

How access is withdrawn

Sim tracks grants made through directory mappings. Removing a member from a group or removing its mapping withdraws the tracked access.

Other directory mappings and independent access can still keep the person in a workspace. Removing a permission-group membership changes their governing policy; it does not remove workspace access. Sim then uses another applicable workspace policy, the organization default, or no permission-group restrictions if neither exists. An empty mapped group applies to nobody and never turns into an all-members policy. Verify both workspace access and the fallback policy when testing a removal.

Lock managed membership is enabled by default on a new connection. It makes the directory authoritative for provisioned members: Sim refuses manual invitations, workspace grants, workspace role changes, and organization role changes for them. Manual access already held when a mapping begins covering it becomes directory-managed and is withdrawn with that mapping. Administrators can still remove access in an emergency.

The lock does not prevent editing permission-group membership directly in Sim. A manual removal can be restored by reconciliation, and a manual addition to an overlapping policy can block a directory assignment. Manage mapped policy membership through the directory and check Group mappings for unassigned members after resolving conflicts.

With locking off, prior manual workspace access is preserved. If a member had manual Read access and a directory mapping raises it to Admin, removing the mapping restores Read. A role manually raised above the directory's level also remains. Older grants have a baseline limitation.

You can manually invite people the directory does not manage. For managed members with locking on, grant access through directory groups.

Provisioning and SSO together

An active provisioned member can authenticate through SSO configured for the same verified domain. Both systems resolve to the same account.

To prevent SSO from adding new organization members, enable Provisioning rules → Manage rules → Disable just-in-time provisioning. While the SCIM connection is active and entitled, this overrides Sign-in → First sign-in → Automatic. Existing members can still sign in, including members added by invitation; they do not all have to be SCIM-provisioned.

Inspect activity and reconcile access

Connection switches, rules, tokens, and mappings save immediately. Provisioning has no page-level Save button.

Provisioning → Activity shows recent authenticated requests, their status, and failure details. A wrong, expired, or revoked token cannot be associated with a connection, so its authentication error appears only in the provider's logs.

Reconcile now reapplies stored group memberships, mappings, and changed connection rules. It does not fetch changes from Okta or Entra. If a directory change has not reached Sim, inspect the provider's provisioning job and retry or repush there first.

For scheduled reconciliation, call GET /api/cron/scim-reconcile with the configured CRON_SECRET. Helm and production Docker Compose include an hourly schedule when their cron service is configured and running. This endpoint runs directly; it does not require Trigger.dev. See Background schedules.

Disable provisioning

Turning the connection off stops synchronization; it does not reverse suspension or prior access changes. Deactivated members stay deactivated. To restore an account without the directory, remove it from the organization and invite it again.

While the connection is disabled, Lock managed membership and Disable just-in-time provisioning no longer apply. Manual membership changes and the SSO provider's first-sign-in setting govern those operations again. Review them before disabling the connection; disabling synchronization is not an offboarding action.

Deployment and upgrades

Apply database migrations before the new application code. The SCIM tables and suspension fields are additive, allowing older code to run against the expanded schema during rollout.

After SCIM has suspended accounts or established managed access, rolling back to code that predates SCIM is unsafe: it cannot enforce those restrictions. Disabling synchronization does not undo suspension or restore earlier membership semantics.

Migration 0325_scim_manual_workspace_baseline tracks prior manual workspace access, but cannot reconstruct levels overwritten by older SCIM code. Review existing directory-owned grants before withdrawing mappings with locking off. Restore prior manual access explicitly where needed.

Protocol reference

Sim stores and returns userName in lowercase. Group display names are unique within a connection, ignoring case. Unmodeled top-level attributes and custom schema extensions are retained; a PUT preserves those it omits. Passwords are neither stored nor returned. Sim controls id, meta, and group membership.

Related docs

• Single sign-on
• Verified domains
• Okta provisioning
• Microsoft Entra provisioning
• Permission groups