SCIM Best Practices

This guide explains how SCIM provisioning should be operated day-to-day once it is configured — in particular, how new employees should be onboarded so they can log in to your application, and how to avoid the most common mistake teams hit after they enable SCIM.

If you have not configured SCIM yet, start with the SCIM Management overview and the IdP-specific guides for Azure or Okta.

The Core Idea: Provisioning is Driven by the IdP

Descope is the SCIM service provider. It receives users and groups that the IdP pushes — it does not pull users from the IdP, and it cannot decide on its own that a given user should exist. Whether a user appears in Descope is determined entirely by whether the IdP decides to push them, which in turn depends on whether that user is assigned to the application on the IdP side representing Descope. Different IdPs use different names for this — Azure calls it an Enterprise Application, Okta calls it an app integration — but the concept is identical: the IdP only pushes users who are in scope for that application.

This has a few practical consequences:

• When a new employee joins your customer's organization, they will not be in Descope until their IT admin assigns them to the application on the IdP side (directly, or via a group that is assigned to the app).
• Descope cannot trigger provisioning. There is no "force resync" Descope can run against the IdP — that action lives in the IdP (for example, Provision on Demand in Azure).
• If JIT is disabled (the recommended setup when using SCIM) and the user was never assigned to the app, the user cannot log in. In most setups the IdP rejects authentication itself before Descope is reached. The exception is when SSO and SCIM use different IdP applications and the user is assigned to the SSO app but not the SCIM app — authentication then succeeds and Descope reports the user as unknown because no SCIM record exists.

Recommended Onboarding Pattern: Group-Based Assignment

The most common pain point we see is customers assigning users to the application on the IdP side one by one. This works initially, but it means every new hire has to be remembered and assigned manually. The next CISO, engineer, or finance hire who is not added to the app cannot log in — and from the customer's perspective, "SCIM is broken".

The recommended pattern is to assign a group — not individual users — to the application on the IdP side.

The group can be anything that reflects how your customer wants to gate access to your product:

Once the group is assigned, onboarding a new employee becomes a single step: add them to the group. The IdP will provision them to Descope on its next cycle, and any roles configured via group mapping will be applied automatically based on the groups the IdP sends along.

Group Mapping is Not Provisioning

This is the single most frequent point of confusion: customers see they have a group mapped to a role in Descope (for example, security → admin) and assume that membership in security is what causes the user to be provisioned. It is not.

• Provisioning decides who exists in Descope. It is controlled in the IdP, by who is assigned to the application on the IdP side.
• Group → Role mapping decides what an already-provisioned user can do. It is configured in Descope's SSO configuration and runs after the user has been pushed.

A user can be in a group that is mapped to a role in Descope and still never appear in Descope, if that user is not in scope for the IdP's provisioning of the app. The IdP must push the user first; only then does Descope apply role mappings to the groups it received.

Practically, this means a customer should ensure two things:

1. The user is in a group (or directly assigned) that the IdP will provision to the app.
2. The groups the IdP sends along with that user are mapped to the right Descope roles in the SSO configuration.

Provisioning Timing

SCIM provisioning is not instantaneous. Each IdP runs SCIM on its own schedule:

• Azure (Microsoft Entra ID) runs provisioning cycles approximately every 40 minutes by default. This interval is not configurable. To push a specific user immediately, use Provision on Demand in the Azure portal. See Microsoft's documentation for details.
• Okta typically provisions on assignment and on group changes, but the exact timing depends on the org's configuration.

When a customer reports that a newly assigned user "still can't log in", first check whether enough time has passed for the IdP's next cycle, and offer the Provision on Demand action as a way to verify.

Verifying Provisioning via Audit Logs

When a customer says a user cannot log in, the first question to answer is: did the IdP ever provision this user to Descope? The fastest way to answer that is the audit log.

1. Open the Audit and Troubleshoot page in the Descope Console.
2. Filter for SCIMEvent events, scoped to the relevant tenant.
3. Look for an event corresponding to the user in question (search by email or login ID).

If you see no SCIMEvent for that user, the IdP has not pushed them — which means they are not assigned to the application on the IdP side (directly or via group), or the IdP's last provisioning cycle has not run yet. The fix is on the IdP side.

For the full list of SCIM-related audit events, see the SCIM Audit Events reference.

Common Pitfalls

• Assigning users one by one. Works for the initial rollout, fails silently every time a new employee joins. Always prefer group-based assignment.
• Assuming Descope-side group mapping causes provisioning. It does not. The IdP must assign and push the user first.
• Disabling JIT without group-based assignment in place. Disabling JIT is the right call when SCIM is the source of truth, but only if every user who needs to log in is in scope for the IdP's provisioning. Otherwise users will fail authentication with no automatic recovery path.
• Forgetting that the same separation applies for deprovisioning. Removing a user from the assigned group in the IdP will cause the IdP to deactivate them in Descope. Removing them from a role-mapped group only changes their roles.

Related Reading

• SCIM Management — overview, access keys, token management, API access
• SCIM with Azure (Microsoft Entra ID)
• SCIM with Okta
• JIT Provisioning — when to use JIT instead of, or alongside, SCIM
• SSO Troubleshooting — SCIM Configuration Issues
• SCIM Audit Events