SCIM Management

Descope supports SCIM 2.0 (System for Cross-domain Identity Management), enabling identity providers (IdPs) such as Okta, Azure, Ping Identity, and others to automatically provision, update, and deprovision users and groups in your Descope project.

Once SCIM provisioning is configured, updates made in the IdP—such as user creation, profile edits, group assignments, or deactivation—are automatically pushed to Descope. These updates are applied to user sessions the next time the user logs in or refreshes their session token (JWT).

SCIM enables centralized identity lifecycle management and ensures that Descope remains consistent with your IdP's directory.

Who Gets Provisioned: Assignment in the IdP

A common misconception is that enabling SCIM means "every user in the IdP can now log in". That is not how SCIM works. Provisioning is driven entirely by the IdP — a user only appears in Descope after the IdP decides to push them, which happens when the user is assigned to the application on the IdP side representing Descope (directly, or by being a member of a group that is assigned to the app). Different IdPs name this differently — Azure calls it an Enterprise Application, Okta calls it an app integration — but the concept is the same.

This means:

• Descope cannot provision a user on its own. Descope is the SCIM service provider; it only receives what the IdP sends.
• A new employee joining your customer's organization is not automatically provisioned to your app. Their IT admin must assign that employee to the application on the IdP side (in Azure, Okta, etc.).
• If a user is missing in Descope when JIT is disabled, the cause is almost always that the user was not assigned to the app in the IdP. In most setups this blocks login entirely — the IdP rejects authentication for unassigned users before Descope is reached. In setups where SSO and SCIM use different IdP applications, authentication can succeed via the SSO app and Descope will then report the user as unknown because no SCIM record exists.

See the SCIM Best Practices guide for the recommended onboarding pattern using group-based assignment, and the SSO troubleshooting guide for diagnosing provisioning failures.

Group Mapping vs. Provisioning

These two concepts are often confused but are completely separate:

A user mapped to a role via group mapping does not get provisioned because of the mapping. The IdP must first assign the user to the app and push them. Only then does Descope apply role mapping to the groups the IdP sent.

SCIM vs. JIT Provisioning

Descope supports both SCIM and Just-In-Time (JIT) provisioning via SSO.

What SCIM Can Do

SCIM provisioning in Descope allows your IdP to:

• Create and update user profiles
• Deactivate users and remove their access
• Create, update, and delete groups
• Assign users to groups

These are implemented in accordance with the SCIM 2.0 protocol and validated during IdP setup (e.g., via Okta's or Azure's provisioning tests).

SCIM groups are automatically mapped to Descope Roles. Read more about Group and Attribute Mapping below.

Group and Attribute Mapping

When groups are pushed to Descope via SCIM, they are interpreted as Roles. These roles are:

• Included in the user's JWT (roles claim, under the associated tenant)
• Are resolved using the same group mapping rules defined in the SSO configuration, ensuring consistency between SCIM and SSO logins

Similarly, SCIM-pushed user attributes (e.g., name, email, phone number, department) are stored in the Descope user profile and available in flows and session data.

Group-to-Role Mapping

Group mappings are configured in the SSO configuration and apply to both SCIM and JIT flows. For example:

• Group engineering → Role developer
• Group finance → Role auditor

If a SCIM or SSO login provides one of these groups, the mapped role will be assigned.

Default Roles

If no mapped roles are found from the user's groups, Descope assigns Default Roles, as defined in the same SSO configuration.

• These apply to both SCIM and JIT flows
• Useful for assigning fallback access (e.g., read-only) when group data is missing

Creating SCIM Access Keys

To authorize SCIM requests from your IdP to Descope, a bearer token is required in the following format:

Authorization: Bearer <ProjectID>:<AccessKey>

The Access Key must:

• Be scoped to a specific tenant
• Include the Tenant Admin role
• Be valid (not expired or revoked)

Option 1: Manual Access Key Creation

You can manually create an access key via the Descope Console, scoped to the relevant tenant. Combine this key with your project ID to form the required bearer token.

Option 2: Automated SCIM Access Key Creation

Descope offers two fully managed ways to create SCIM-compatible access keys for tenant administrators.

SSO Setup Suite

The Descope SSO Setup Suite includes a built-in option for tenants to configure SCIM themselves. This approach requires no manual access key handling and is ideal for enterprise self-service onboarding.

Create SCIM Access Key Flow Action

You can build custom onboarding flows that programmatically generate SCIM access keys using the Create SCIM Access Key action. This allows for flexible automation during tenant provisioning.

Managing SCIM Tokens

SCIM tokens can be rotated or revoked to maintain security and control over your SCIM integration. You can either Rotate token, Revoke token, or Rotate and Revoke token.

You can manage SCIM tokens in the Descope console in the Tenants page -> Authentication Methods -> SSO -> SCIM Provisioning or in the SSO Setup Suite.

Rotate

This operation creates a new SCIM token while keeping existing tokens active. To start using the new token, update your IdP's SCIM configuration. The old token remains valid until manually revoked.

Use this when:

• You want to test a new token before fully switching
• You need zero-downtime token rotation
• You're planning a gradual migration to a new token

Revoke

This operation revokes the current SCIM token without creating a new one. This effectively disables SCIM provisioning for the tenant.

Use this when:

• You want to disable SCIM provisioning entirely
• You're switching to JIT (Just-In-Time) provisioning instead

Rotate and Revoke

This operation creates a new SCIM token and immediately revokes the old one. Your IdP will need to be updated with the new token to continue SCIM provisioning.

Use this when:

• You suspect a token may have been compromised
• You're conducting regular security maintenance
• You need to invalidate the old token immediately

SCIM Session Behavior

SCIM updates do not immediately revoke existing user sessions. Instead:

• Changes are applied on the next login or token refresh
• Role changes, deactivations, and profile updates take effect without requiring user input

To enforce stricter security policies, consider shortening session durations or logging a user out (revoking their session) when group membership or access levels change.

SCIM API Access

Descope provides a SCIM Management API for programmatic management of SCIM configurations. This includes endpoints to:

• View user and group records
• Validate SCIM push activity
• Revoke or rotate access keys
• Test provisioning status

Multi-Tenant and Multi-SSO Architecture

Descope is designed for multi-tenant SaaS environments and supports multiple SSO configurations per tenant. SCIM provisioning is tied to each SSO configuration, not just the tenant.

This allows:

• One tenant to support multiple IdPs (e.g., Okta and Azure)
• Each SSO configuration to have its own SCIM integration
• Fine-grained, isolated identity management for each IdP under the same tenant

SCIM Configuration Guides

Descope offers detailed setup guides for configuring SCIM provisioning with popular identity providers:

Each guide provides:

• Step-by-step setup instructions
• Attribute and group mapping guidance
• Troubleshooting and validation steps

For day-to-day operational guidance — how customers should onboard new users so they are automatically provisioned, why group mapping is not the same as provisioning, and how to debug "user can't log in" reports — see SCIM Best Practices.