SCIM Management

The Descope service supports the ability to dynamically configure user data via SCIM (System for Cross-domain Identity Management). Descopers can configure SCIM provisioning from their IdP, which will then be able to push user profile updates as well as groups.

Once SCIM provisioning is configured within the environment, when users are deactivated, their contact details change, or their roles or groups change, the changes will be pushed to the Descope instance. When the JWT is refreshed, these changes will take effect on the user's session. Having SCIM provisioning allows for deactivating users from your IdP and the users being unassociated from your application. SCIM also enables organizations to increase or decrease access levels of users within the application for different users from your IdP.

The Descope API then opens endpoints to load, create, update, and delete SCIM-related configurations. The Descope SDK does not support the same SCIM endpoints as the API.

The below guides cover configuring SCIM provisioning within Okta and Azure as examples, but it applies to other IdPs. Descope's available API endpoints for SCIM management are detailed within the SCIM Management API References. Note that SCIM configurations are not visible within the Descope UI.

Configuring SCIM provisioning within Okta as an IdP

If you wish to configure SCIM provisioning within Okta, you can follow our guide here that uses our dedicated Okta Integration app. If you don't wish to use this integration app, or already have a custom app in use, then follow the guide below instead.

Prerequisites for configuring SCIM

You must already have SSO enabled and users logging in via SSO within your Descope tenant.
You must create a tenant for your customer and be associated with an access key with the Tenant Admin role. It is essential to note the access key's expiration; if it is expired or revoked, the SCIM provisioning integration will no longer work. For more information on creating tenants, see the Tenant Management Guide. For more information on access keys, see the Access Key Management Guide.
Within your IdP, you should have People and Groups assigned to the application.

Note

If you want to manage your users via SCIM, it makes sense to turn off JIT Provisioning under your Tenant Settings in the Descope Console. This will ensure that SCIM manages user attributes and nothing is overwritten by your SSO IdP.

Enable SCIM Provisioning within your IdP

The first step in the configuration of SCIM provisioning within Okta is to go to the General tab within your Okta application and check the box for Enable SCIM provisioning. Once you have done this, you will see the provisioning tab added to your Okta application.

Configure SCIM Connection

The next step is to navigate to the Provisioning tab within your application. Here you will provide the following:

SCIM connector base URL: https://api.descope.com/scim/v2
Unique identifier field for users: email
Supported provisioning actions: Push New Users, Push Profile Updates, and Push Groups - select these two checkboxes.
Authentication Mode: Select HTTP Header
Authorization: This will be the bearer. The format for this bearer is ProjectId:AccessKey. This AccessKey is the one referenced within the prerequisites and the Access Key associated with the tenant you are configuring SCIM provisioning.

Once you have populated these fields, you will test the connection configuration. This test will return a box that confirms Create Users, Update User Attributes, and Push Groups are connected successfully.

The next step is to go to the To App section within the Provisioning settings. Here you will check the checkboxes to enable Create Users, Update User Attributes, and Deactivate Users.

Validating Assignments and Push Groups

The user must verify that the Assignments have correctly synced to the Descope service via SCIM provisioning. If there are errors within people or groups within the Assignments tab, you will need to review these items.

After successfully configuring the SCIM connection, you will have a new tab within the application for Push Groups. From this tab, you can push groups to the Descope tenant, mapped to the Descope roles you defined in the SSO authentication settings. These groups that are pushed to the Descope service will then be usable within API calls to the Descope service.

Once your tenant utilizes SCIM provisioning, all changes from the IdP will be reflected in the Descope service and synced to the user's logins and sessions. These changes occur on the next refresh of the user's session JwT.

Configuring SCIM provisioning within Azure as an IdP

This guide will assume that you have already configured a working Descope application within Azure.

Note

SCIM Provisioning within Azure runs on defined cycles and may not be immediate. For more details, review Microsoft's documentation around the time to provision users.

Prerequisites for configuring SCIM

You must already have SSO enabled and users logging in via SSO within your Descope tenant.
You must create a tenant for your customer and be associated with an access key with the Tenant Admin role. It is essential to note the access key's expiration; if it is expired or revoked, the SCIM provisioning integration will no longer work. For more information on creating tenants, see the Tenant Management Guide. For more information on access keys, see the Access Key Management Guide.
Within your IdP, you should have People and Groups assigned to the application.

Note

Enable SCIM Provisioning within your IdP

The first step in the configuration of SCIM provisioning within Azure is to go to the Provisioning section within your enterprise application.

Then click Get Started.

Configure SCIM Connection

The next step is to change the provisioning mode to Automatic, then you will provide the following:

Tenant URL: https://api.descope.com/scim/v2
Secret Token: This will be the bearer. The format for this bearer is ProjectId:AccessKey. This AccessKey is the one referenced within the prerequisites and the Access Key associated with the tenant you are configuring SCIM provisioning.

Once you have populated these fields, you can test the connection and see the successful test result in the top right.

Once you have a successful test, click save towards the top left.