SCIM 2.0 vs SCIM 1.0 - What’s The Difference Between The Two Versions?

SCIM is designed to simplify user provisioning and identity management across various systems, but knowing which version to support can be confusing.

There are two main versions of SCIM in use today: SCIM 1.1 (SCIM 1.0 was deprecated), and SCIM 2.0.

While there are some similarities between these two versions, there are some variations in how data is structured, formatted, and exchanged.

If you’re building a SCIM integration for your enterprise customers, you’ll need to be aware of these differences to build integrations compatible with the SCIM versions your customers use.

In this article, we’ll discuss SCIM 2.0 and SCIM 1.1 in more depth and then dive into the key differences between versions 1.1 and 2.0.

Quick overview: The key differences between SCIM 2.0 and SCIM 1.1

The differences between SCIM 2.0 and SCIM 1.1 are mainly in the schema and the endpoints.

Below are some notable differences:

• SCIM 1.1 represents data in both XML and JSON format while SCIM 2.0 only allows JSON.
• In SCIM 1.1 you can use TLS 1.0 while in SCIM 2.0 you must use TLS 1.2.
• SCIM 2.0 has more filtering options for queries including ne (not equal), ew (ends with), not, and [ ] (complex attribute grouping).
• The PATCH request syntax is different in SCIM 2.0 and uses explicit operations like add, remove, and replace.
• In SCIM 1.1, in addition to the /Users and /Groups endpoints, you only have the /ServiceProviderConfigs endpoint while SCIM 2.0 has two additional endpoints – /Schemas and /ResourceTypes.
• In SCIM 1.1 the endpoint is plural: /ServiceProviderConfigs, in SCIM 2.0 the endpoint is singular: /ServiceProviderConfig
• SCIM 2.0 has new attributes – immutability, returned, and uniqueness.

What is SCIM 2.0?

SCIM 2.0 was released in 2015 and, like SCIM 1.1, defines a core schema for structuring user identities and endpoints for exchanging this data between different systems — usually the Service Provider(SP) and an Identity Provider (IdP) — and therefore allowing users to be provisioned (or deprovisioned) within the SP’s database.

The main goals of SCIM 2.0 were to make the SCIM schema more flexible with more attributes and endpoints, and to increase interoperability between systems:

• It has additional filtering options such as ne(not equal), ew (ends with), not, and [ ] (complex attribute grouping), that allow for more complex queries. It’s easier to get the exact data you need.
• It has more attributes like mutability, uniqueness, and returned that allow for a more accurate representation of user data.
• It’s more opinionated, which reduces the areas open to interpretation between IdPs and improves interoperability. For instance, data must be in JSON not JSON or XML. It’s also more specific about which TLS version to use for security — TLS 1.2.
• It has better support for partial updates with PATCH operations. The syntax is more specific. For example, for adding values to a resource, you use the add attribute, for updating data, the replace attribute and the delete attribute for deleting requests.

What is SCIM 1.1?

SCIM 1.1 came after SCIM 1.0 (now deprecated). It clarified the initial version and laid much of the groundwork for a standardized method of managing user identity. SCIM 1.1 defines a RESTful API and a standardized schema for representing users and groups, which makes it easier for systems to communicate user identity information.

While it did simplify the implementation of identity management across various cloud applications, SCIM 1.1  was not considered to be flexible enough by the developer community. As devs used it, they started to see areas that could be improved like more attributes and endpoints and better specifications for some operations like PATCH.

This led to the introduction of SCIM 2.0.

SCIM 1.1 vs SCIM 2.0: Key differences between each version

Below are some of the key differences between SCIM 1.1 and SCIM 2.0:

More attributes in SCIM 2.0

These attributes were added in SCIM 2.0:

• Mutability: In SCIM 1.1, mutability is represented by the readOnly attribute:
  • readOnly: true: The attribute cannot be changed once set.
  • readOnly:false: The attribute can be updated after it's created.

For some attributes, readOnly is limiting — what if you want a password to be written only but never read? SCIM 2.0 introduced a new attribute, mutability, with four values, immutable, readOnly, readWrite and writeOnly, that provides a broader range of control:

• readOnly: The attribute cannot be modified e.g. a user's lastModified timestamp.
• immutable: The attribute cannot be changed once set e.g. a user's username or employeeNumber after they’re first created.
• readWrite: The attribute may be updated and read at any time e.g. a user’s email.
• writeOnly: The attribute may be updated at any time but you shouldn’t return it e.g. a user’s password.

• Returned: New in SCIM 2.0, this controls if and when attributes are returned in a response, improving control over data visibility:
  • always: Always returned e.g the ID.
  • never: Never returned.
  • default: The attribute is returned by default.  If the GET request "attributes" parameter is specified, attribute values are only returned if the attribute is named in the "attributes" parameter.
  • request: Only returned if explicitly requested.

• Uniqueness: Specifies whether an attribute must be unique, and the scope of that uniqueness:
  • none: The values are not intended to be unique in any way.
  • server: The value must be unique within a specific server or tenant e.g. a server-generated key.
  • global: The value SHOULD be globally unique e.g., an email address.

Filtering options

SCIM 2.0 significantly improves upon the filtering capabilities available in SCIM 1.1 allowing for more specific and complex queries:

• ne (not equal): Filters out resources that don't match the specified value.
• ew (ends with): Finds resources where the attribute value ends with a given substring.
• not: Excludes resources that meet the specified condition.
• [ ] (complex attribute grouping): Allows combining multiple filter conditions for detailed queries.

PATCH request operations

The syntax of the PATCH operation in SCIM 2.0 is different from the one in SCIM 1.0 — it’s more specific and introduces the PatchOp schema and an Operations attribute that describes the change (e.g., add, remove, or replace) using JSON Patch (RFC 6902).

Here's how it looks in practice:

Example 1: How to add a member to a group

SCIM 1.1

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce

Host: example.com

Accept: application/json

Content-Type: application/json

Authorization: Bearer h480djs93hd8

{ 
"schemas": ["urn:scim:schemas:core:1.0"],
"members": [
{      "display": "Dwight Schrute",
"value": "2819c223-7f76-453a-919d-413861904646"   
}
]
}

SCIM 2.0:

  PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce

  Host: example.com

  Accept: application/scim+json

  Content-Type: application/scim+json

  Authorization: Bearer h480djs93hd8

{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[
{
"op":"add",
"path":"members",
"value":[
{
"display": "Babs Jensen",
"$ref":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
}
]
}

‍Example 2: How to group operations in a single request using PatchOp

In SCIM 1.1:

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce

Host: example.com

Accept: application/json

Content-Type: application/json

Authorization: Bearer h480djs93hd8

{
"schemas": ["urn:scim:schemas:core:1.0"],
"members": [
{
"display": "Dwight Schrute",
"value": "2819c223-7f76-453a-919d-413861904646"
"operation": "delete"
},
{
"display": "James Smith",
"value": "08e1d05d-121c-4561-8b96-473d93df9210"
}
]

In SCIM 2.0:

  PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce

  Host: example.com

  Accept: application/scim+json

  Content-Type: application/scim+json

  Authorization: Bearer h480djs93hd8

{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op":"remove",
"path":
"members[value eq \"2819c223-7f76-453a-919d-413861904646\"]"
},
{
"op":"add",
"path":"members",
"value": [
{
"display": "James Smith",
"$ref":
"https://example.com/v2/Users/08e1d05d-121c-4561-8b96-473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210"
}
]
}
]
}

When you look at the SCIM 1.1 code, it’s not immediately clear what’s happening but thanks to the operations attribute in SCIM 2.0, it’s easier to tell what a request is supposed to do.

Data format

SCIM 1.1 supports both JSON and XML.

So you’d have singular attributes encoded as string name-value-pairs in JSON; e.g.,

"attribute": "value"

and elements in XML; e.g.,

<attribute>value</attribute>

IdPs using SCIM 1.1  have to specify the data format they’re requesting when calling your SCIM server:

For JSON:

GET /Users/2819c223-7f76-453a-919d-413861904646.json

For XML:

GET /Users/2819c223-7f76-453a-919d-413861904646.xml

This lack of a standardized data format can introduce a lot of complexity to your system, especially if you need to process both JSON and XML SCIM requests. Working with XML, specifically, can be quite challenging due to its verbosity compared to JSON.

Thankfully, SCIM 2.0 only supports JSON, the more lightweight and readable data format of the two  - It has no option for XML.

Security recommendations

Unlike SCIM 1.1, which recommended TLS 1.0, SCIM 2.0 requires you to use TLS 1.2 for all SCIM requests.

SCIM 2.0 also offers detailed guidance on handling security compared to SCIM 1.1 including recommending against Basic Authentication, and instead recommending Bearer Tokens with OAuth 2.0, HOBA Authentication or even POP tokens — among other authentication options. The specification also has an entire section on the best practices for handling anonymous requests, handling private data, and securing data in storage.

More service provider Configuration endpoints

In SCIM 1.1, you only have the /ServiceProviderConfigs endpoint for server configuration information. You use it to return a JSON structure that describes the SCIM specification features you support.

SCIM 2.0 has two more additional endpoints:

• /Schemas: An HTTP GET to this endpoint should return all the resource schemas you support. You can return individual schemas by appending the schema URI to the /Schemas endpoint. For example:
  
  /Schemas/urn:ietf:params:scim:schemas:core:2.0:User

• /ResourceTypes: An HTTP GET to this endpoint should return the types of resources available on your SCIM server (e.g., Users and Groups).
• /ServiceProviderConfig: Note that this is spelled differently.

FAQ

Is SCIM 1.1 still in use?

Yes, SCIM 1.1 is still in use in some organizations. SCIM 1.1 was first released in 2011 and it’s been around for nearly a decade. Many companies built their identity management systems based on this version. Some like Okta and PingIdentity support both versions.

Is there any benefit to sticking with SCIM 1.1?

No - SCIM 2.0 is the latest version and addresses many of the shortcomings of SCIM 1.1. That said, if you’re creating a SCIM integration for an identity provider that only supports SCIM 1.1, you won’t have a choice but to use it.

Is there a SCIM 3.0?

Currently, no. There has been no release of SCIM 3.0.

Next steps: Which one should you choose?

Your customers' Identity Providers (IdPs) likely use different versions of SCIM, and even among those using the same version, variations in implementation are extremely common.

This usually means you're stuck juggling multiple for both SCIM 1.1 and SCIM 2.0 along with the differences within each version — a real headache that eats up your engineering team's time. You could pick a side and support just one version, but then you risk not fully serving all your customers, potentially leading to lost revenue.

Here's the good news: You don’t have to choose.

With Directory Sync by WorkOS, you can quickly expand your total addressable market by integrating SCIM support for the numerous directory providers and HRIS platforms your potential clients use without having to build separate custom integrations for each.

• Get started fast: With SDKs for every popular platform, and Slack-based support, you can implement SCIM in minutes rather than weeks.
• Events-based processing: While webhooks are also supported, WorkOS’ unique 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 WorkOS Directory Sync.