Oct 22, 2020
Communicating with WSO2 Identity Server using the SCIM 2.0 Users REST Endpoint
This blog post will look at how some user provisioning tasks can be performed by communicating with the SCIM 2.0 Users REST API endpoint in the WSO2 Identity Server.
User provisioning includes the creation, management, deletion of user accounts and managing the rights associated with these accounts. In the WSO2 Identity Server, inbound user provisioning can be used to add users from external applications. It supports inbound user provisioning using SCIM REST API endpoints.
SCIM
SCIM, which stands for System for Cross-domain Identity Management is an HTTP based protocol that uses JSON payloads that can be used for user provisioning and user management in cross domain environments. More information about the SCIM protocol can be found in the IETF specification linked in the references section at the bottom.
In the WSO2 Identity Server, the URLs SCIM endpoints can be found by going to Main > Identity Providers > Resident > Resident Realm Configuration and expanding the Inbound Provisioning Configuration.
The SCIM 2.0 Users endpoint in the identity server in a local installation is https://localhost:9443/scim2/Users.
User Creation
A user is a SCIM resource, which is a JSON object that can be created, maintained, and deleted using HTTP requests.
Each resource representation contains an attribute named “schemas”, which should contain a list of URIs. This list of URIs indicate the included SCIM schemas which are used to show the attributes contained within a resource.
The core schema for the User resource has the following URI: urn:ietf:params:scim:schemas:core:2.0:User. This core schema defines attributes such as userName, name, familyName etc. More information about these attributes and other attributes can be found here.
With WSO2 identity server it is possible to extend the SCIM 2.0 User Schema. More information about schema extension can be found here.
To create a new user, an HTTP POST request can be made to the Users endpoint. All requests made to the SCIM endpoints need to contain valid HTTP authentication information for a user with the necessary permissions in the header. The WSO2 Identity Server SCIM API supports both Basic Authentication and OAuth 2.0. The latter is recommended.
The /permission/admin/manage/identity/usermgt/create permission is necessary for user creation.
A request for a user resource registration creation can be made as shown below using a tool like curl, postman etc. to the https://localhost:9443/scim2/Users endpoint. The content type can be set to either application/json or application/scim+json. The userName attribute is required.
{
"schemas": [],
"name": {
"familyName": "doe",
"givenName": "john"
},
"userName": "john",
"password": "password",
"emails": [
{
"primary": true,
"value": "john@example.com",
"type": "home"
},
{
"value": "johnwork@example.com",
"type": "work"
}
]
}As a result of the above request, the user will be created and a response similar to the following should be returned,
{
"emails": [
{
"type": "work",
"value": "johnwork@example.com"
},
{
"type": "home",
"value": "john@example.com"
}
],
"meta": {
"created": "2020-10-22T06:03:38.036Z",
"location": "https://localhost:9443/scim2/Users/9b371e7d-bd4e-42d4-9c2d-24f8505a9c8d",
"lastModified": "2020-10-22T06:03:38.036Z",
"resourceType": "User"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"roles": [
{
"type": "default",
"value": "Internal/everyone"
}
],
"name": {
"givenName": "john",
"familyName": "doe"
},
"id":"9b371e7d-bd4e-42d4-9c2d-24f8505a943d",
"username": "john"
}Retrieving User Information
In addition to creating users, user information can be viewed by sending an HTTP GET request to https://localhost:9443/scim2/Users/<User-Id>. The user making the request need the /permission/admin/manage/identity/usermgt/view permission to access this data.
For example, in order to view the information of the user created above, you can send a GET request to https://localhost:9443/scim2/Users/9b371e7d-bd4e-42d4–9c2d-24f8505a9. This will return the same JSON response as above.
Updating and Deleting Users
Information for this user can be updated by sending a PUT or PATCH request to this same URL. As usual, PUT is used for attribute replacement while PATCH is used for partial updates. In addition to that, this user can be deleted by sending a DELETE request to this URL. The update and delete operations require /permission/admin/manage/identity/usermgt/update and /permission/admin/manage/identity/usermgt/delete permissions
Filtering and Listing Users
A list of the users can can be obtained by sending a get request to the https://localhost:9443/scim2/Users/endpoint. The filter parameter can be used to filter the users. In addition to that, parameters startIndex and count can be used for pagination. For sorting sortBy and sortOrder parameters can be used. There are few other parameters as well. More information about these parameters are available in the SCIM 2.0 — WSO2 Identity Server documentation linked below. The requesting user must have the /permission/admin/manage/identity/usermgt/view permission.
Similarly, but using a POST request on the https://localhost:9443/scim2/Users/.search endpoint, it is possible to search users.
More about the features/endpoints of the SCIM API not discussed here can be found out from the links in the references section below.
