What is a SCIM integration and should you build or buy it?

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 about:

• What a SCIM integration is
• Why you should support SCIM
• What to consider before deciding to build your integration
• Why you might prefer outsourcing your integration.

Let’s get started.

What is a SCIM integration?

A SCIM integration is the implementation of the System for Cross-domain Identity Management protocol to standardize and automate the management of user identities across different systems.

It allows your customer's identity provider, like Okta, Google Workspace, or Microsoft Entra ID, to exchange user identity data with your SaaS. For example, when a new user is provisioned or deprovisioned, or their role within the organization changes, these updates are automatically communicated to your system via the SCIM integration. 

Why build a SCIM integration?

Building a SCIM integration has the following benefits:

• Increased market competitiveness: By offering SCIM integration, your SaaS product becomes more attractive to large enterprises prioritizing efficient, automated identity management systems. 
• Revenue growth: Enterprises willing to adopt SCIM are often larger organizations with the budget to afford premium services. Integrating SCIM can therefore lead to higher revenue per customer through upsells and expanded seat counts, as enterprises feel more confident in deploying your solution across their user base.
• Faster onboarding: With SCIM, the onboarding process for new customers is quicker and smoother. Automated provisioning means new users can start using your application almost immediately after being added to the enterprise's identity provider. This rapid deployment capability can be a strong selling point.
• Operational efficiency: SCIM reduces the need for manual intervention in managing user accounts, which can decrease the workload on your customer support and IT teams.

What does every SCIM integration need?

Endpoints compatible with multiple identity providers

The SCIM protocol specifies a RESTful API standard and a structured schema, which, in theory, should allow you to create a universal endpoint capable of supporting all your SCIM integrations.

In practice, it's not so straightforward. Each Identity Provider (IdP) might interpret the SCIM standards differently, so you're not off the hook for customization.

You’ll need: 

• Flexible response to varied IdP requests: One IdP might send a DELETE request to remove a user completely, while another might prefer a PATCH to flip a user’s ‘active’ status to false. You'll need to customize your integration to accommodate these variations.
• Accurate data model mapping: Your SCIM integration must reconcile differences between your app’s user data model and the diverse SCIM schemas used by IdPs. This includes managing standard and custom attributes without data loss or corruption.
• Robust tests and error handling: Each tweak or custom fix adds another layer of complexity to your system. More moving parts mean more things that can go wrong, so brace yourself for some serious testing and troubleshooting.

It needs to scale

As your SaaS takes off and racks up users, the traffic on your SCIM endpoints is going to climb — fast. We're talking about scaling from handling a few requests for new hires to hundreds of requests for an entire department. Your integration must keep up without slowing down or dropping a request.

When building your endpoints, design for scalability right from the start. Consider hosting your endpoint on platforms that offer auto-scaling or implementing message queues to absorb load spikes.

It should handle out-of-sync requests

Like with any system that processes a massive 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.

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 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 isn't just a plug-and-play affair. You’ll need to get on calls with your customers' admins to map the attributes their IdPs use to your internal data model and securely exchange all the authentication details, like API keys. You may also have to have customer support on standby to help answer any questions your customers may have.

For an even smoother process, you’ll need how-tos and in-depth documents that cover setup procedures, common issues, and troubleshooting tips.

Tests

Finally, your SCIM integration needs tests. Check that SCIM calls are received and processed accurately. Test edge and error cases and the entire user lifecycle to confirm that user creation, updates, and deactivation are functioning correctly.

Should you build or buy a SCIM integration?

At the heart of every growing SaaS company is a critical decision: Should you develop your own SCIM integration or outsource it? Here are some questions to help you think it through:

Do you or your engineering team have the skills to build it?

Your team needs to thoroughly understand SCIM's specifications, including how to structure user data, handle requests, manage responses, and make sure your SCIM integration is secure and can scale gracefully.

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.

Do you have the capacity to integrate new identity providers?

Every new customer or change from an IdP can mean a new round of custom coding and testing. Can your team manage that without sidelining other critical projects?

Do you have the capacity to provide long-term integration support?

SCIM isn't set-it-and-forget-it. It demands ongoing adjustments and maintenance. You’ll also need to conduct routine security checks and monitor the integration’s performance closely to ensure it’s working as expected.

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 SCIM connector you can trust, like WorkOS, and outsource it.

Use WorkOS to build your SCIM integration

Directory Sync by WorkOS abstracts the complexities of building your own SCIM integration. It brings together most of the IdPs your customers are already using into one unified integration.

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: The WorkOS Events API ensures you receive updates in the order they’re sent, eliminating concerns about out-of-sync data. Plus, you can process these events on your own terms, without overloading your system.

Getting started with Directory Sync

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.

Bottom line

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.

If you’re serious about expanding your total addressable market, you won't want to overlook supporting SCIM.

Sign up for WorkOS today, and start selling to enterprise customers tomorrow.