SCIM APIs

The SCIM API can be called in order to perform various tasks in the WSO2 Identity Server. For simplicity, cURL commands are used in this example to send CRUD requests to the REST endpoints of Identity Server.

Download the WSO2 Identity Server, unzip it and run it.

URL of the SCIM User Endpoint is: https://localhost:9443/wso2/scim/Users
URL of the SCIM Group Endpoint is: https://localhost:9443/wso2/scim/Groups

These endpoints are exposed over HTTPS since sensitive information is exchanged and also protected with Basic Auth Authentication.

Create User: The following command can be used to create a user.
Request
curl -v -k --user admin:admin --data '{"schemas":[],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","password":"hasinitg","emails":[{"primary":true,"value":"hasini_home.com","type":"home"},{"value":"hasini_work.com","type":"work"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users
Here authentication is done using Basic Auth and the payload is sent in JSON format adhering to the SCIM 1.1 specification. You receive a response with 201 CREATED status and the payload response as follows:
Response
{"id":"0032fd29-55a9-4fb9-be82-b1c97c073f02","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini_home.com","type":"home"},{"value":"hasini_work.com","type":"work"}],"meta":{"lastModified":"2016-01-26T16:46:53","location":"https://localhost:9443/wso2/scim/Users/0032fd29-55a9-4fb9-be82-b1c97c073f02","created":"2016-01-26T16:46:53"}}
Do the following to test this.

GET User: You can retrieve a particular user resource using its unique id (You'll get this id in the response to the create user request):
Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users/0032fd29-55a9-4fb9-be82-b1c97c073f02
The response consists of all attributes that were sent.

List Users: Now create some users through the Management Console of the Identity Server and fill in their profile details. For the purposes of this example, created another user called pulasthim and the profile details are entered.
Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users
The following is the response you would receive.
Response
{"schemas":["urn:scim:schemas:core:1.0"],"totalResults":2,"Resources":[{"id":"0032fd29-55a9-4fb9-be82-b1c97c073f02","userName":"hasinitg","meta":{"lastModified":"2016-01-26T16:46:53","created":"2016-01-26T16:46:53","location":"https://localhost:9443/wso2/scim/Users/0032fd29-55a9-4fb9-be82-b1c97c073f02"}},{"id":"b228b59d-db19-4064-b637-d33c31209fae","userName":"pulasthim","meta":{"lastModified":"2016-01-26T17:00:33","created":"2016-01-26T17:00:33","location":"https://localhost:9443/wso2/scim/Users/b228b59d-db19-4064-b637-d33c31209fae"}}]}
You can see the representation of the three users with attributes in JSON format adhering to SCIM Schema.

Update User: Update the work and home email of the user: hasinitg through the following cURL command:
Request
curl -v -k --user admin:admin -X PUT -d '{"schemas":[],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini@wso2.com","type":"work"},{"value":"hasi7786@gmail.com","type":"home"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users/0032fd29-55a9-4fb9-be82-b1c97c073f02
You receive a 200 OK response and a payload containing the updated user representation.
Delete User: Delete the user with userName 'pulasthim' that was created through the Management Console in the Identity Server:
Request
curl -v -k --user admin:admin -X DELETE https://localhost:9443/wso2/scim/Users/b228b59d-db19-4064-b637-d33c31209fae -H "Accept: application/json"
You receive a response with status 200 OK and the user is deleted from the user store. Similarly, you can manage groups by performing CRUD operations on the Group resource endpoint.
Filter User: Since CRUD operations have to be performed using SCIM ID which is unique to Service Provider, User REST endpoint also supports the filter operation. You can filter users based on their username, which is considered the unique user attribute in Carbon servers. You can use the following cURL command.
Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users?filter=userName+Eq+%22hasinitg%22
You receive a response similar to the one below from which you can extract the SCIM ID to perform the rest of the operations.
Response
{"schemas":["urn:scim:schemas:core:1.0"],"totalResults":1,"Resources":[{"id":"0032fd29-55a9-4fb9-be82-b1c97c073f02","userName":"hasinitg","meta":{"lastModified":"2016-01-26T18:26:04","created":"2016-01-26T16:46:53","location":"https://localhost:9443/wso2/scim/Users/0032fd29-55a9-4fb9-be82-b1c97c073f02"}}]}
Create Group: You can create groups either with or without members. The following command creates a group with a user.
Request
curl -v -k --user admin:admin --data '{"displayName": "engineer","members": [{"value":"0032fd29-55a9-4fb9-be82-b1c97c073f02","display": "hasinitg"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups
You receive a response with the payload as indicated below and a response status 201 CREATED:
Response
{"id":"b4f9bccf-4f79-4288-be21-78e0d4500714","schemas":["urn:scim:schemas:core:1.0"],"displayName":"PRIMARY/engineer","members":[{"value":"0032fd29-55a9-4fb9-be82-b1c97c073f02","display":"hasinitg"}],"meta":{"lastModified":"2016-01-26T18:31:57","created":"2016-01-26T18:31:57","location":"https://localhost:9443/wso2/scim/Groups/b4f9bccf-4f79-4288-be21-78e0d4500714"}}
You can observe in the management console of IS, that the new group is listed under roles and user 'adam' is listed under users of that group.
List Groups: Now create another role through the Identity Server Management Console and list all the groups. Create a group named: 'manager' without any users added to it. The following command lists the groups.

Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Groups

When you list the groups you can see both groups are listed.
Response
{"schemas":["urn:scim:schemas:core:1.0"],"totalResults":2,"Resources":[{"id":"b4f9bccf-4f79-4288-be21-78e0d4500714","displayName":"PRIMARY/engineer","meta":{"lastModified":"2016-01-26T18:31:57","created":"2016-01-26T18:31:57","location":"https://localhost:9443/wso2/scim/Groups/b4f9bccf-4f79-4288-be21-78e0d4500714"}},{"id":"484cdc26-9136-427b-ad9e-96ea3082e1f5","displayName":"PRIMARY/manager","meta":{"lastModified":"2016-01-26T18:33:33","created":"2016-01-26T18:33:33","location":"https://localhost:9443/wso2/scim/Groups/484cdc26-9136-427b-ad9e-96ea3082e1f5"}}]}
Update Group: Rename the group 'manager' to executive:
Request
curl -v -k --user admin:admin -X PUT -d '{"displayName": "executive"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/484cdc26-9136-427b-ad9e-96ea3082e1f5
You receive a response with 200 OK status and full JSON representation of the updated group.
Delete Group: You can delete the group using the unique SCIM Id of the group. The following command deletes the group: 'executive'.
Request
curl -v -k --user admin:admin -X DELETE https://localhost:9443/wso2/scim/Groups/484cdc26-9136-427b-ad9e-96ea3082e1f5 -H "Accept: application/json"
Filter Group: You can filter groups with the group display name using one of the following commands. These commands filter the group with display name: 'engineer'.
Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Groups?filter=displayName+Eq+%22engineer%22
OR
Request
curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Groups?filter=displayNameEqengineer
The following is the response you would get.
Response
{"schemas":["urn:scim:schemas:core:1.0"],"totalResults":1,"Resources":[{"id":"b4f9bccf-4f79-4288-be21-78e0d4500714","displayName":"PRIMARY/engineer","meta":{"lastModified":"2016-01-26T18:31:57","created":"2016-01-26T18:31:57","location":"https://localhost:9443/wso2/scim/Groups/b4f9bccf-4f79-4288-be21-78e0d4500714"}}]}