In an Identity Management solution, the user is in the centre of it all. But how can you provision new users? We have several ways to do that, we can let the user self-sign up, but we can also do it programmatically using SCIM.
SCIM (System for Cross Domain Identity Management) is an open standard for user provisioning. There has been couple of revisions since the first release of SCIM and the current version is SCIM 2.0. In short, SCIM makes user data more secure and simplifies the user experience by automating the user identity lifecycle management process.
The use case for SCIM (inbound provisioning) involves automating the creation, update, and deactivation of user accounts in target systems based on information provided by an identity provider. SCIM provides a standardized way for identity providers to communicate with target systems and perform these provisioning operations. It allows for seamless integration and synchronization of user identities across different systems, eliminating the need for manual user management. It ensures consistency, accuracy, and security in user identity management.
While SCIM primarily focuses on inbound provisioning, it can also be used for outbound provisioning where it involves in the synchronization of user account information from identity server to a target third party system. This enables the identity provider to synchronise data across multiple systems..
Bulk import is a feature often associated with SCIM and provisioning systems. It allows for the efficient creation or update of multiple user accounts in bulk, typically through a structured data file. With bulk import, organizations can streamline the initial population of user data or perform large-scale updates across target systems, saving time and effort.
WSO2 Identity Server supports SCIM 2.0 out of the box from WSO2 IS 5.4 onwards. WSO2 IS has provided a set of REST APIs which implements the SCIM 2.0 protocols according to the SCIM 2.0 specification. We will be using the following SCIM 2.0 APIs for a basic user provisioning scenario which includes the following,
- Retrieve all the user
- Create a user
- Retrieve the created user
- Update the user profile
- Update roles of a user
- Delete the user
Before starting, we must start the WSO2 IS server. For this purpose, I will be using the latest WSO2 IS 6.1 running in my local If you do not know how, read one of our blogs. Although this is an older version the principle is the same. However due to the deprecation of analytics you can skip the part about the Analytics server and the trust relationship.
Once WSO2 server is up and running SCIM endpoints can be accessed as below,
- Super tenant: https://<domain>:<port>/scim2
- Other tenants: https://<domain>:<port>/t/<tenant-domain>/scim2
For this purpose, I have started WSO2 IS 6.1 and SCIM endpoint can be accessed with the below URL,
https://localhost:9443/scim2
This endpoint is secured with basic authentication by default so when using these APIs make sure you set the basic authorization header. This can be set up in postman using the Basic Auth type in Authorization tab.
Postman
Postman makes testing out the SCIM APIs easy.
To try out the APIs along with the blog you can download and import the Postman collection from this link https://bitbucket.org/yenlo/yenlo_scim-blog/src/master/scim_apis_postman_collection.json. Once imported, there will be all the required APIs pointing to the running local identity server to try out the basic user provisioning.
I am assuming that you have Postman either installed locally or via the browser. Start Postman on your OS.
When Postman is started you can import the file you downloaded. Look for the import button. Click on it.
Select the file you downloaded
Now we are ready to retrieve information about the users. From the API documentation we know that we can do a GET and what the parameters are.
Retrieve all users
Select Retrieve all the users request in the postman collection.
The endpoint is: GET: https://localhost:9443/scim2/Users
This will return all the user in the IS as below,
This response contains all the required user details such as the ID, username, metadata information and the roles (groups) of the user. Also, the response has the required information to support pagination as well.
Create a user
Select Create a user request in the postman collection.
The endpoint is: POST: https://localhost:9443/scim2/Users
This will create a user and returns the created user details as below,
The created user will be in Primary user store. If the user needs to be created in a different user store, when creating the user provide the username with the prefix {domain-name}/.
For example, if the username is `saad` and the secondary user store domain name is `blog`. Then the username should be `blog/saad`. So that this user will be added to the provided user store.
The created users ID will be saved as variable which will be used during retrieval, update and delete of the user.
Retrieve the created user
Select Retrieve the created user request in the postman collection.
User can be retrieved by the user ID.
The endpoint is: GET: https://localhost:9443/scim2/Users/<user-id>
This will return only the specific user which has the requested user ID as below,
This returns the data specific to the requested user.
Update the user profile
Select Update user request in the postman collection.
User profile can be updated using the user ID.
The endpoint is: PUT: https://localhost:9443/scim2/Users/<user-id>
Updating the user profile to have mobile number:
The response has the updated user profile data which has the updated mobile number of the user. Using this API, other information of the user can also be updated accordingly.
Update roles of a user
Select Retrieve all the roles request in the postman collection and execute the request to store the role IDs as variables which will be used during the update. Then select Update user roles request in the postman collection.
To update the roles of a user, Bulk API can be used. There are APIs provided by Group API but using that we can only update a specific role to add or remove users from the role. But Bulk API can be used to create/update/delete/replace SCIM resources in bulk. Depending on the operation provided in the request payload, the relevant SCIM resource will get affected accordingly.
The endpoint is: POST: https://localhost:9443/scim2/Bulk
Adding two roles to the user
In this API there are multiple operations provided to add the user to multiple roles and the response has a status code for each operation.
Delete the user
Select Delete a user request in the postman collection.
User can be deleted by the user ID.
The endpoint is: DELETE: https://localhost:9443/scim2/Users/<user-id>
A specific user can be deleted as below by providing the user ID,
This API responds with a 204 HTTP status code to imply the request is success. Hence, the user is deleted successfully.
Above explained APIs can be used for basic user provisioning using SCIM APIs. There are many more SCIM APIs which can be utilized based on the use case. All the other SCIM APIs can be checked through WSO2 Documentation.
Conclusion
By following the above steps user provisioning can be achieved with WSO2 identity Server using the SCIM protocol.
SCIM can be used with LDAP (Lightweight Directory Access Protocol) or AD (Active Directory) to facilitate user provisioning and identity management. LDAP is commonly used for storing and retrieving user identities, attributes, and organizational information. SCIM can integrate with LDAP to automate the provisioning of user accounts and the synchronization of user attributes between the identity provider and LDAP directory.
Similarly, SCIM can also integrate with AD, which is a directory service provided by Microsoft for Windows-based environments. AD is widely used in organization for user authentication, authorization and identity management. SCIM can leverage AD’s capabilities for user provisioning and synchronization between identity provider and AD.
While SCIM is often associated with directory service like LDAP and AD, it is flexible enough to work with RDBMS (Relation Database Management System) to manage a large user store efficiently. By leveraging SCIM with RDBMS for a large user store, organization can benefit from streamlined user management and efficient provisioning. It provides a scalable and customizable solution to handle user identities and its attributes we are allowing to maintain user data in a relational database.
The integration of SCIM with LDAP or AD or RDBMS provides a standardized and automated approach to user management, reducing manual effort, ensuring consistency, and improving data accuracy across systems.
By using the SCIM protocol benefits such as identity centralization and provisioning standardization can be obtained. Hence, it is indeed beneficial for organization to use SCIM protocol for identity provisioning.
