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: “urn:ietf:params:scim:schemas:extension:enterprise:2.0:User”.

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

1. Log in to the management console (https://{host}:{port}/carbon/)
2. Navigate to Main menu-> Identity tab -> Claims and click on List.
3. Click on http://wso2.org/claims claim dialect.
4. You can see an attribute called Account Disabled with the claim URI http://wso2.org/claims/identity/accountDisabled. Click on the Edit button and then tick Supported by Default.
5. Now you diable/enable the user account via the management console. (Navigate to Main menu-> Identity tab -> Users and Roles-> List-> Users and click on User Profile of a particular user and update the Account Disabled value as true)
6. Now get the SCIM ID of that user by “User ID” attribute or find out it by GET request to https://{host}:{port}/scim2/Users/.
7. Then get the user’s details by performing a GET request to https://{host}:{port}/scim2/Users/{user-id}.

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.

1. 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 <IS-product-home>/wso2is-5.10.0/repository/conf/scim2-schema-extension.config file)
2. Even though there is a local claim under http://wso2.org/claims dialect, 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.

1. Open the scim2-schema-extension.config file located in the <IS_HOME>/repository/conf/ folder.

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 asubAttribute 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

1. Log in to management console (https://{host}:{port}/carbon/).
2. Navigate to Main menu-> Identity tab -> Claims .
3. Click Add under Claims.
4. Click Add External Claim and enter the following values. Then click on Add.

Dialect URI: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
External 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 urn:ietf:params:scim:schemas:extension:enterprise:2.0:User dialect.

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 https://{host}:{port}/scim2/Users

Request body:

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.

References:

• https://is.docs.wso2.com/en/latest/develop/extending-scim2-user-schemas/#extending-the-scim-20-api

Happy Reading !! Stay Tuned !! 😇