A Beginner’s Guide to SCIM

With the advancement in technology, a significant amount of attention should be paid to ensure security and confidentiality of users when accessing applications. Therefore, there should be a proper way to manage digital identities across multiple applications. This concept is known as user provisioning.

User provisioning is the process of creating and maintaining digital identities (user accounts) in one or more systems and assigning appropriate privileges to them.

In traditional applications, in order to support user provisioning, it is needed to have multiple connectors for each service, thus resulting in a high cost and increased complexity. As a solution, SCIM protocol was designed which provides the ability to manage identities across various domains. RFC7642 defines SCIM as follows.

The System for Cross-domain Identity Management (SCIM) specification is designed to manage user identity in cloud-based applications and services in a standardized way to enable interoperability, security, and scalability.

In a simplified way, it supports performing a subset of HTTP methods (GET, POST, PUT, PATCH, DELETE) on identity resources such as Users and Groups, thus providing a standardized representation of those resources. Therefore, it makes it easy, fast and cheap to provide user identities into, out of and around the cloud.

Accordingly, SCIM Specification defines following two major components.

1. SCIM Core Schema (RFC7643)
2. SCIM Protocol (RFC7644)

Now let’s look at what these two are meant for and the major aspects of those.

SCIM Core Schema

The Core Schema provides a platform-neutral schema and an extension model for representing Users, Groups and other resource types. In SCIM, “Resource” is considered as the common denominator and all other objects are derived from that. The set of resources is defined using a set of schema URIs and a resource type. Each resource consists of three common attributes which are “id”, “externalId” and “meta”. Moreover, a resource is a collection of attributes where each attribute has an attribute name and an attribute value which can be either simple or complex. Each attribute has a set of characteristics as described below.

• name — unique name for the attribute
• type — data type of the attribute, can be either “String”, “Boolean”, “Decimal”, “Integer”, “DateTime”, “Binary”, “Reference”, “Complex”
• multiValued — Boolean value, defines whether attribute can have multiple values
• description — a human-readable description of the attribute
• required — Boolean value, defines whether attribute is mandatory or optional
• caseExact — Boolean value, defines whether attribute is case-sensitive or not
• mutability — defines the circumstances under which the attribute can be redefined, can be either “readOnly”, “readWrite”, “immutable”, “writeOnly”
• returned — defines when attribute is returned in response body, can be either “always”, “never”, “default”, “request”
• uniqueness — defines the uniqueness of attribute value, can be either “none”, “server”, “global”
• subAttributes — defines only when the attribute type is “complex”
• canonicalValues — a collection of suggested canonical values that may be used (eg: “work” and “home” for attribute “email”)
• referenceTypes — a multi-valued array of JSON strings that indicates the SCIM resource types that may be referenced, applicable only when attribute type is “reference”

Following is an example JSON resource structure for resourceType “User”.

{
  "schemas":
    ["urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
  "meta": {
    "resourceType": "User",
    "created": "2021-05-23T05:50:28Z",
    "lastModified": "2021-05-23T05:50:28Z",
    "location": "https://example.com/v2/Users/229d3f0d-a07b-4052-bf4d-3071ecafed0"
  },
  "id": "229d3f0d-a07b-4052-bf4d-3071ecafed0",
  "externalId": "736732",
  "userName": "rash",
  "emails": [
    {
      "type": "home",
      "value": "rash@gmail.com",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "123",
  }
}

SCIM Protocol

The SCIM Protocol is an application-level, REST protocol for creation, modification, retrieval, and discovery of core identity resources. SCIM provides a rich REST API with multiple operations as follows.

In addition to that, SCIM protocol defines a set of endpoints for managing resources. Those endpoints are defined corresponding to the resource type. For example, “User” and “Group” resources use “/Users” and “/Groups” endpoints respectively. Furthermore, SCIM provides three endpoints “/ServiceProviderConfig”, “/ResourceTypes” and “/Schemas” to discover supported features and specific attribute details.

Following is a sample request used to create a User.

POST Users  HTTP/1.1
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
Host: example.com
Content-Length: ...
Content-Type: application/scim+json

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId":"736732",
  "userName":"rash",
  "name":{
    "familyName":"Na",
    "givenName":"Rash"
  }
}

Following will be returned in response to the above request containing the created Resource and HTTP code 201, which indicates that the Resource has been created successfully.

HTTP/1.1 201 Created
Content-Type: application/scim+json
Location: https://example.com/v2/Users/229d3f0d-a07b-4052-bf4d-3071ecafed0
ETag: W/"e180ee84f0671b1"

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id":"229d3f0d-a07b-4052-bf4d-3071ecafed0",
  "externalId":"736732",
  "meta":{
    "resourceType":"User",
    "created":"2021-05-23T05:50:28Z",
    "lastModified":"2021-05-23T05:50:28Z",
    "location": "https://example.com/v2/Users/229d3f0d-a07b-4052-bf4d-3071ecafed0",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{
    "familyName":"Na",
    "givenName":"Rash"
  },
  "userName":"rash"
}

You can find more details on SCIM REST APIs by referring to rfc7644 and is.docs.wso2.com/en/5.12.0/develop/scim2-rest-apis.

WSO2 Identity Server

There are multiple SCIM implementations available. WSO2 Inc. provides a SCIM 2.0 implementation known as WSO2 Charon. It is an open source implementation comes under Apache 2.0 license. It can be used by any one who wants to add SCIM-based provisioning support for their applications. WSO2 Charon has been integrated with WSO2 Identity Server to enable identity provisioning.

Hope this article would help you to understand the high-level concept of SCIM. Please refer following for more details.

[1] RFC7642 — SCIM: Definitions, Overview, Concepts, and Requirements — https://datatracker.ietf.org/doc/html/rfc7642

[2] RFC7643— SCIM: Core Schema — https://datatracker.ietf.org/doc/html/rfc7643

[3] RFC7644 — SCIM: Protocol — https://datatracker.ietf.org/doc/html/rfc7644