How to use SCIM with SSO: A Developer's Guide

Enterprises using Single Sign-On (SSO) will almost always use SCIM to handle aspects of the wider authentication system that SSO does not cover: User management, provisioning and access control post-login.

If you’re hoping to bring on enterprise customers, this means you’ll eventually need to add SCIM to support your app’s SSO solution.

Not sure what SCIM is or if implementing it is the right move for you? We’ll break down what SCIM is, why it’s so important in user identity management, and how it helps with SSO.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an industry standard commonly used to automate user provisioning and de-provisioning.

SCIM is not a direct part of the Single Sign-On process. Instead, it plays a complementary role.

At the enterprise level, it’s used by your customers to add, modify, or remove users from your app right from their Identity Provider (IdP). This makes it easier for their IT teams to manage their vast estate of apps, services and the employees who need access to them.

And for your app, this means frictionless user onboarding, no manual user provisioning for your support team, and ultimately - more paid seats for your product.

There are two primary features of SCIM:

• Standardized schema: SCIM defines a standard schema for representing users and groups. This schema includes attributes like a user's name, email address, and role, among others.
• HTTP requests with JSON payloads SCIM is a RESTful protocol and supports Create, Read, Update, and Delete (CRUD) operations for user identity data.

SCIM defines a format for user data and specifies how this data should be exchanged between systems, making it easier for Service Providers (SPs) and Identity Providers (IdPs) to sync profile data without a custom integration.

When a user’s data is updated in the IdP, SCIM ensures that this change is reflected in your app and every other app connected to that IdP via SCIM.

For example, when an IT admin adds a new employee to their organization, the IdP automatically sends a SCIM request containing the new user’s data (emails, roles, permissions etc.) to your app and all the other connected apps. You can then use this data to create a corresponding account in your database.

What makes SCIM invaluable for enterprises with lots of employees is that it enables support for bulk operations — admins can provision entire departments at one go.

How does SCIM help with SSO?

SCIM does not enable SSO.

Instead, it complements the SSO process by ensuring both parties (the service provider and the identity provider) have already “pre-agreed” — or synced —  a list of provisioned users and their identity-related details and permissions.

You can think of this as a real-time, always-in-sync guest list; your app always knows which users are allowed to log in to your app, and what they’re allowed to do when they get in - all before they attempt to initiate an SSO process.

Additionally, SCIM helps SSO by providing a more secure solution for user provisioning and access control.

One of the most popular SSO protocols among enterprises is SAML — it has solid security features, and it’s been around for longer than any other popular SSO protocol, so almost every IdP supports it.

Unfortunately, SAML is not a real-time protocol — it doesn’t have a built-in standard for continuously updating your app with changes in a user’s status after the initial login. This means any modifications to a user’s access rights or roles aren't immediately reflected in your app until their next login.

This means that if a user is still in an active session on your app when their permissions are changed or revoked, they will still have access to resources their IT team has removed authorization for. This is where SCIM saves the day.

With SCIM, your app gets real-time updates — whenever your customer provisions a user, changes their permissions, or even deactivates their account, their IdP sends an update to your SCIM endpoint.

For example, if a user’s status changes to ‘inactive’ in your customer’s IdP, SCIM uses this information to trigger a deprovisioning event in your app, which you may then respond to by ending the user’s session.

You’re probably thinking, doesn’t a SAML assertion have attributes too?

Well, it does (they’re passed in the attribution with the authorization decision assertion), and like SCIM attributes,  they can also store authorization data.

However, these attributes are not updated post-login (remember — SAML is not a real time protocol). So if a user's permissions change during an active session, their access rights within your application remain unchanged until they log out.

This lack of real time synchronization in SAML’s SSO profiles can be disastrous for security — an employee might retain access to your app long after they’ve left the company.

SCIM complements SSO by ensuring that your app always has the most current information for each user beyond what it gets with just an SSO login.

How do you implement SCIM with your existing SSO stack?

Integrating SCIM with your existing SSO stack can seem straightforward at first.

Generally, the process involves building a RESTful API endpoint that your customers’ IdPs can call to provision users on your app. This endpoint should be able to receive and process requests for creating, returning, updating, and deleting user accounts or groups from each and every IdP it integrates with.

This is where SCIM implementation gets complicated. As your client list grows, so does your implementations complexity – it has to be compatible with each of their IdPs.

So, before you start building your own SCIM API, keep the following in mind:

• SCIM implementations vary across Identity Providers. There are two major versions of SCIM — 1.1 and 2.0 — and not all IdPs use the latest one. Some even use custom attributes unique to their systems. Plus, they may handle operations such as user suspension and deletion differently. Meaning, you may find yourself having to write a custom integration for each customer you bring on.
• You have to listen to and process all the SCIM events from all of your customers’ IdPs —  without missing any. Missing an event could lead to discrepancies in authorization data between your customer’s IdP and your app. If your app misses a deprovisioning request, for instance, a user might continue having access to your app depending on how often they SSO in, how long their session is, etc.
• Your system needs to scale graciously. Performance shouldn’t take a hit if your app goes from processing one SCIM request to processing hundreds of requests if one of your customers tries to onboard entire departments at once.
• Onboarding new customers can be a long drawn-out process. You’ll need to map the attributes your customers are using in their own system to your own implementation, figure out how they provision and deprovision users, and thoroughly test everything to make sure it all works. This is often a slow process.

Adding SCIM to your existing SSO stack with WorkOS

If you’d rather not deal with all of those complexities, you can use WorkOS’ Directory Sync instead.

WorkOS simplifies SCIM provisioning for every major IdP used by your customers via a single, API-based integration, including Okta, Microsoft Entra (formerly Azure AD), JumpCloud, and PingIdentity via a single API-based integration.

And,  if your customer is using a home-grown SSO solution, WorkOS supports custom SCIM 2.0 connections.

Here’s why you’ll love Directory Sync by WorkOS:

• It’s fast to get started: With SDKs for every popular platform, and Slack-based support, you can implement SSO and Directory Sync in minutes rather than weeks.
• Events-based processing: While webhooks are also supported, WorkOS’ unique Events API means every SCIM request is processed in order, and in real-time. You’ll never miss a provisioning request again.
• Admin portal: A self-serve admin portal you can share with your customer’s IT admins to let them configure their identity provider and map their own custom attributes. No more back and forth.
• Pricing that makes sense: Unlike competitors who price by monthly active users, WorkOS charges a flat rate for each company you onboard - whether they’re syncing 10 or 10,000 users with your app.

Explore Directory Sync by WorkOS.