This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
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.
Navigate to the SCIM User Endpoint at the following URL:Â https://localhost:9443/wso2/scim/Users.
You can use the following SCIM User Endpoint to specifically return data of the currently logged-in user: https://localhost:9443/wso2/scim/Users/me
(You can use this endpoint for commands that refer to a single user, such as GetUser, UpdateUser etc.)- Navigate to the SCIM Group Endpoint at the following URL:Â
https://localhost:9443/wso2/scim/Groups.
These endpoints are exposed over HTTPS since sensitive information is exchanged and also protected with Basic Auth Authentication.
The following requests use Basic Auth authentication to demonstrate sending requests to the REST endpoints of WSO2 Identity Server as a quick start. In a production environment, we recommend that you use OAuth Authentication instead.
Create User: The following command can be used to create a user.
Requestcurl -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
In this request, 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"}}
Some additional attributes such as
unique id
,created
,last modified
andlocation
are READ ONLY attributes and are set by the service provider.Do the following to test this.
- Login to the the WSO2 IS management console using admin credentials (admin/admin).
- Click List under the Users and Roles section on the Main tab and then select Users. You will see that the user created above is listed.Â
- Click on User Profile to view the user profile of the user you created. You will see that only the user's first and last names have been set properly but the other fields remain empty. This is because the Carbon platform uses a different set of attributes in LDAP than the SCIM specific dialect. However, those attributes are stored in the underlying user store. You can verify using a GET request on the particular user.
GET User:Â You can retrieve a particular user resource using its unique id (You will get this id in the response to the
create user
request):Requestcurl -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.
Alternatively, you can login as a user and use the
Users/me
SCIM endpoint to retrieve data of the currently logged-in user:Âcurl -v -k --user hasinitg:hasinitg https://localhost:9443/wso2/scim/Users/me
For this command, the user credentials of the user created above (hasinitg) was used as an example.
List Users: Now create some users through the WSO2 IS management console and fill in their profile details. The following code snippets show the response received after a new user called "pulasthim" was created and the user profile was updated. Â
Requestcurl -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 fields of the user "hasinitg" through the following cURL command:
Note: You have to use the correct SCIM ID by taking it either from the "create user" response or from the "list user" response.
Requestcurl -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.
Alternatively, you can use the
Users/me
SCIM endpoint to update the user profile of the currently logged-in user:curl -v -k --user hasinitg:hasinitg -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/me
For this command, the user credentials of the user created above (hasinitg) was used as an example.
Delete User:Â Delete the user with username 'pulasthim' that was created through the WSO2 IS management console.Â
Requestcurl -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 will be 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 the service provider, the 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.
Requestcurl -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.
Note: When creating a group with users, you need to have that user already existing in the user store and provide its unique id. Create a new group named: 'engineer' with the user 'hasinitg' as a member. The attributes you have to include in the cURL command are the user ID, username:password.
Requestcurl -v -k --user admin:admin --data '{"displayName": "engineer","members": [{"value":"316214c0-dd7e-4dc3-bed8-e91227d32597","hasinitg": "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.Â
Requestcurl -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:
Requestcurl -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'.
Requestcurl -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'.
Requestcurl -v -k --user admin:admin https://localhost:9443/wso2/scim/Groups?filter=displayName+Eq+%22engineer%22
OR
Requestcurl -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"}}]}
Now, you can use the above commands or similar in a sample scenario.
Using the SCIM API
This sample scenario is to add users and groups to a super tenant and a normal tenant so that the users are unique to their domains.
For the super tenant:
Create group AMRSNGHE/ngioletGR
Requestcurl -k --user admin:admin --data '{"displayName": "AMRSNGHE/ngioletGR"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups
Response{"id":"8ee9253e-4fe1-4863-9641-80d807611707","schemas":["urn:scim:schemas:core:1.0"],"displayName":"AMRSNGHE/ngioletGR","meta":{"lastModified":"2015-04-30T10:18:33","created":"2015-04-30T10:18:33","location":"https://localhost:9443/wso2/scim/Groups/8ee9253e-4fe1-4863-9641-80d807611707"}}
Create user AMRSNGHE/groupUSR001
Requestcurl -k --user admin:admin --data '{"schemas":[],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR001","password":"testPwd123"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users
Response{"id":"bbda8f2f-fea7-4a9c-9128-f1e0c3aad475","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR001","meta":{"lastModified":"2015-04-30T10:19:05","location":"https://localhost:9443/wso2/scim/Users/bbda8f2f-fea7-4a9c-9128-f1e0c3aad475","created":"2015-04-30T10:19:05"}}
Create user AMRSNGHE/groupUSR002
Requestcurl -k --user admin:admin --data '{"schemas":[],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR002","password":"testPwd123"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users
Response{"id":"e04e20ca-6321-4c75-88b9-cfa5a600e356","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR002","meta":{"lastModified":"2015-04-30T10:19:14","location":"https://localhost:9443/wso2/scim/Users/e04e20ca-6321-4c75-88b9-cfa5a600e356","created":"2015-04-30T10:19:14"}}
Add user AMRSNGHE/groupUSR001 to group AMRSNGHE/ngioletGR
Requestcurl -k --user admin:admin -X PATCH -d '{"displayName": "AMRSNGHE/ngioletGR","members": [{"value":"<id returned in the response when creating the AMRSNGHE/groupUSR001>","display": "AMRSNGHE/groupUSR001"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>
Add user AMRSNGHE/groupUSR002 to group AMRSNGHE/ngioletGR
Requestcurl -k --user admin:admin -X PATCH -d "{"displayName": "AMRSNGHE/ngioletGR","members": [{"value":"<id returned in the response when creating the AMRSNGHE/groupUSR002>","display": "AMRSNGHE/groupUSR002"}]}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>
List the group members
Requestcurl -k --user admin:adminhttps://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>
For a tenant amrsnghe.org:
Create group AMRSNGHE/ngioletGR
Requestcurl -k --user gayashan@amrsnghe.org:adming --data '{"displayName": "AMRSNGHE/ngioletGR"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups
Response{"id":"8ee9253e-4fe1-4863-9641-80d807611707","schemas":["urn:scim:schemas:core:1.0"],"displayName":"AMRSNGHE/ngioletGR","meta":{"lastModified":"2015-04-30T10:18:33","created":"2015-04-30T10:18:33","location":"https://localhost:9443/wso2/scim/Groups/8ee9253e-4fe1-4863-9641-80d807611707"}}
Create user AMRSNGHE/groupUSR001
Requestcurl -k --user gayashan@amrsnghe.org:adming --data '{"schemas":[],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR001","password":"testPwd123"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users
Response{"id":"bbda8f2f-fea7-4a9c-9128-f1e0c3aad475","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR001","meta":{"lastModified":"2015-04-30T10:19:05","location":"https://localhost:9443/wso2/scim/Users/bbda8f2f-fea7-4a9c-9128-f1e0c3aad475","created":"2015-04-30T10:19:05"}}
Create user AMRSNGHE/groupUSR002
Requestcurl -k --user gayashan@amrsnghe.org:adming --data '{"schemas":[],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR002","password":"testPwd123"}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users
Response{"id":"e04e20ca-6321-4c75-88b9-cfa5a600e356","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"John","givenName":"Doe"},"userName":"AMRSNGHE/groupUSR002","meta":{"lastModified":"2015-04-30T10:19:14","location":"https://localhost:9443/wso2/scim/Users/e04e20ca-6321-4c75-88b9-cfa5a600e356","created":"2015-04-30T10:19:14"}}
Add user AMRSNGHE/groupUSR001 to group AMRSNGHE/ngioletGR
Requestcurl -k --user gayashan@amrsnghe.org:adming -X PATCH -d '{"displayName": "AMRSNGHE/ngioletGR","members": [{"value":"<id returned in the response when creating the AMRSNGHE/groupUSR001>","display": "AMRSNGHE/groupUSR001"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>
Add user AMRSNGHE/groupUSR002 to group AMRSNGHE/ngioletGR
Requestcurl -k --user gayashan@amrsnghe.org:adming -X PATCH -d '{"displayName": "AMRSNGHE/ngioletGR","members": [{"value":"<id returned in the response when creating the AMRSNGHE/groupUSR002>","display": "AMRSNGHE/groupUSR002"}]}' --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>
List the group members
Requestcurl -k --user gayashan@amrsnghe.org:adminghttps://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>