Directory Sync (SCIM)

Directory Sync allows you to automatically provision and deprovision users in your Clerk application by connecting it to your organization's directory service via the SCIM protocol. When Directory Sync is enabled, changes made in your identity provider (IdP) — such as creating, updating, or removing users — are automatically reflected in Clerk.

This is especially useful for organizations that manage large user bases through an IdP like Okta or Microsoft Entra ID (formerly Azure AD), since it eliminates the need to manually manage user accounts across multiple systems.

How Directory Sync works

Once configured, your IdP pushes user changes to Clerk using the SCIM 2.0 protocol. Clerk acts as the SCIM service provider and handles the following operations:

• Create: When a user is assigned to the app in your IdP, Clerk automatically creates a corresponding user account. A user.created webhook event is fired.
• Update: When user attributes (such as name, email, or custom attributes) are updated in the IdP, Clerk syncs those changes automatically. A user.updated webhook event is fired.
• Delete / Disable: When a user is removed or deactivated in the IdP, Clerk deactivates the corresponding Clerk user and immediately revokes all of their active sessions. A user.updated webhook event is fired.

Directory Sync works in conjunction with your existing enterprise SSO connection. You must have a SAML or OIDC enterprise connection set up before enabling Directory Sync.

Directory Sync vs. JIT Provisioning

Just-in-Time (JIT) Provisioning creates user accounts on first sign-in. Directory Sync, by contrast, proactively keeps your Clerk user base in sync with your IdP — users are created before they ever sign in, and deactivated as soon as the IdP syncs the change to Clerk (which can take several minutes), without requiring a sign-in event.

For organizations that require prompt deprovisioning (e.g., when an employee leaves), Directory Sync is the recommended approach.

Enable and configure Directory Sync

Directory Sync is configured per enterprise connection. To set it up:

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select the enterprise connection you want to enable Directory Sync for.
3. Select the Directory sync tab.
4. Select Enable SCIM. Clerk will generate an Endpoint URL and a Bearer token in the Connection details card. Save these values since you'll need to provide them to your IdP.

Connect your identity provider

Once Directory Sync is enabled in Clerk, configure your IdP to point to Clerk's SCIM endpoint.

Okta

1. In the Okta admin dashboard, navigate to your enterprise app's Provisioning tab.
2. Select Configure API Integration and enable the Enable API integration option.
3. Paste the Endpoint URL from Clerk into the SCIM connector base URL field.
4. Set the Unique identifier field for users to userName.
5. Enter the Bearer token from Clerk into the API Token field.
6. Select Test API Credentials to verify the connection, then select Save.
7. Under To App, enable the operations you want Okta to push to Clerk: Create Users, Update User Attributes, and Deactivate Users. Select Save.
8. Under Attribute Mappings, confirm that email (user.email) is mapped and sent to Clerk. If userName is the user's email, you still need a separate mapping to email — Clerk requires both.
9. To sync groups for role mapping, switch to the Push Groups tab on the app's Provisioning section and enable Push Groups. Select the groups you want to push to Clerk and select Save.

Microsoft Entra ID

1. In the Azure portal, navigate to your enterprise application and select Provisioning.
2. Set Provisioning Mode to Automatic.
3. In the Admin Credentials section, paste the Endpoint URL from Clerk into the Tenant URL field.
4. Paste the Bearer token from Clerk into the Secret Token field.
5. Select Test Connection to verify, then select Save.
6. Expand the Mappings section and confirm that attribute mappings are configured for userName, name.givenName, name.familyName, email, and active.
7. Under Settings, set the Provisioning Status to On and select Save.

Synced user attributes

The following common user attributes are synced from your IdP to Clerk via SCIM. The exact SCIM attribute values depend on your IdP. Clerk automatically maps these for you.

Custom attribute mapping

Custom attributes let you sync additional user data from your IdP (such as department, employee_id, or cost_center) into Clerk's publicMetadata. When Directory Sync is enabled, SCIM becomes the exclusive source for these values, and they become read-only in Clerk until Directory Sync is disabled.

Attribute definitions are configured at the enterprise connection level and shared between your SSO and SCIM connections. For a full overview of how the shared attribute pool works and how to configure it, refer to Custom Attribute Mapping.

How SCIM attribute mapping works

Clerk exposes a /Schemas endpoint that your IdP queries to discover what attributes Clerk accepts. In addition to the standard User schema, Clerk advertises a custom extension schema (urn:clerk:scim:schemas:extension:custom:2.0:User) that accepts any attribute name and maps it directly to the corresponding publicMetadata key.

To configure SCIM attribute mapping for a custom attribute:

1. First, define your custom attributes at the enterprise connection level.
2. In the Clerk Dashboard, navigate to the Directory sync tab on your connection.
3. Scroll to the Attribute mapping card. In the Custom attributes section, select Map custom attribute.
4. In the SCIM attribute field, enter the SCIM schema path your IdP sends (e.g., urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department).
5. In the Clerk User attribute dropdown, select one of your custom attributes.
6. Select Map attribute.
7. In your IdP, ensure the attribute is configured to be pushed via SCIM.

For example, you might map the shared department attribute to urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department in Okta.

Role mapping

Role mapping lets you automatically assign Clerk roles to users based on their IdP group memberships. This eliminates manual role management in Clerk and lets your IdP serve as the single source of truth for access levels.

You must link the enterprise connection to an organization to use Directory Sync role mapping. The role mapping uses the linked organization's role set. If you delete a role that's associated with a role map, Clerk will remap the organization member roles.

When a member's role is assigned through a group-to-role mapping, that role assignment cannot be manually overridden in the Clerk Dashboard — it's controlled entirely by the member's IdP group memberships and is re-resolved on the next sync. Members whose roles are not sourced from a mapping remain manually editable, and all members become manually editable again when Directory Sync is disabled. Role definitions themselves (names, permissions) are always managed in Clerk.

How it works

When your IdP pushes group data to Clerk via SCIM, Clerk stores the groups and their memberships. You then configure a mapping in the Clerk Dashboard from each IdP group to a Clerk role. When a user is added to a group in the IdP, Clerk assigns the mapped role. When a user is removed from a mapped group, Clerk re-resolves their role from the remaining mapped groups in precedence order. They only fall back to the organization's default role if no mapped groups remain.

Configure role mapping

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select the enterprise connection with Directory Sync enabled.
3. Select the Directory sync tab and scroll to the Role mapping card.
4. Select Map role. In the dialog, pick a SCIM group and the Clerk role it should map to, then select Map role to save.
5. Repeat for each group you want to map.

Multi-group precedence

If a user belongs to multiple groups that each map to different Clerk roles, Clerk applies the role according to the order of the mappings in the Dashboard. On the Directory sync tab, in the Role mapping card, use the drag handle on each row to reorder the mappings — the mapping highest in the list takes precedence when a user belongs to multiple mapped groups.

Group deletion behavior

When a group is deleted in your IdP, Clerk removes the group and re-resolves each affected user's role from their remaining mapped groups in precedence order. Users only fall back to the organization's default role if they have no mapped groups left. When a role mapping changes, a background job queues role reassignment for all affected group members.

View directory users

The Directory users tab (visible once Directory Sync is enabled) on your connection shows every user that has been provisioned through Directory Sync. For each user you can see their current status (Active or Deactivated) and when they were last synced from the IdP. Selecting a user takes you to their user page.

This is useful as a first debugging step. If a user isn't appearing in your app after being assigned in the IdP, check here to confirm they were actually provisioned and that their status is Active.