User Account Locking

The account locking feature in IS allows to prevent users from authenticating using IS. A user account can be locked by one of the following methods.

• Account locking by failed login attempts

• Account locking by an administrative user: An administrative user can lock a user account by using Admin Service or by editing the user profile from the management console.

Account locking by failed login attempts

The Identity Server can be configured to lock user account when a number of consecutive failed login attempts are exceeded. Following section explains on configuring the Identity Server for account locking.

Configuring Identity server for Account Locking

1. Enable the Identity Listener by setting the following property to true in the <IS_HOME>/repository/conf/identity/identity.xml file.

<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener" orderId="50" enable="true"/>

2. Configure the following parameters in the <IS_HOME>/repository/conf/identity/identity-mgt.properties file.

Authentication.Policy.Enable=true
Authentication.Policy.Account.Lock.On.Failure=true
Authentication.Policy.Account.Lock.On.Failure.Max.Attempts=2
Authentication.Policy.Account.Lock.Time=5

Detailed description of the above properties can be found at the end of this page.

Unlocking the locked user account

A locked user account by failed login attempts can be unlocked by one of the following methods

By setting a lock timeout period:

IS can be configured to automatically unlock a user account after a configured amount of time

The above mentioned Authentication.Policy.Account.Lock.Time property is used to set the timeout value. The value is set in minutes. Once the account get locks, it will be automatically unlocked after the time value given to the property. If the Lock Time is set to 0, the account has to be unlocked an admin user. This is explained in the section Account locking by an administrative user.

Account locking by an administrative user

An administrative user can unlock a user account by using Admin Service or by editing the user profile from management console

Locking a user account from management console

An administrative user can lock a user account by editing the user’s profile in the management console. But in order to make the Account Lock status appear in the user’s profile, the Account Locked claim (http://wso2.org/claims/identity/accountLocked) in http://wso2.org/claims claim dialect should be set to “Supported by Default”. Refer Claim Management section for more detailed explanation about claims.

Once the claim configuration is done, go to list users ui and click on “User Profile” of the user you want to lock. If it’s the first time you are locking the user account, there should be a textbox in front of the label ‘Account Locked’ to insert the account lock status. To lock the user account, type true in the textbox and update the user’s  profile.

If it is not the first time you are locking the account, there should be a checkbox instead of a the textbox. Check the checkbox to lock the account or uncheck it to unlock the account and click update.

Locking a user account from the admin service

An administrative user (with the permission level /permission/admin/configure/security/usermgt/users) can lock a user account using UserIdentityManagementAdminService. The admin service provides lockUserAccount operations to achieve this. Following is a sample SOAP request that can be sent to UserIdentityManagementAdminService (https://localhost:9443/services/UserIdentityManagementAdminService) to lock a user account.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ser="http://services.mgt.identity.carbon.wso2.org">
  <soapenv:Header/>
  <soapenv:Body>
  <ser:lockUserAccount>
  <!--Optional:-->
  <ser:userName>SpongeBob</ser:userName>
  </ser:lockUserAccount>
  </soapenv:Body>
</soapenv:Envelope>

Unlocking a user account from the admin service

Similarly, we can use the UserIdentityManagementAdminService to unlock a locked user account. The service provides the unlockUserAccount operation to achieve this. Following is a sample SOAP request that can be sent to UserIdentityManagementAdminService to unlock a user account.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ser="http://services.mgt.identity.carbon.wso2.org">
  <soapenv:Header/>
  <soapenv:Body>
  <ser:unlockUserAccount>
  <!--Optional:-->
  <ser:userName>SpongeBob</ser:userName>
  </ser:unlockUserAccount>
  </soapenv:Body>
</soapenv:Envelope>

The Identity Server can be configured to send an email notification to the user when a user account is unlocked by an admin user. Following are the required configurations.

1. Configure the following parameters in the <IS_HOME>/repository/conf/identity/identity-mgt.properties file.

Notification.Sending.Enable=true
Notification.Expire.Time=7200
Notification.Sending.Internally.Managed=true

Detailed description of the above properties can be found at the end of this page.

2. Navigate to the <IS_HOME>/repository/conf/axis2/axis2.xml file and uncomment the <!--<transportSender name="mailto"

class="org.apache.axis2.transport.mail.MailTransportSender"> XML configuration. You must change the parameter values according to your email settings.

ex:

<transportSender name="mailto"
class="org.apache.axis2.transport.mail.MailTransportSender">
    <parameter name="mail.smtp.from">sampleemail@gmail.com</parameter>
    <parameter name="mail.smtp.user">sampleemail</parameter>
    <parameter name="mail.smtp.password">password</parameter>
    <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
    <parameter name="mail.smtp.port">587</parameter>
    <parameter name="mail.smtp.starttls.enable">true</parameter>
    <parameter name="mail.smtp.auth">true</parameter>
</transportSender>

<configuration type="accountUnLock">
    <targetEpr></targetEpr>
    <subject>WSO2 Carbon - Your account unlocked</subject>
    <body>
        Hi {first-name},
        Please note that the account registered with us with the user name: {user-name} has been unlocked by Admin.
    </body>
    <footer>
        Best Regards,
        WSO2 Identity Server Team
        http://www.wso2.com
    </footer>
    <redirectPath></redirectPath>
</configuration>

4. Restart the server once the configuration changes are made.

By default, IS stores these claim values in the JDBC datasource configured in the identity.xml file. If needed ,you can configure IS to store the claim values in the userstore as well. For that, open the <IS_HOME>/repository/conf/identity/identity-mgt.properties file and change the Identity.Mgt.User.Data.Store property to the datastore you have configured. The default value org.wso2.carbon.identity.mgt.store.JDBCIdentityDataStore is the Identity datasource. Changing the store to UserStoreBasedIdentityDataStore ensures that identity claims are stored in the userstore. The following is the configuration that does this.

Identity.Mgt.User.Data.Store=org.wso2.carbon.identity.mgt.store.UserStoreBasedIdentityDataStore

See the following table for descriptions of the configurations in identity-mgt.properties.