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/.

WSO2 Identity Server as a SCIM Service Provider

Owned by Former user (Deleted)
Last updated: Nov 08, 2017 by Former user (Deleted)
5 min read

WSO2 Charon is an open source implementation of SCIM protocol, which is an open standard for Identity Provisioning. It can be used by any one who wants to add SCIM-based provisioning support for their applications. WSO2 Charon is integrated with WSO2 Identity Server. This page demonstrates the utilization of SCIM endpoints that expose user and group resources in a RESTful way.

The following is a high level overview of SCIM Service Provider architecture of IS.

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.

  1. URL of the SCIM User Endpoint is: https://localhost:9443/wso2/scim/Users
  2. 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":"48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","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":"2012-11-03T18:36:53","location":"https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","created":"2012-11-03T18:36:53"}}

    Some additional attributes exist such as unique id, created, last modified and location, which are READ ONLY attributes and set by the service provider.

    Do the following to test this.

    1. Access the Management Console of the Identity Server in a browser with the URL: https://localhost:9443/carbon/admin/login.jsp and login as an admin using admin credential.
    2. The above created user is shown in the Management Console under: Configure > Users and Roles > Users.
    3. You can access the user profile of the user and see first name and last name are set properly but not other fields. That is because Carbon 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 that using a GET request on the user in question.

  • GET User: You can retrieve a particular user resource using its unique id:

    Request
    curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215

    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, two users called adam and Shyama are created and their 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":3,
"Resources":
[
{"id":"48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","name": {"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini_work.com","type":"work"},{"value":"hasini_home.com","type":"home"}],"meta":{"lastModified":"2012-11-03T18:36:53","created":"2012-11-03T18:36:53","location":"https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215"}},
{"id":"8dd71de9-e2f9-47b7-a5d4-a5f3862950ff","profileUrl":"shyama@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"shyama","givenName":"Shyama"},"userName":"shyama","emails":["shyama@example.com"],"phoneNumbers":[{"value":"7890","type":"mobile"}],"addresses":[{"value":"Panadura","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:53:46","created":"2012-11-03T18:52:41"}},
{"id":"6b14c23d-4811-4bbd-b653-04fcda2df266","profileUrl":"adam@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"adam","givenName":"adam"},"userName":"adam","emails":["adam@gmail.com"],"phoneNumbers":[{"value":"857657","type":"mobile"}],"addresses":[{"value":"Pannipitiya","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:51:52","created":"2012-11-03T18:50:26"}}
]
}

    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:

    Note: You have to use the correct SCIM ID by taking it either from the "create user" response or from the "list user" response.

    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/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215

    You receive a 200 OK response and a payload containing the updated user representation.
     

  • Delete User: Delete the user with userName 'shyama' 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/8dd71de9-e2f9-47b7-a5d4-a5f3862950ff -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 one of the following cURL commands.

    Request
    curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users?filter=userName+Eq+%22adam%22

    OR

    Request
    curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users?filter=userNameEqadam

    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":"6b14c23d-4811-4bbd-b653-04fcda2df266","profileUrl":"adam@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"adam","givenName":"adam"},"userName":"adam","emails":["adam@gmail.com"],"phoneNumbers":[{"value":"857657","type":"mobile"}],"addresses":[{"value":"Pannipitiya","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:51:52","created":"2012-11-03T18:50:26"}}]}

  • 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. So create a new group named: 'engineer' with user 'adam' as a member.

    Request
    curl -v -k --user admin:admin --data "{"displayName": "engineer","members": [{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display": "adam"}]}" --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":"e8868723-30b2-4979-ae23-6d1de2e7d841","schemas":["urn:scim:schemas:core:1.0"],"displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"adam"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}}

    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: 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":"e8868723-30b2-4979-ae23-6d1de2e7d841","displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"adam"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}},
{"id":"3f26902e-c22b-48bc-ba0a-c197a5710b70","displayName":"manager","meta":{"lastModified":"2012-11-03T20:39:25","created":"2012-11-03T20:39:25","location":"https://localhost:9443/wso2/scim/Groups3f26902e-c22b-48bc-ba0a-c197a5710b70"}}
]}

  • Update Group: Rename the group 'manager' to executive:

    Request
    curl -v -k --user admin:admin -X PATCH -d "{"displayName": "executive"}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/3f26902e-c22b-48bc-ba0a-c197a5710b70

    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/3f26902e-c22b-48bc-ba0a-c197a5710b70 -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",null],"totalResults":1,"Resources":[{"id":"e8868723-30b2-4979-ae23-6d1de2e7d841","displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"adam"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}}]}

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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -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

    Request
    curl -k --user gayashan@amrsnghe.org:adminghttps://localhost:9443/wso2/scim/Groups/<id returned in the response when creating the group AMRSNGHE/ngioletGR>