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.

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