Automated User Provisioning Using SCIM(System for Cross-domain Identity Management)

System for Cross-domain Identity Management (SCIM) is a standard protocol for automating the exchange of user identity information between identity providers. It is an automated process of creating, updating, and deleting user accounts across different systems using the SCIM protocol. In simple terms, it allows organizations to manage user identities in a centralized location and automatically synchronize them across various systems.

Integrating an existing system with SCIM involves implementing the SCIM protocol in your system to enable the exchange of user identity information. By doing so, customers can benefit from streamlined user management and reduced administrative overhead.

For example, suppose an organisation is using an HR system to manage employee data and a cloud-based application, let’s say Zoom, to provide employees with access to virtual meetings. In that case, integrating these two systems with SCIM will allow the HR system to automatically create, update, and delete user accounts in the cloud-based Zoom application. This eliminates the need for manual user account management and ensures that user information is consistent across all systems.

SCIM defines CRUD (Create, Read, Update, Delete) operations for managing user identity information. Let’s take a look at each of these operations.

Creating a User

This is how a single Create User API interaction looks like

URL: /scim/v2/Users
method: POST
request_body: {
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jsmith",
  "name": {
    "givenName": "John",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "jsmith@example.com",
      "type": "work",
      "primary": true
    }
  ]
}

response_body: {
  "id": "0123456789",
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jsmith",
  "name": {
    "givenName": "John",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "jsmith@example.com",
      "type": "work",
      "primary": true
    }
  ]
}

If you look closely, the URL refers to User resource and method POST refers to the Create operation. The Request and Response look exactly the same, except for the id in the response body, which is only generated after the User is created. This is the User object and it is this same object that will be exchanged for any of the CRUD operations.

Reading a User

URL: /scim/v2/Users/0123456789 
method: GET
request_body: empty
response_body: <USER_OBJECT>

OR 

URL: /scim/v2/Users?filter=userName eq "test@mycompany.com"
method: GET
request_body: empty
response_body: <USER_OBJECT>

Updating a User

URL: /scim/v2/Users/0123456789
method: PUT
response_body: <USER_OBJECT>

You can also implement a PATCH method for your user api, and for some Identity providers such as OKTA, it’s required that you do, as it uses PATCH to communicate a few types of updates. However it’s much more complex that this simple PUTapi and should be implemented carefully. We will look at the PATCH method along with the DELETE method below.

Deleting a User

The following code snippet demonstrates how to delete a user using the SCIM API in JavaScript.

URL: /scim/v2/Users/0123456789
method: DELETE

The request structure for deleting a user in SCIM is the same as the request structure for retrieving a user. The response structure for deleting a user in SCIM is not applicable as the server typically returns a 204 No Content status code.

Additionally, some Identity providers(eg. Okta) may not support DELETE operation. Instead, they rely on Update operation on the User by updating some property such as active to false using the PATCH request. Here is how it looks.

URL: /scim/v2/Users/0123456789
method: PATCH
request_body: {
  'schemas'    => ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
  'Operations' => [
    {
      'op'    => 'add',
      'path'  => 'name.familyName',
      'value' => 'Johny'
    },
    {
      'op'    => 'remove',
      'path'  => 'name.givenName'
    },
    {
      'op'    => 'replace',
      'path'  => 'active',
      'value' => false
    }
  ]
}

SCIM allows three types of operations in patch, add, remove and replace Okta only uses replace and that too only for making user inactive. i.e. active=false . Other operations may be supported by other identity providers and should e implemented accordingly. A general purpose SCIM Client should implement all PUT, PATCH and DELETE methods to make modifications to the User resource

SCIM Workflows

So far we have only seen how individual APIs in SCIM work. SCIM Identity providers usually, in order to remain sync with the service provider, need to do a lot more than calling a single API per operation.

let’s imagine Zoom has already setup their SCIM APIs and Customer has already Integrated it with Okta. Now, a user( test@mycompany.com) can be assigned to Zoom from Okta and that should result in a User getting Created within your Zoom tenant. Here is how the interaction looks like.

1. When the user getting assigned to Zoom from Okta does not already exist in Okta.

2. When the user getting assigned to Zoom from Okta already exists in Okta.

Lets understand whats happening here.

1. An Admin assigned a User test@mycompany.com to Zoom App from Okta.
2. Okta makes a SCIM GET request, with a filter criteria of userName eq "test@mycompany.com", There are two ways zoom can respond to this request. Zoom may already have a user matching the filter criteria or it may not.
3. If the user does not already exist in Zoom, then it will not return the user Object, this way Okta understands that it needs to create a new user, and thus sends a create user request.
4. If the user already exists in zoom, then it will return the User object with the details of the user. This way Okta knows the User exists in Zoom and also the current details of the User in Zoom. Okta will send an Update user request with the latest details of the user that it has.

Hereafter, Okta has the external user id(zoom user id) for test@mycompany.com, and on any subsequent changes to the same user, Okta can directly access the user in Zoom using GET, PUT or DELETE api with its own resource URL. For example, GET /scim/v2/Users/0123456789

Identity providers follow similar workflows for updating the users as well. i.e they will first make a get call to get the latest details of the user and depending on the change required, make a single or multiple PUT/PATCH/DELETE requests.

A few caveats

During our implementation of SCIM user provisioning, we faced the following problems:

Lack of Standardization: One of the biggest challenges we faced was the lack of standardization in the SCIM specification. Different vendors implement the specification in slightly different ways. For example some vendors make DELETE request for deactivating the user and some might make either PUT or PATCH request and just update the user as inactive.

This made it difficult to ensure compatibility between our system and third-party applications.

To overcome this problem, we invested time in thoroughly understanding the SCIM specification and its various implementations. We also made sure to test our implementation with different vendors and fine-tune our implementation to ensure maximum compatibility.

Complex Data Models: Another challenge we faced was working with complex data models in the SCIM specification. The specification includes a wide range of attributes and complex data structures, which made it difficult to ensure consistency and accuracy across different systems.

To overcome this problem, we carefully created mapping functions to transform our existing User model into SCIM user model. We also invested time in understanding the data structures used by different vendors and mapped our data model accordingly.

There are libraries out there for most of the programming languages. However most of them lack support for multitude of features in SCIM, so it is important to carefully choose one and build additional required features on top of it.

Security Concerns: Security is a major concern when implementing user provisioning systems, as it involves handling sensitive user data. We had to ensure that our implementation met the highest security standards to ensure that user data was protected at all times.

To address security concerns, we implemented signed JWT based bearer token authentication. Most of the identity providers support basic auth, token authentication as well as OAuth. However SCIM by itself does not limit us to implement stricter security measures, as long as both the parties involved in SCIM communication support it.

Conclusion

To implement SCIM user provisioning, it’s important to carefully plan the data model, security protocols, and integration with existing systems. It’s also important to be aware of the challenges and potential pitfalls associated with the specification, such as lack of standardization and complex data models. However, with careful planning and implementation, SCIM user provisioning can provide significant benefits for organizations of all sizes.

Thank you for reading!

References

SCIM 2.0 specification: https://tools.ietf.org/html/rfc7644 OpenID Foundation SCIM Implementation Guide: https://openid.net/specs/openid-connect-scim-2.0.html Okta Developer SCIM documentation: https://developer.okta.com/docs/reference/scim/ OneLogin Developer SCIM documentation: https://developers.onelogin.com/scim