User Account Locking & Unlocking using SCIM 1.1 APIs — WSO2 Identity Server

Were you looking for a REST API to lock/unlock user accounts in WSO2 Identity Server? Then you might find this article interesting.

First of all let’s install the latest version of Identity Server. You can download it from here.

Now let’s configure SCIM for account locking in WSO2 Identity Server following the below steps.

Enable account locking in WSO2 IS

First you have to enable account locking feature in WSO2 IS. [1]

1. Log in to the management console.
2. Click on Resident under Identity Providers
3. Expand the section named Login Policies
4. Check the checkbox Account Lock Enabled. Here you can configure other parameters such as account unlock time, no.of failed attempts etc.
5. Then, Click on “List” under claims and then click on “http://wso2.org/claims".
6. Expand the section “Account Locked” and click “Edit”.
7. Check the checkbox named “Supported by Default” and save the changes by clicking “Update” button. Please note that the name of the mapped attribute is “accountLock”.
   After updating, a checkbox will be displayed in the user profile (Users and Roles -> List -> (select user) -> User Profile) named “Account Locked”.

Configuring SCIM for account locking

In order to handle locking accounts through SCIM API, you have to extend the SCIM user schema.
For that, please follow the steps given below. [2]

1. Locate the provisioning-config.xml file in the path {IS-HOME}/repository/conf/identity/provisioning-config.xml
2. Open the file and locate the “user-schema-extension-enabled” property and set it to true.
   <Property name=”user-schema-extension-enabled”>true</Property>
3. Locate the scim-schema-extension.config in the path {IS-HOME}/repository/conf/ and add ‘accountLock’ attribute.
   { “attributeURI”:”urn:scim:schemas:extension:wso2:1.0:wso2Extension.accountLock”, “attributeName”:”accountLock”, “dataType”:”boolean”, “multiValued”:”false”, “multiValuedAttributeChildName”:”null”, “description”:”Account lock”, “schemaURI”:”urn:scim:schemas:extension:wso2:1.0", “readOnly”:”false”, “required”:”false”, “caseExact”:”false”, “subAttributes”:”null”
}
4. Then add “accountLock” attribute as a sub-attribute of wso2Extension element in the bottom of that file.
   “subAttributes”:”employeeNumber costCenter organization division department manager askPassword verifyEmail accountLock”
5. Save the file.

Enabling SCIM Listener

Open <IS_HOME>/repository/conf/identiy/identity.xml file and set enable=true to following listener.

<EventListener type=”org.wso2.carbon.user.core.listener.UserOperationEventListener” name=”org.wso2.carbon.identity.scim.common.listener.SCIMUserOperationListener”
625 orderId=”90" enable=”true”/>

Make sure SCIM2 listener, if available in the identity.xml file is set to false.

<EventListener type=”org.wso2.carbon.user.core.listener.UserOperationEventListener”
628 name=”org.wso2.carbon.identity.scim2.common.listener.SCIMUserOperationListener”
629 orderId=”93" enable=”false”/>

Save the file and restart the server.

Configuring SCIM claim for Account Locking

Then you have to map SCIM accountLock claim to the accountLock attribute in WSO2 dialect. In order to do that,

1. Log into the Management Console.
2. Under Main tab, click Add under Claims.
3. Click Add External Claim.
4. Select urn:scim:schemas:core:1.0 as the Dialect URI, give urn:scim:schemas:extension:wso2:1.0:wso2Extension.accountLock as External Claim URI and select http://wso2.org/claims/identity/accountLocked for *Mapped Local Claim and click Add.

Using SCIM REST API

Now you can check whether a user is locked or not from a SCIM API call. [3]
Eg :

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users?attributes=accountLock

The response for the above request will contain a boolean value for the attribute “accountLock” which shows whether the account is locked or not, as below.

{
 "totalResults":3,
 "schemas":["urn:scim:schemas:core:1.0"],
 "Resources":[
 {"meta":
{"created":"2018-07-24T22:52:58","location":"https://localhost:9443/wso2/scim/Users/admin","lastModified":"2018-07-24T22:52:58"}
,"id":"eef9a4ac-e9ff-4880-8f2a-4e2c1443535b","userName":"admin"},
 {"meta":
{"created":"2018-07-25T01:10:06","location":"https://localhost:9443/wso2/scim/Users/testuser2","lastModified":"2018-07-25T01:10:06"}
,"wso2Extension":
{"accountLock":true}
,"id":"01645c39-b96c-447e-b9a3-45bedcdc1a6c","userName":"testuser2"},
 {"meta":
{"created":"2018-07-25T01:11:02","location":"https://localhost:9443/wso2/scim/Users/testuser3","lastModified":"2018-07-25T01:11:02"}
,"wso2Extension":
{"accountLock":false}
,"id":"c4289553-f565-48de-866a-d30cb12a54c5","userName":"testuser3"
 }]
 }

You can lock/unlock a specific user through SCIM API, by sending a PATCH request as below.
This will update the value of the attribute accountLock.

curl -v -k 
--user admin:admin 
-X PATCH 
-d '{"schemas": ["urn:scim:schemas:core:1.0"],"wso2Extension":{"accountLock":true},"userName": "testuser2","meta": {"attributes": []}}' 
--header "Content-Type:application/json" 
https://localhost:9443/wso2/scim/Users/01645c39-b96c-447e-b9a3-45bedcdc1a6c

In order to send above request, you have to use the URI https://localhost:9443/wso2/scim/Users/<USER_ID>.
You can get the user IDs and other details of the users using the following request.

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users

Enable email sending for account locking/unlocking

You can configure the WSO2 IS to send an email to the user’s email address when the user account is locked/unlocked. To configure this, follow the steps below.

1. Open the output-event-adapters.xml file found in the <IS_HOME>/repository/conf directory.
2. Configure the relevant property values for the email server under the <adapterConfig type=”email”> tag and restart the server.

<adapterConfig type=”email”> 
<! — Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust based authentication rather username/password authentication -->
<property key=”mail.smtp.from”>abcd@gmail.com</property> 
<property key=”mail.smtp.user”>abcd</property> 
<property key=”mail.smtp.password”>xxxx</property> 
<property key=”mail.smtp.host”>smtp.gmail.com</property> 
<property key=”mail.smtp.port”>587</property> 
<property key=”mail.smtp.starttls.enable”>true</property> <property key=”mail.smtp.auth”>true</property> 
<! — Thread Pool Related Properties -->
<property key=”minThread”>8</property> 
<property key=”maxThread”>100</property> 
<property key=”keepAliveTimeInMillis”>20000</property> 
<property key=”jobQueueSize”>10000</property> 
</adapterConfig>

References

[1] https://docs.wso2.com/display/IS541/Locking+a+Specific+User+Account
[2] https://docs.wso2.com/display/IS541/Extensible+SCIM+User+Schemas+With+WSO2+Identity+Server
[3] https://docs.wso2.com/display/IS541/SCIM+1.1+APIs