SCIM Integrations For Your SaaS

Picture the scene: You’re about to close a big enterprise deal for your SaaS, and the prospect’s decision-maker is itching to sign on the dotted line. You’ve already discussed SSO, but just at the last moment… their IT team asks you to create a SCIM integration to their Identity Provider (IdP).

If you don’t know what a SCIM integration is, it’s a connection between your app and your customer's IdP specifically to enable user provisioning. Enterprises frequently ask for one because it allows them to provision user accounts and manage access to your app automatically — and at scale.

In this article, we’ll learn more about SCIM integrations, their importance when selling to enterprise clients, and why, for most SaaS companies, outsourcing the integration to a provider rather than building it in-house is often the wisest choice.

What is a SCIM integration?

A SCIM (System for Cross-domain Identity Management) integration allows your customer's identity provider, like Okta, Google Workspace or Microsoft Entra ID to exchange user identity data with your SaaS.

It helps manage who gets access to what in your SaaS. When a new user is added (or removed), or their role within the organization changes, these updates are automatically communicated to your system via the SCIM integration. Your app then adjusts the user's permissions in your own database to mirror those changes.  

Simply put, it helps keep a user’s information within your SaaS in sync with their data in the IdP.

Why build a SCIM integration?

Enterprises love to buy SaaS with SCIM integration, and for good reason:

• It significantly reduces their admin overhead by automating user provisioning and de-provisioning. Their service desk or HR software can create, delete, or update user accounts in the IdP and have the user’s data updated in all the SaaS used within the company without requiring manual intervention.
• It’s more secure than manually managing access since permissions are automatically managed through SCIM groups. Security risks associated with errors, such as admins forgetting to revoke access when employees leave the company or change roles, can be completely avoided.
• Some enterprises operate under strict regulatory requirements that mandate precise control over access to information and data. SCIM integration helps maintain compliance with such regulations by ensuring accurate and timely management of user access rights, as well as near-instant revocation of permissions when necessary.

Because of these benefits, enterprises are more eager to sign up for SaaS apps that support SCIM. On top of that, they’re more likely to provision more seats on your app or allow their employees to self-serve access — all of which translates to more MRR for you.

What does every SCIM integration need?

Every SCIM integration needs:

Endpoints compatible with multiple Identity Providers

The SCIM protocol specifies a RESTful API standard and a schema, which theoretically should allow you to create a universal endpoint that works for all your SCIM integrations.

However, in practice, this is often not the case.

Integrating multiple Identity Providers (IdPs) complicates the process, as each IdP may have its unique implementation of the SCIM standard.

When you’re building a SCIM endpoint, you’ll have the challenge of designing it to process and respond to requests from these diverse IdPs uniformly

For instance, take the inconsistencies with de-provisioning requests. You’ll have some IdPs that will send you a DELETE request when a user is de-provisioned to remove that user entirely and those who’ll send you a PATCH request to set the user’s active status to false. To process these requests, you often end up having to build a custom integration for each IdP for the same admin action.

And unfortunately, the differences don’t stop there.

Your app's user data model likely differs slightly from these IdPs’ SCIM schemas. Some may even have custom attributes. You'll need to map each of the IdPs’ schemas to your internal user data model before using or even storing the data.

As you design your system for broad compatibility, you inevitably increase its complexity and naturally introduce more potential points of failure.

It needs to scale

As your SaaS grows and you onboard more customers, the number of SCIM requests your system receives will increase. Whether it's one request for a single employee or hundreds of requests for an entire department, your endpoint needs to process these requests without slowing down or worse - dropping a request.

Meaning, you should probably design for scalability right from the start. For example, host your endpoint with auto-scaling configured, or implement message queues to absorb load spikes by queuing requests and processing them at a manageable rate.

It should handle out-of-sync requests

Like with any system that processes a huge number of requests, your SCIM integration must be able to handle race conditions. Race conditions occur when two processes try to access or modify a single resource concurrently.

They’re disastrous for security because they cause inconsistent permission states. For example, if two requests from two admins attempt to update a user's attributes concurrently, one update could overwrite the other — meaning the data in your app can be out of sync with the data in your customer’s IdP. And to make matters worse, it might go unnoticed — a user might end up having unauthorized access to critical data far longer than they should!

Every SCIM integration needs to be able to implement proper synchronization checks and have recovery protocols for correcting out-of-sync data.

Error handling

Many different errors can occur with SCIM integrations like invalid payloads, schema violations, unauthorized requests, or issues connecting to endpoints. Your integration needs to handle errors gracefully and log them for debugging.

Documentation and support

Setting up SCIM for your customer is tricky enough that you’ll need to provide direct customer support for your SCIM integration, particularly during the initial setup process.

You’ll need to get on calls with your customer’s admins to map the attributes their IdPs use to your internal data model and to securely exchange all the authentication details like API keys necessary to connect to their IdP. You may also have to have customer support on standby to help answer any questions your customers may have.

And, for an even smoother process, you’ll need how-tos and in-depth docs on how your integration works.

Tests

Finally, test, test, test. Check that SCIM calls are received and processed accurately. Test edge and error cases. And test the full user lifecycle to confirm user creation, updates, and deactivation are functioning properly.

Build vs buy?

Whether you build or buy (outsource) your SCIM integration will depend on a couple of things:

• Do you or your engineering team have the skills?

Your team needs to thoroughly understand SCIM's specifications, including how to structure user data, handle requests, and manage responses. You should be able to adapt to the different implementations in various IdPs by mapping custom attributes, potentially handling different requests for the same admin action, and implementing strategies to handle concurrent requests and out-of-sync events.

Additionally, you must also design the underlying infrastructure in a scalable manner.

• Do you have the time and resources to build your own?

Building a SCIM integration takes time. If your SaaS is still in the early stages, you’ll realize it makes more sense to outsource the SCIM integration instead of building your own. The reason for this is not to divert the already limited engineering resources to non-core features.

• Can you keep up with integrating with new identity providers as you onboard more customers?

As mentioned before, IdPs typically implement SCIM in slightly different ways. It’s unlikely a single integration works with all your customers' IdPs without requiring customizations.

You'll often find yourself needing to develop integrations compatible with the majority of IdPs just to cover all the integrations your potential customers may need, a process that could span several months. That’s unless you're prepared to have your customers on standby while engineering builds their integration.

• Do you have the capacity to provide long-term integration support for your customers?

Maintaining a SCIM integration requires ongoing attention maintenance. Over time, IdPs may update their APIs or change their SCIM implementation. You must regularly update your integration to stay compatible. It's also important to conduct routine security checks to uncover and fix potential vulnerabilities before they become a problem.

Moreover, you’ll need to keep a close eye on the integration’s performance making sure it’s always available when customers need it.

If you can do all the above and get it right, then by all means, build your own SCIM integration. However, if you’d rather focus on adding more features to your core product, find a provider you can trust, like WorkOS, and outsource it.

Deep-dive: Using WorkOS to build your next SCIM integration

WorkOS Directory Sync abstracts the complexities that come with building your own SCIM integration. It unifies multiple integrations of most of the Identity Providers your customers use and gives you a single interface your SaaS can connect to.

Here are some of the features you’ll love:

• Pre-integrations with most major providers: Directory Sync integrates with providers like Okta, Azure AD, OneLogin, and HRIS systems like Rippling and Workday. It also supports custom SCIM 2.0 providers if you want to connect to an in-house directory.
• Attribute mapping: You don’t need to normalize attributes from multiple directories. WorkOS does that for you in the background.
• Admin portal: You can share the admin portal with your customer’s admin team and let them configure the integration themselves. It’s much faster and eliminates the need for the back and forth.
• Event-based processing: With the WorkOS Events API, you’ll always receive events in the order they came in — you don’t have to worry about out-of-sync events. Better still, you can process the events at your own pace, your system doesn’t have to process more requests than it can handle.

Getting started with Directory Sync is pretty straightforward:

• Sign up for a WorkOS account to get access to the WorkOS dashboard.
• From the dashboard, you can configure a connection to your customer’s IdP manually or invite an admin to configure it themselves.
• Once the connection is set up, WorkOS records updates from the connected directories (user or group deletions, updates, and creations).
• With the WorkOS SDKs (which come in a variety of programming languages including JavaScript and Python) and the WorkOS API, you can set up webhooks to be instantly notified of these changes or use the Events API to retrieve these events.
• Once your SaaS receives the events, process them accordingly. For example, create a new user account for user-created events.

Conclusion

A SCIM integration saves your customers tons of time and the hassle of manually managing users in your app. This convenience is a major selling point and often a deciding factor for businesses evaluating SaaS apps.

Therefore, if you’re serious about expanding your total addressable market, you may want to support SCIM.

As we explained above, for most SaaS apps, buying a done-for-you SCIM integration like Directory Sync instead of building your own is the better option since it's a fast and easy way for your app to get enterprise-ready and get ahead of the competition.

However, if you want to build your own, make sure it’s interoperable with the identity providers you’re planning to support, it scales, handles errors and out-of-sync events gracefully, and is easy to integrate with IdPs.