How SCIM deprovisioning works

User deprovisioning is about removing access from users when they no longer need it. It involves disabling user accounts and access to applications and data. It is a crucial and time-sensitive process since every employee account left active post-employment or after a role change is a potential backdoor for unauthorized access, data leaks, and security breaches.

Nowadays, when every enterprise uses many different products for many different things and their employees need varying levels of access to each one, provisioning and deprovisioning users can be a major pain if not automated. That’s why most enterprises use SCIM, a standard designed to simplify IT admins’ lives. Create, update, or delete user accounts, groups, and permissions in only one system and have these changes propagated in real-time to all the other apps the company is using.

In this article, we will see how SCIM deprovisioning works and how you can integrate it into your app using WorkOS.

What is user deprovisioning?

Deprovisioning is when a user’s access rights are removed, revoked, or even deleted when they are no longer needed. This includes:

• When an employee leaves the company.
• When a project is completed.
• When employees change roles, they must be deprovisioned from their current access and permissions and provided with new access.

Organizations tend to focus more on provisioning rather than deprovisioning. Still, the process of removing accounts or privileges in a timely manner is just as important (or even more so) as the account creation process.

Neglecting deprovisioning can leave organizations vulnerable to security breaches, unauthorized access, and potential compliance violations. For example, although SOC2 does not require SCIM, it does require a process for off-boarding users and documentation (logs) that show you have done it and they don’t have access anymore.

Deprovision flow overview

SCIM deprovisioning syncs disabled user accounts between your customer’s identity provider (IdP) and your app automatically in real time. When an IT admin removes a user from their IdP, SCIM propagates these changes to your app.

Here’s how the flow looks:

1. When an employee leaves the company, the IdP disables the account and sends a notification to each service provider in a standardized format.
2. Each service provider processes the received data and disables or deletes the corresponding user account. The user will also be removed from any groups to ensure they no longer have access or permissions associated with those groups.

With SCIM, users immediately lose access to the application when they are deprovisioned or unassigned in their IdP.

Without SCIM, users would only lose access once any current sessions expire. This means that users will have access to the system even though they shouldn’t. This is a security risk and a problem from a compliance perspective.

Disabling vs deleting users

While SCIM is standardized, it still leaves room for interpretation, meaning different IdPs may approach user deprovisioning differently.

• Some IdPs, like Okta, deprovision users by setting their active attribute from true to false. In this case, the user account is disabled, effectively preventing the user from logging in while retaining the account data for audit or reactivation purposes.
• Other IdPs allow permanent deletion of user accounts during deprovision. This process removes all traces of the user's account and data.

The deprovisioning behavior also varies among service providers. Some providers deactivate accounts, while others support permanent deletion.

‍WorkOS supports both models so you can implement the one that matches your use case: soft-delete (user deactivation) or hard-delete (user deletion).

Example: deprovision users from GitHub

Let’s see a simple user deprovisioning example using the GitHub API.

We will assume that your company uses GitHub and every time a new engineer is hired, and they are added in the company’s user directory, they should also get a fresh GitHub account. That means, that if any of these employees leave the company, their GitHub account should be disabled.

Here’s how you would deactivate a user from GitHub if you used a soft-delete model. After this, the user will continue to exist but in a deactivated state.

	
PATCH https://api.service-provider.com/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
Authorization: Bearer {token}
Content-Type: application/scim+json

{
   "schemas": ["urn:ietf:params:scim:schemas:api:messages:2.0:PatchOp"],
   "Operations": [
       {
           "op": "replace",
           "path": "active",
           "value": false
       }
   ]
}
	

If you use a hard-delete model, the call to completely delete a user looks like this:

	
DELETE https://api.service-provider.com/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
Authorization: Bearer {token}
	

For a complete set of user provisioning examples, check out How SCIM provisioning works - tutorial with API calls.

How to deprovision users with WorkOS

With WorkOS and Directory Sync, you can automate user provisioning and deprovisioning, and respond to changes as soon as they are sent from your IdP.

With Directory Sync you get:

• Automatic retry handling.
• Support for all major SCIM versions (1.1, 2.0).
• Built-in compatibility with all major identity providers.
• Provider-specific mappings and transformations.
• Comprehensive audit logging.
• Enterprise-grade security and compliance.

Directory updates can be delivered to you via webhooks or retrieved by your app using the events API:

• With the events API, your application is the one retrieving events from WorkOS. The events API offers a more robust data synchronization by returning a strictly ordered list of immutable events and offering controlled throughput through pagination. This solves some of the problems that webhooks have, like out-of-order updates and spiky throughputs. For more on this, see Why you should rethink your webhook strategy.
• With webhooks, WorkOS automatically notifies your app when an event occurs by invoking an endpoint hosted within your application.

You can set up Directory Sync in 3 steps:

1. Create a new directory connection in the WorkOS dashboard. You can configure the directory connection yourself or invite an admin to do it using the Admin Portal.
2. Use the WorkOS SDKs to integrate the Directory Sync API into your app and enable fetching directory resources programmatically.
3. Handle directory events to keep your app in sync using the events API or webhooks.

For more details, see the Directory Sync Quickstart.

Next steps

Implementing SCIM in your application requires building and maintaining complex provisioning logic, user synchronization, and enterprise-grade security features. ‍WorkOS already built these components so that you can make your app Enterprise Ready in minutes, not months.

When enterprises ask if your app supports automated user provisioning and deprovisioning, you can say yes — without spending months building SCIM yourself. Try WorkOS today, and start selling to enterprise customers tomorrow.