SCIM protocol explained

With enterprise companies using over 300 SaaS apps on average, managing access gets more complex as more employees join the company. Each new employee might need access to a specific set of these 300+ apps, requiring individual account setups and permissions. This process is not only more time-consuming but also raises the risk of errors like granting incorrect access which can be disastrous for security.

Enter SCIM: A protocol that eliminates most of these errors and speeds up access management by allowing companies to automatically provision (grant access) and deprovision users (revoke access). IT admins no longer have to do this manually.

Because of these benefits, most of your enterprise customers will ask you for a SCIM integration that they can hook up to their identity provider.

This SCIM integration must follow the SCIM protocol — the standard that defines how to connect to and exchange identity data with identity providers — to be compatible with your customers’ IdPs.

In this article, you’ll learn more about the SCIM protocol, including its key components, exactly how it works, and how you can implement it.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an open and standardized protocol for exchanging and managing user identities across various systems and applications. It defines a RESTful API with a JSON schema for communicating and representing data.

By implementing SCIM, you allow your customers to provision or de-provision users from their identity providers (like Okta, Microsoft Enta, OneLogin, or any other SCIM-compliant directory) to your app automatically without having to manually manage access.

How does the SCIM protocol work?

At its core, SCIM’s architecture leverages RESTful APIs and JSON for communication — RESTful APIs for the endpoints and JSON to structure resources (i.e. user and group data).

The key components of the SCIM protocol are as follows.

Resource types

SCIM has two primary resource types:

• User resource: Represents individual user accounts. It defines the attributes of a user, such as id, name, username, email, and group memberships. SCIM defines core attributes for a user resource but, you can define custom attributes too.
• Group resource: Represents a collection of users who have something in common, for example managers, interns, or product engineers within a company. A group in SCIM is defined by its members (users), and like user resources, group definitions are flexible and can support custom attributes.

SCIM attributes

Think of an attribute as the pieces of information that describe a resource, such as a name, email address, or phone number for a User resource. Or a group name or member list for Group resources.

There are two types of attributes:

• Standard attributes are predefined in the SCIM core schema for User and Group resources.
• Custom attributes are defined by you. They extend the SCIM schema and allow customers to store additional data. For example, you could define a “minimumIAL” attribute to indicate assurance levels, or an “isArchived” attribute to indicate a group’s status.

Both user and group resources must contain the following attributes:

• id: Unique identifier for the resource issued by you (the service provider). It must be unique within your system. This should be whatever identifier that you use for your users.
• externalId: Unique identifier provided by your customer. Used to identify resources within their own system. This identifier is chosen by your customer.
• meta: Used to describe the resource e.g. when it was created or last modified. Defined by you (the service provider).

SCIM schema

A SCIM schema is a JSON data model that specifies attributes necessary to represent a resource. Each resource has a matching schema:

• The User resource schema with standard attributes like userName, and emails for individual user profiles.
• The Group resource schema with standard attributes like display names and members to represent groups and their memberships.

The SCIM schema is extensible. You can add custom attributes to it, to represent additional information beyond what is defined in the core schema. The enterprise user schema, for example, is an extension schema derived from the User schema that is specifically designed to accommodate user attributes like costCenter, employeeNumber, and department which are commonly found in enterprise environments.

SCIM endpoints

SCIM specifies several endpoints through which resources (such as Users and Groups) can be accessed and managed. The two main endpoints are:

• /Users - For managing individual user entries.
• /Groups - For handling collections of users.

SCIM operations

SCIM defines a set of operations based on the CRUD (Create, Read, Update, Delete) model to manage identity information. These operations are fundamental to the protocol and enable the automated provisioning and management of user identities.

Create

The Create operation adds a user or group to your app via a HTTP POST request. This request includes all the necessary information about the new user or group in the body of the request. Your app then processes this request and creates a new user account or group.

Example: When a new employee joins the company, an IdP makes a POST request to the /Users endpoint to all the connected apps.

Read

The Read operation is used to fetch an existing group or user details from your app via a HTTP GET request. It supports retrieving either a single resource by a unique identifier (the id) or a list of resources using a filter:

• By ID: An IdP can directly request a resource’s details by appending the id to the endpoint URL (e.g. /Users/{id} for a user or /Groups/{id} for a group).
• By search filter: SCIM allows for sophisticated filtering with options like eq (equals), which lets your customers specify the exact value they’re looking for in an attribute. For example, to find users with a specific email, the endpoint might look like, /Users?filter=email eq "user@example.com".

Example: An IdP can request identity information to make sure your app’s data is sync with the data in its system.

Update

The Update operation is designed to modify the attributes of existing resources, such as user or group details, within your apps.

SCIM defines two REST methods for update operations:

• PUT: Used to overwrite an entire resource with a new version. This means all the current attributes of the resource are replaced with what's provided in the request.
• PATCH: Used for partial updates to a resource, meaning you can modify specific attributes without touching the rest.

Example: If an employee's job title changes, the IdP makes a PATCH request to /Users/{id} endpoint in your app with their new title in the payload.

Delete

The Delete operation is used to remove a user or group from your app.

To delete a resource, an IdP sends a HTTP DELETE request to the specific endpoint of the resource, typically by appending the resource's unique ID to the endpoint URL. It’s typically used for user offboarding, or to remove groups that are no longer needed.

Example: When an employee leaves the company, an IdP will send a HTTP DELETE request to the /Users/{id} endpoint and your app will respond by deleting or suspending their account.

Some common use cases of the SCIM protocol are:

• Automated user provisioning and provisioning: Perhaps, the most common use case of the SCIM protocol is automating the creation or removal of user accounts in SaaS apps.
• Unified identity management: SCIM is typically implemented through a central user directory which makes it easier to manage user profiles and permissions in multiple apps.
• Access control: SCIM groups help manage access groups automatically – your customers can create groups, add or remove members, and assign permissions based on group memberships.

SCIM vs REST

REST is a set of guidelines for how any app should communicate over the internet.

Here are the main principles of REST:

• Everything is a resource — a piece of information such as a document, an image, or a service endpoint.
• Resources are manipulated (created, read, updated, or deleted) via standard HTTP methods such as GET, POST, PUT, DELETE.
• It mainly uses JSON or XML to structure this data.

SCIM uses these same REST principles, but in a more specific way:

• SCIM is specialized for identity management: SCIM is used for creating, managing, and exchanging user identity information exclusively. REST can be used by any type of web service with any type of data, not just identity data.
• SCIM uses JSON: SCIM 2.0 specifically requires you to use JSON to format data. With any other REST API, you’re free to use other formats like XML.
• It has a fixed schema: With SCIM, you can't just invent new types of information to manage; you work within a set schema designed for User and Group data with the option to extend the schemas with custom attributes. With REST, you can create and manage any kind of resource you can think of, from blog posts to order entries.
• It pre-defines endpoints and methods: SCIM defines a specific set of HTTP methods and matching endpoints for managing data (eg. POST /Users to create users or PATCH /Groups to update group data). REST doesn’t define any particular methods (other than those available in the HTTP protocol) - you’re free to use any endpoints as you see fit.

Implementing the SCIM protocol

Implementing the SCIM protocol means enabling your customers to manage access to your SaaS from their user directories.

Here’s a brief how-to on how to connect your app to your customer's IdP:

1. Choose your SCIM version: Generally, you’ll want to support SCIM 2.0 — it’s the current version and most IdPs support it. If you have the time and resources, you may also want to support SCIM 1.1 for the few IdPs that still use it.
2. Develop your API endpoints: Create API endpoints for SCIM requests, typically /Users and /Groups endpoints for handling user and group resources, respectively. Then determine how you will map the  SCIM schemas to your internal data model, ensuring you can handle standard attributes and any custom attributes you plan to support.
3. Secure your endpoints: Choose a method for securing your SCIM endpoints. The most common authorization scheme for APIs is OAuth 2.0. Make sure you have logic to properly validate tokens — only authorized IdPs should access your SCIM endpoints.
4. Handle advanced SCIM features: Optionally, add support for bulk operations to handle multiple SCIM requests simultaneously. This is an important feature, particularly for large companies that might need to provision or de-provision entire departments of users at once, or manage bulk access during significant organizational changes, like mergers and acquisitions. You will also likely need to implement advanced filtering to allow IdPs to precisely query user and group data.

Test your API

Rigorously test your SCIM implementation with common IdPs to confirm everything is working as it should. Test all the CRUD operations, errors, and edge cases.

When building your SCIM integration, here are some best practices to keep in mind:

• Build it to scale from the start. As you onboard more customers, the number of requests you need to process will increase. Design your system in a scalable manner. Make sure it can go from handling one request to hundreds of requests without slowing down or worse, crashing.
• Have strategies in place to handle out-of-sync events. Regular sync checks can help maintain consistency between your app and the data in your customers' directories.
• Get security right — use TLS 1.2 for all your requests as per SCIM’s spec, and make sure whatever authorization protocol you’re using works properly.
• Return detailed error messages. This will help your customers understand what went wrong during their request processing and simplify debugging.
• Test your implementation both for interoperability and performance. Test it with various identity providers to make sure it works across different providers and also assess how it handles load spikes.

Next steps

Building a SCIM integration from scratch is no small feat. You've got to set up endpoints, secure them, ensure they’re compatible with a multitude of directory providers, and keep everything running smoothly as your system grows. Then there's the testing for errors and performance issues, and the headache of managing the slight differences in SCIM implementations across providers.

Fortunately, you don’t have to do all that. Use a ready-made SCIM connector like Directory Sync by WorkOS and increase the number of customers you convert by supporting SCIM for the dozens of providers they use via a single API-based integration.

• Get started fast: With SDKs for every popular platform, and Slack-based support, you can implement Directory Sync in minutes rather than weeks.
• Events-based processing: While webhooks are also supported, WorkOS’ Events API means every SCIM request is processed in order, and in real-time. You’ll never miss a provisioning request again.
• 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.