What is SCIM Provisioning? Everything You Need to Know in 5 Minutes
We’ll explain what SCIM provisioning is, how it works and why you should implement SCIM support into your SaaS app.
If you’ve spent any length of time looking into enabling Single Sign-On (SSO) for your app, you’ll likely have come across the lesser-known concept of SCIM.
SCIM provisioning is a concept used by IT teams across the world to manage the access their employees have to the apps and services which make up their IT estate. For startups, supporting SCIM is a gateway to closing more enterprise deals, and driving much better adoption within those enterprise customers’ workforces.
In this article, we’ll explain what SCIM provisioning is, how it works and why you should implement SCIM support into your SaaS app. We’ll also give you some practical steps to implement it in the fastest and easiest way possible.
What is SCIM provisioning?
SCIM stands for System for Cross-Domain Identity Management. It’s a RESTful API which allows a Service Provider (that’s your app) and an Identity Provider (IdP, your enterprise customer’s SSO platform) to exchange provisioning and identity information about users.
In layman’s terms, SCIM provisioning is like having an automatic guest list for your app.
Imagine your app as a party venue and your customer’s system (like their company's employee directory) as the guest list manager. Whenever the guest list changes - like when new employees join or leave the company - SCIM automatically updates your app’s list, so it always knows who’s allowed at the party and who’s not."
In other words, your customer is saying “I have this end-user and I want you to add them to your database and allow them to use your app, so here are the user’s personal details”.
Those personal details are arguably the most important part of SCIM - they let your app know:
- Who the user is - e.g. their name and email address.
- What the user is entitled to do - e.g. their level of access/the access group they belong to.
- Information your app might need to display about that user or use under the hood - e.g. their profile picture, their timezone, their job type.
Like any REST API’s payload, these details are encoded as a JSON object. In SCIM terms, each of these pieces of data is called an attribute, which is defined in a standardized schema.
Those attributes sit underneath pre-defined resources - primarily users as explained above, and groups which control levels of access (for example, you might add a user to an admin group or a privileged-user group).
Read more about SCIM attributes by clicking here.
The rigidity of the SCIM specification is what makes it so useful to IT teams - they can standardize and normalize how their employee data is stored and used across the entire organization.
When they buy your software, IT teams can seamlessly integrate your app into the rest of their estate. They don’t need to define bespoke processes for working with your software, they don’t need to create new, automated workflows for provisioning users and they can sleep easy knowing that their existing access and authorization controls on their workforce extend to your app and the data it holds.
Why should you use SCIM?
While the overall benefits of SCIM to enterprise IT teams are obvious, that doesn’t necessarily explain why it makes your life as a developer any easier, nor why you should bother taking the time to implement it in your app.
But in reality, SCIM is a huge timesaver for the developers who make use of it and can make a meaningful impact on your ability to close sales and more importantly, increase your generated revenue from those sales.
Let’s look at each of the key benefits to you.
SCIM will help you win sales
For almost all software-buying decisions, an enterprise’s procurement team will put out an RFP - In other words, they’ll compare your software to your competitors and pick the one that best suits them. More often than not, this is less about your app’s core functionality and more about how nicely your app plays with its estate and existing systems.
See: Why so many Fortune 500 IT teams picked Microsoft Teams over Slack.
When you have SCIM available, you’re making it easy for your customer’s IT department to onboard and integrate your app. Removing that headache means they’re much more likely to choose you from their list of options. Most startups will launch SSO without SCIM support, so you can easily edge them out of the running with this feature.
SCIM will help you increase adoption from your customers
One of the biggest hidden benefits of SCIM is that it makes it trivial for your customer’s IT team to provision new users on your app at scale, which can rapidly increase the revenue you derive from that customer.
For example, with SCIM implemented on your app and linked to your customer’s IdP, the IT team can now:
- Add entire departments to your app with one click.
- Add automated provisioning to their internal service desk tool (like ServiceNow) so that any employee across the entire company can have themselves provisioned onto your app, often without any difficult approval needed.
- Set your app to be automatically provisioned on Day 1 of new employee onboarding by their HRIS system.
Just like improving your public onboarding experience can have a dramatic impact on your product-led growth, making it smooth and easy for your customer to onboard more of its employees, makes it much more likely that they will onboard more of them.
SCIM is standardized
The SCIM protocol is (mostly) standardized in how it's used across different platforms. While some attribute naming conventions may differ slightly, you can broadly expect the user and group resources and the Core Schema to be in use by any provider. Many providers will have their own custom attributes, but the standardization of SCIM solves 80% of the headaches.
The problem you have as a developer is that every new enterprise customer you onboard might be using a different IdP or directory provider, and they might have a Human Resources Information System (HRIS) like Workday or Rippling that they need your app to interface with too.
If you’re using SCIM, you can support these new systems and onboard a new customer with ease. If not, you’ll spend a lot of engineering cycles on creating and supporting an ever-growing list of custom integrations.
SCIM is more secure than the alternatives
One of the most important differentiators of SCIM is that it works in real time. This means that a user can be logged into your app, and have their privileges or data changed while they’re using it.
This is different from other methods used to exchange identity data, such as SAML which can only make changes to the user on login.
For security-conscious enterprises (which is all of them), especially those in a regulated industry like finance and banking, the ability to modify what data a user has access to in real time is a serious, and often mandatory, asset.
How do you implement SCIM provisioning?
The hard way
As an open standard, you can implement SCIM manually just like you would like any other REST API. But despite the simplicity of the protocol, a practical implementation comes with some challenges:
- Data Normalization: While SCIM is a standard, every IdP has their own quirks on how exactly they implement it.
As you onboard multiple customers with multiple providers, you’ll need to normalize the attributes between them all to avoid maintaining multiple, essentially custom integrations. - Attribute Mapping: You’ll need to work with your customer’s IT team to understand which attributes they’re using, how they’re using them and how you should process them on your end.
This isn’t the most difficult task in the world, but it does create a lot of back-and-forth communication during the critical onboarding phase with a new customer.
- Group Fragmentation: Each major IdP has a different approach to how they handle the suspension/deletion of a user using the SCIM protocol. Depending on which access groups the user has access to, this can lead to different scenarios - including, but not limited to, a “suspended” user remaining active on your app when it shouldn’t be.
Of course, this can have huge implications for security, and also runs the risk of you erroneously billing your enterprise customer for user accounts they no longer intend to be active. You’ll need to figure out how IdPs like Okta, JumpCloud, Microsoft Entra and Google Workspace process user suspensions, and make sure your app is prepared to handle each scenario safely. - Event Processing: SCIM works primarily by allowing IdPs to send provisioning instructions directly to your app. You'll need to not only build an endpoint to handle this reliably, but also make sure it can gracefully handle bursty spikes in traffic
For example, if an IT team provisions an entire department onto your app at once, then you can go from processing zero events to processing hundreds or thousands in the space of a few seconds. - Out-of-Sequence Events: As with any high-volume endpoint implementation, it’s not unusual for updates to arrive late or out of sequence. While this is a problem for any kind of code, it can introduce particularly dangerous issues in SCIM.
For example, provisioning and deprovisioning events for the same user may arrive out of sequence, resulting in a user who has access to a resource they shouldn’t have - and worse yet, your customer’s system will believe that the access has been revoked.
This can have serious contractual consequences with your customer.
The easy way
If that all sounds daunting, you’ll be glad to know that most developers prefer to use a dedicated SCIM provider like WorkOS to simplify their implementation. Here’s how WorkOS’ Directory Sync product addresses the issues above:
- Attribute Mapping: WorkOS comes with a beautifully designed Admin Portal, which you can (manually or programmatically) send to your customer’s IT team. This guides them through the full setup process, allowing them to configure connection details and more importantly, map out each of their attributes. No back-and-forth is required.
- Data Normalization: WorkOS is already built to support dozens of HRIS and IdP systems, like Microsoft AD, Okta, Google Workspace and more. The attributes are normalized behind the scenes, so you never need to worry about it.
- Event Processing: Directory Sync comes with an Events API, which streams in real time and maintains perfect synchronicity between your app and your customer’s directory. You won’t miss events, and those events will always be delivered in order - meaning you don’t have to worry about out-of-sequence security risks with SCIM.
Bringing these advantages to your product is straightforward. WorkOS provides SDKs for every major platform, provides a production-mirror sandbox environment to test your implementation and provides support directly on Slack if you run into any problems.
Ready to get started with Directory Sync by WorkOS?