WSO2 Identity Server is capable of exposing REST APIs to manage users in your user stores, via SCIM. SCIM or System for Cross-domain Identity Management is a standard for automating the exchange of user identity information between identity domains, or IT systems. You can read more about SCIM, here. WSO2 Identity Server supports SCIM 1.0 standard from version 5.3.0 and SCIM 2.0 standards from version 5.4.0. You can find the WSO2 official documentation for SCIM 2.0 in here.

Standard SCIM 2.0 API can be used to add a new user, query existing users, update user information, etc. SCIM 2.0 API for WSO2 Identity Server 5.3.0 is a good blog post if you wish to try out these default APIs. But these APIs are limited to the attributes provided by the WSO2 implementation. Today I’m going to discuss how we can update a custom attribute in the user profile using the SCIM 2 API. The attribute I’m aiming to modify is Account Lock Status.

What is User Account Lock

With WSO2 Identity Server, an administrative user can lock and unlock a particular user’s account using the management console or using the AdminService. Locking a Specific User Account document provides more information about this feature. By default, SCIM API cannot change user account lock status as the default SCIM claims does not include it. Our goal is to add the account lock status to the list and invoke the API to lock/ unlock users.

Required Configurations

Open the file <IS-HOME>/repository/conf/scim2-schema-extension.config using a text editor.

1. Add below configuration.

   {
   	"attributeURI":"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:accountLock",
   	"attributeName":"accountLock",
   	"dataType":"boolean",
   	"multiValued":"false",
   	"description":"Lock user account.",
   	"required":"false",
   	"caseExact":"false",
   	"mutability":"readwrite",
   	"returned":"default",
   	"uniqueness":"none",
   	"subAttributes":"null",
   	"canonicalValues":[],
   	"referenceTypes":[]
   }
   

2. Then add the accountLock attribute as a sub-attribute of User.

   "subAttributes":"verifyEmail askPassword accountLock employeeNumber costCenter organization division department manager"
   

Configurations are done now. Save the file and restart the server.

Adding Claim Mappings

Now you can configure the claim mappings in order to map the SCIM user attributes to the LDAP user attributes. Follow below steps to do so.

1. Log into the Management Console.
2. Under the Main tab, click on Claims > Add
3. Click on Add External Claim
4. Select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User as the Dialect URI, give urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:accountLock as External Claim URI and select http://wso2.org/claims/identity/accountLocked for Mapped Local Claim.
5. Click on Add.

Enabling Account Locking Feature.

WSO2 Identity Server doesn’t allow user account locking by default. You have to specifically enable it.To do so follow the below steps.

1. Click on Resident under Identity Providers in the Main tab.
2. Expand the section named Login Policies.
3. Check the checkbox Account Lock Enabled.
4. Then, Click on List under claims and then click on http://wso2.org/claims.
5. Expand the section Account Locked and click Edit.
6. Check the checkbox named Supported by Default and save the changes by clicking the Update button.

You’re all set now. Next step is to use the REST API to lock/ unlock users.

Testing the feature.

In order to update the lock status of a user account, we need to obtain the SCIM ID of that particular user. Therefore, we first call the GET users API to get the user details.

curl -v -k --user admin:admin 'https://localhost:9443/scim2/Users'

This command will query all the users in your user store. If you know some attributes of the user, you can use filters to get fined grained search results. In below command, I’m querying a user with username set to vihanga.

curl -v -k --user admin:admin 'https://localhost:9443/scim2/Users?filter=userName+Eq+vihanga'

After obtaining the SCIM ID of the user, invoke below cURL command with the accountLock attribute set to true or false to lock or unlock the user account.

curl -v -k --user admin:admin -X PATCH -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"replace","value":{"EnterpriseUser":{"accountLock":"false"}}}]}' --header "Content-Type:application/json" https://localhost:9443/scim2/Users/<USER_ID>

After setting the lock status to true for a particular user, the server should reject any authentication attempts done by that account.

This is only a simple example of what can be done using the SCIM 2 API in WSO2 Identity Server. You can add any kind of custom attributes to the user profile and modify them via this method.

That’s the end of this post. Have a great day!