How to add SCIM Extended Attributes in WSO2 Identity Server
❓Why Extended Attributes?
In my previous blog, I explained the core and basics of SCIM schema. There you can see how SCIM defines the user object. It contains a common set of user attributes that ensure interoperability with heterogeneous user management systems. The core schema for “User” is identified using the following schema URI:
“urn:ietf:params:scim:schemas:core:2.0:User” and SCIM extension defines user attributes commonly used in business or enterprise. The EnterpriseUser extension is identified using the following schema URI:
As I have highlighted in the previous blog, SCIM doesn’t replace any userstore. instead, it acts as a standard interface on top of the underlying userstores. In reality, organizations may have their own attributes defined for their users which have already been used in their LDAP schemas or any other userstore schema. If SCIM supports only the attributes defined in the User and EnterpriseUser schemas, what will happen to other user attributes ???😨
Without making things complicated, SCIM has introduced the extensions to extend resource types. So, we are not going to put our hands on the core User schema(
urn:ietf:params:scim:schemas:core:2.0:User) (which is common for the universe), but we can play with EnterpriseUser schema
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User . Therefore, we can add custom attribute definitions into EnterpriseUser schema and use SCIM API to manage those user attributes in the underlying userstore.
Hurry!! Problem gets solved. 🥳
Being practical is better than theory. So, Let’s see how this extending can be done in WSO2 Identity Server 5.10.0
- Log in to the management console (
- Navigate to
Main menu-> Identity tab -> Claimsand click on List.
- Click on
- You can see an attribute called Account Disabled with the claim URI
http://wso2.org/claims/identity/accountDisabled. Click on the
Editbutton and then tick
Supported by Default.
- Now you diable/enable the user account via the management console. (Navigate to
Main menu-> Identity tab -> Users and Roles-> List-> Usersand click on User Profile of a particular user and update the Account Disabled value as true)
- Now get the SCIM ID of that user by “User ID” attribute or find out it by
- Then get the user’s details by performing a
WHAT 😨?? Account Disabled attribute is not returned in the response. Why is that?? Let’s see. It may be due to one of the following reasons.
- If the particular attribute is in the core User schema or EnterpriseUser schema check the returned characteristic of the attribute. If the returned = “never” that attribute doesn’t appear in the response. (Core SCIM schema definitions in WSO2 IS- 5.10.0 can be found here and EnterpriseUser schema can be found
- Even though there is a local claim under
http://wso2.org/claimsdialect, if it is not mapped to any SCIM attribute, such details don’t return in SCIM response. NOTE: Navigate to
Main menu-> Identity tab -> Claims. You will see two dialects named,
urn:ietf:params:scim:schemas:core:2.0:User— Map attributes defined in core user schema to local attributes/claims in the WSO2-IS userstore
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User— Map attributes defined in EnterpriseUser schema to local attributes/claims in the WSO2-IS userstore
When doing the above troubleshooting you will identify that,
According to the first point — there is no matching attribute definition to “Account Disabled” in the User core schema or the existing EnterpriseUser schema.
According to the second point — there is no mapping for
http://wso2.org/claims/identity/accountDisabled claim in the mentioned claim dialects.
Here we go to fix them.
➕ Add an Attribute Definition
As I mentioned before, we don’t have the right to change the core user schema if “Account Disabled” is not included in the core schema. Hence, we can add a new attribute to EnterpriseUser schema.
- Open the
scim2-schema-extension.configfile located in the
Define the extension by adding attribute in the following format before the last element of the JSON array (i.e. urn:ietf:params:scim:schemas:extension:enterprise:2.0:User should be the last JSON object)in the
scim2-schema-extension.config file. Read the Attribute Definition section of this blog to understand what each property is referred to. Then modify the attribute definition according to your requirement.
3. Add the attributeName of the above-added attribute into
scim2-schema-extension.config file, as a
subAttribute of the
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User attribute (in the same file)as seen in the code block below.
“subAttributes”:”verifyEmail askPassword employeeNumber costCenter organization division department manager pendingEmails accountDisabled”,
4. Save the file and restart the WSO2 Identity Server.
🔁 Map SCIM attribute URI to Local attribute
- Log in to management console (
- Navigate to
Main menu-> Identity tab -> Claims.
Add External Claimand enter the following values. Then click on
Dialect URI: urn:ietf:params:scim:schemas:extension:enterprise:2.0:UserExternal Claim URI: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:accountDisabled (Attribute URI defined in the previous step)Mapped Local Claim: http://wso2.org/claims/identity/accountDisabled
5. Then you will be able to see the claim mapping in
All configurations are done. Let’s see how to create a user with this attribute and whether the attribute is returned in the response.
Create User with account Disabled attribute:
POST request to
The response will be
HTTP status code 201 Created with response body:
You can see
“accountDisabled”: true under
“urn:ietf:params:scim:schemas:extension:enterprise:2.0:User” namespace. Also, you can verify that the particular attribute is updated in the user profile via the management console.
Cheers! We did it. 🥳
NOTE: By any chance, if you want to add a new custom claim to the WSO2 IS and then map it to the SCIM attribute the following step should be done prior to the previous two steps.
📝 Create a local claim
You can follow the steps given in https://is.docs.wso2.com/en/latest/develop/extending-scim2-user-schemas/#add-the-custom-claim to satisfy this requirement.
One more reminder: If you are adding a user claim (http://wso2.org/claims/) and the attribute mapping is done with an LDAP/ directory userstore’s attribute, the mapping attribute should be in that LDAP/ directory schema. “customClaim” attribute is a general term used for the example, there is no such attribute in default LDAP userstore of WSO2 IS.
Happy Reading !! Stay Tuned !! 😇