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. However, these two approaches should not be used together for the same tenant.

Important: Do not enable both SCIM and JIT for a single tenant. If both are active, SSO logins may overwrite SCIM-managed attributes or group assignments. To use SCIM as the source of truth, JIT provisioning should be disabled under Tenant Settings.

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.

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