What is SCIM and how does it work?

Auth & identity
June 12, 2024
Author: Isaac Ejeh

SCIM (System for Cross-domain Identity Management) is an open HTTP–based protocol that specifies a standard schema and architecture for managing identity resources across multiple domains.

At its core, SCIM simplifies the bidirectional exchange of user and group resources between identity providers (IdPs) and cloud-based service providers (SaaS applications) by providing a RESTful SCIM API that can be used to perform CRUD operations on these resources.

In this article, you’ll learn about the SCIM protocol and how SCIM auto-provisioning works. We’ll explore some examples and use cases of the protocol, and discuss how you can implement SCIM as an enterprise SaaS provider without wasting valuable engineering time and resources.

What is SCIM provisioning?

In enterprise organizations that don’t use SCIM, managing user and employee access can be a very manual and herculean task. When a new employee joins the company, HR and IT administrators have to manually assign their roles and access permissions across a multitude of tools and platforms.

This process becomes increasingly complex as the number of internal and external systems grows, often reaching hundreds or even thousands in larger enterprises. To further complicate things, each employee typically needs to maintain separate login credentials for each tool they access.

This not only creates a poor and cumbersome onboarding experience for new joiners but also poses security risks when employees leave the organization. IT departments have to invest significant time and effort into revoking access rights and removing user data from every single platform to ensure the off-boarded employee can no longer gain entry.

SCIM addresses these challenges by enabling organizations to maintain a centralized repository or single source of truth for all identity resources. Using the SCIM protocol, IT administrators can automatically provision, update, and de-provision employee resources using JSON formatted payloads that are communicated between SCIM clients and service providers.

SCIM flow with Stytch

Whether it’s onboarding a new team member, updating an existing employee’s email address or role, or offboarding a departing employee, SCIM makes it possible to handle these tasks programmatically, saving valuable time and reducing the risk of errors.

The SCIM provisioning process is straightforward: when a user is provisioned onto an application, the identity provider (IdP) exchanges key attributes such as the user’s name, email and a unique identifier with the respective service provider(s) over the SCIM API. The same process applies when a user’s identity is updated or de-provisioned, ensuring that all connected systems remain in sync with the central identity repository.

How does the SCIM protocol work?

Diagram of SCIM API and providers

The SCIM protocol, as defined by the IETF RFC 7644 standard specification, revolves around two main resources — Users and Groups. The Users resource stores identity data for each user, while the Groups resource defines the access groups, departments, or tenants a user belongs to, along with their corresponding level of authorization access.

To ensure consistency and interoperability in the way identity resources are described and maintained across different systems within the protocol, the SCIM schema defines the standard structure and attributes for “Users” and “Groups” resources. Each resource must adhere to a set of three required attributes (id, externalId and meta attributes) typically stored as name/value pairs in a JSON object.

SCIM also provides URL endpoints that identity providers (IdPs) and service providers can use to perform CRUD API operations on these resources and other entities defined within the protocol. These endpoints serve as the communication channels through which identity data is exchanged, enabling seamless synchronization across multiple domains.

In a typical SCIM setup, an organization’s identity provider (SCIM IdP), such as Microsoft Entra ID, Google Workspace, or Okta, acts as the SCIM client. These IdPs are responsible for storing and managing user identities, access permissions, and other relevant information within their respective identity directories.

On the other hand, the SaaS applications or internal systems that employees use to perform their daily tasks, such as Notion or Linear, are known as SCIM service providers. These applications consume user identity data provided by the SCIM client to ensure employees have the appropriate access and privileges within their respective environments.

When CRUD updates are made to a user’s identity, such as updating their department or role, the SCIM client (IdP) automatically synchronizes these changes to the connected service providers according to the SCIM protocol. In the same way, IdPs can also read user identity information from service providers and incorporate updates into their identity directory, ensuring both systems remain in sync and up-to-date.

Is SCIM a SAML or SSO alternative?

SAML (Security Assertion Markup Language) and SCIM are both open standardized protocols, but they serve unique purposes and are used in different scenarios.

SAML is primarily used for implementing single sign-on (SSO), enabling users to access multiple applications with a single set of credentials and eliminating the need to re-enter login information for each application.

SAML achieves this by exchanging authentication assertions between the identity provider (IdP) used within the company and the various service providers (SPs) used for work. The thing is, SAML SSO focuses on user authentication and doesn’t inherently require SCIM to function, as long as user identities are provisioned manually.

SAML can also be used to pass authorization data within security assertions, however, identity lifecycles would still need to be managed manually, because SAML doesn’t offer the same level of real-time identity synchronization and consistency as the SCIM protocol.

SCIM, on the other hand, doesn’t directly support authentication or SSO. Instead, it complements SAML by ensuring that multiple applications always have the most up-to-date information for each user who needs to gain access. For example, when a new user is added to the identity provider, SCIM can automatically propagate this information to all service providers that support SAML SSO, ensuring the user has the necessary access and permission levels whenever they need to authenticate.

When SCIM is implemented in an environment where SAML SSO is used, it can automate user provisioning, de-provisioning, and synchronization of user attributes across all connected applications that users access via SAML SSO.

By using SCIM to programmatically manage identity resources, while leveraging SAML for user authentication, organizations can maintain a centralized identity management system that not only simplifies user logins via SSO but also ensures that user attributes are securely and consistently managed throughout their lifecycle.

Why and when should you implement SCIM?

As we have seen thus far, the most compelling reason to adopt SCIM as a large enterprise is that it enables your IT and security departments to maintain accurate and up-to-date identity resources across all connected systems. This reduces the risk of data inconsistencies and potential security breaches, without the need for unnecessary manual work.

As such, if you’re a SaaS provider catering to large enterprises, providing out-of-the-box support for the SCIM protocol is mostly non-negotiable. It eliminates stress for the IT administrators who would otherwise need to manually onboard hundreds or even thousands of users onto your application.

For newer B2B SaaS startups, supporting SCIM can significantly increase your chances of closing deals with large enterprise clients. This can also drive early adoption and product usage because these large companies can automatically onboard their employee base in one go, thereby encouraging widespread use very early on.

Building SCIM in-house vs using Stytch

When implementing the SCIM protocol, engineering teams can choose to build a custom SCIM connector in-house or leverage an out-of-the-box SCIM connector like Stytch.

The downside with building a custom SCIM implementation is that it’s never worth the resources and time your team will expend, especially if you don’t have the size or scale of a Google or Microsoft.

If you choose to implement SCIM in-house, you must be prepared to handle the complexities of integrating with all the identity providers that your current and potential customers may be using within their companies.

The reality is that every IdP has a different implementation approach to how they map attributes and integrate with the SCIM protocol. As such, you’ll need to figure out how IdPs like Okta, OneLogin, Entra ID, JumpCloud, and Google Workspace all map resource attributes and perform CRUD operations using the SCIM API, and also ensure your application can securely handle each provider.

By leveraging the SCIM base connector URL provided by Stytch, enterprise applications can effortlessly configure their IdP and connected service providers to send and receive SCIM updates without the need for an in-house SCIM implementation.

Diagram of Stytch API with SCIM

We can also receive SCIM requests from your IdP, and immediately effect the requested updates on our end, whether it’s to revoke an active session, assign a new RBAC role, or even update a Member object.

Another compelling reason to use a SCIM provider like Stytch is that we support other open industry protocols such as SAML, OIDC, and OAuth. With Stytch, these protocols can be implemented in a matter of days, as opposed to the months or even years it would take for an in-house implementation.

Want to learn more about Stytch’s APIs and SDKs? You can check our docs and sign up for a free developer account to start building today.

If you want to learn more about our Enterprise features and pricing, feel free to schedule a call with any of our Solutions Engineers.

cta image

Build auth with Stytch

cta image


LinkedIn share
Twitter share
Facebook share