SCIM, or System for Cross-domain Identity Management, is a standard protocol for managing identities via APIs. It is widely adopted by many well-known IT solutions from vendors such as Microsoft (Entra ID), AWS, Oracle, Salesforce, and many others.

The most commonly used functionalities of SCIM include listing, creating, and updating users. Additionally, it is often utilized to assign users to groups, effectively managing permissions.

A valuable resource for learning SCIM is the SCIM playground available at scim.dev. This web application is an excellent tool if you’re interested in testing SCIM calls or integrating your application with a SCIM sandbox server.

List Users

A GET request to the /Users endpoint retrieves all users. It’s important to note that pagination is typically implemented in such responses. You can navigate through the results using the startIndex parameter. An example response is provided below for your reference. Please note that the list of users is encapsulated within the Resources attribute. While the SCIM protocol defines User and Group as Resources, it also provides the flexibility for you to introduce custom resources as needed.

{
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "id": "9b10f477-10c2-4d38-a509-e64b98857d2f",
      "meta": {
        "created": "2024-01-11T11:07:12+00:00",
        "lastModified": "2024-01-11T11:07:12+00:00",
        "location": "https://api.scim.dev/scim/v2/Users/9b10f477-10c2-4d38-a509-e64b98857d2f",
        "resourceType": "User"
      },
      "urn:ietf:params:scim:schemas:core:2.0:User": {
        "userName": "bjensen",
        "name": {
          "formatted": "Ms. Barbara J Jensen III",
          "familyName": "Jensen",
          "givenName": "Barbara"
        },
        "active": true,
        "emails": [
          {
            "value": "barbara.jensen@example.com",
            "type": "other",
            "primary": true
          },
          {
            "value": "barbara.jensen@example.com",
            "type": "work",
            "primary": true
          }
        ]
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "example:name:space"
      ]
    }
  ]
}

Create User

Users can be created by issuing a POST request to the /Users endpoint. It’s crucial to include all required attributes in the body of the request.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "bjensen",
  "name": {
    "formatted": "Ms. Barbara J Jensen III",
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "active": true,
  "emails": [
    {
      "value": "barbara.jensen@example.com"
    }
  ],
  "userName": "bjensen"
}

This request should yield a 201 Created HTTP response. The body of the response will contain the newly created user with the specified attributes, in addition to attributes generated by the SCIM server, such as timestamps for creation and modification, as well as a unique identifier.

Update Users

In SCIM, a user can be updated using either a PATCH or PUT request. The former allows for the modification of a specific attribute, while the latter replaces the entire User object. Although this might seem less than ideal, a PUT request is typically easier to implement.

For a PUT request, the identifier of the User must be specified in the URI, such as /Users/9b10f477-10c2-4d38-a509-e64b98857d2f. This identifier is returned upon the creation of the user, or it can be retrieved by first listing the users.

The body of the request should contain the complete user object. An example is provided below.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "jcleese",
  "name": {
    "formatted": "Mr. John Cleese",
    "familyName": "Cleese",
    "givenName": "John"
  },
  "emails": [
    {
      "value": "john.cleese@example.com"
    }
  ],
  "userName": "jcleese"
}

Assign Groups to Users

Often, an application needs to assign groups, or permissions, to users. This is typically accomplished by issuing a PATCH request to a specific Group endpoint, such as /Groups/9b10f964-ef91-4e41-97dd-85bb6d28b158. The body of this request should include the identifier of the user who is to be added as a member.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "9b10f477-10c2-4d38-a509-e64b98857d2f"
        }
      ]
    }
  ]
}

Want to learn more?

SCIM offers more than just the basic features mentioned. For instance, it provides an advanced filtering method for retrieving specific resources such as users. It also includes metadata that offers information about the attributes associated with resources, supports bulk requests, and allows for advanced patch requests.

Interested in exploring further? Experiment with the wide range of functionalities offered by the SCIM protocol at scim.dev.