User Account Locking and Account Disabling

Account locking and account disabling are security features in WSO2 Identity Server (IS) that can be applied to prevent users from logging in to their account and from authenticating themselves using their WSO2 IS account. The account locking feature is used to block a user from logging in temporarily, for example, in instances where there have been many consecutive, unsuccessful login attempts. Account disabling is a more of a long term security measure, which disables the account for a significant amount of time.

For more information about configuring user accounts, see the Configuring User Stores topic. A user account can be locked or disabled in one of the following ways:

Account locking by failed login attempts

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

Configuring WSO2 Identity Server for account locking

1. Enable the Identity Listener by setting the <UserOperationEventListener> property with the name "IdentityMgtEventListener" 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.

   Configuration	Description
   Authentication.Policy.Enable=true	This enables the authentication flow level which checks for the account lock and one time password features. This property must be enabled for the account lock feature to work.
   Authentication.Policy.Account.Lock.On.Failure=true	This enables locking the account when authentication fails.
   Authentication.Policy.Account.Lock.On.Failure.Max.Attempts=2	This indicates the number of consecutive attempts that a user can try to log in without the account getting locked. In this case, if the login fails twice, the account is locked.
   Authentication.Policy.Account.Lock.Time=5	The time specified here is in minutes. In this case, the account is locked for five minutes and authentication can be attempted once this time has passed.

   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

Unlocking the locked user account

The WSO2 IS can be configured to automatically unlock a user account after a certain period of time. A user account locked by failed login attempts can be unlocked by setting a lock timeout period. To configure this:

• Configure the Authentication.Policy.Account.Lock.Time property in the  <IS_HOME>/repository/conf/identity/identity-mgt.properties file. As mentioned in the above table, the value refers to the number of minutes that the account is locked for, after which, authentication can be attempted again. 

  Authentication.Policy.Account.Lock.Time=5 

  If the lock time is set to 0, the account has to be unlocked by an admin user. For more information about this, see Account locking by an administrative user.

Account locking by an administrative user

An administrative user can unlock a user account using one of the following methods:

Using the management console

An administrative user can lock a user account by editing the user’s profile in the management console. 

1. Start the WSO2 IS server if you have not already and log in to the management console using admin credentials.
2. Navigate to Claims>List on the Configure menu and select the http://wso2.org/claims  claim dialect. For more information about claims, see Claim Management. 
3. Select the Account Locked claim and click Edit.
   
   
4. Select the "Supported by Default" checkbox and click Update. This is done to make the "Account Locked" status appear in the user's profile. 
5. Navigate to Users and Roles>List>Users on the Main menu and click on User Profile of the user you want to lock. 
6. If it is the first time this particular account is being locked, a textbox will appear in front of the Account Locked field as seen below. To lock the account, type true in the textbox and click Update.
    

Using the AdminService

An administrative user (with the permission level /permission/admin/configure/security/usermgt/users ) can lock a user account using the  UserIdentityManagementAdminService . The admin service provides the lockUserAccount operation to achieve this. The following request is a sample SOAP request that can be sent to the 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>Bob</ser:userName>
  </ser:lockUserAccount>
  </soapenv:Body>
</soapenv:Envelope>

Unlocking a user account from the admin service

Similarly, you can use the UserIdentityManagementAdminService to unlock a locked user account. The service provides the unlockUserAccount operation to achieve this. The following request is a sample SOAP request that can be sent to the 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>Bob</ser:userName>
  </ser:unlockUserAccount>
  </soapenv:Body>
</soapenv:Envelope>

The WSO2 IS can be configured to send an email notification to the user when a user account is unlocked by an admin user. Follow the steps below to configure this. 

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

   Configuration	Description
   Notification.Expire.Time=7200	The time specified here is in minutes. In this case, the notification expires after 7200 minutes.
   Notification.Sending.Internally.Managed=true	This enables the internal email sending module. If this property is set to false, the email sending data is available to the application via a Web service. Thus the application can send the email using its own email sender.
   Notification.Sending.Enable=true	This property enables the email sending function when the password account is unlocked.

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

2. Navigate to the <IS_HOME>/repository/conf/axis2/axis2.xml file and uncomment the following property. Change the parameter values according to your email (see the second code block below for an example of this).  
   

   <!--<transportSender name="mailto"
   class="org.apache.axis2.transport.mail.MailTransportSender">

    
   

   Example

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

3. Make sure the following email template is defined in the <IS_HOME>/repository/conf/email/email-admin-config.xml file. This is the format in which the email is sent to the user when the account is unlocked.
   

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

Storing claims in the user store 

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.

1. 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.

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

   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 user store. 

2. The identity claims mentioned below should be mapped correctly to the attributes in the underlying user store. For more information on how to do this, see  Claim Management. 

• • http://wso2.org/claims/identity/accountLocked - This claim is used to store the status of the user's account, i.e., if it is locked or not.

  • http://wso2.org/claims/identity/unlockTime - This is used to store the timestamp that the user's account is unlocked.

  • http://wso2.org/claims/identity/failedLoginAttempts - This is used to track the number of consecutive failed login attempts. It is based on this that the account is locked.

Account disabling

An administrative user can disable a user account by configuring this feature in the WSO2 Identity Server and editing the user profile of the account. The following section provides instructions on how to configure the WSO2 IS for account disabling and disable the user account. 

1. Enable the Identity Listener by setting the <EventListener> 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 property in the <IS_HOME>/repository/conf/identity/identity-mgt.properties file.

   Authentication.Policy.Enable=true 

   Note: The WSO2 IS can be configured to send an email notification to the user when a user account is enabled or disabled by an admin user. Do the following to configure this:

   • To enable the notification sending functionality when enabling user accounts, set the following property to true in the identity-mgt.properties file.

     Notification.Sending.Enable.Account.Enable=true

   • To enable the notification sending functionality when disabling user accounts, set the following property to true in the identity-mgt.properties file.

     Notification.Sending.Enable.Account.Disable=true

3. Restart the IS server to make the changes effective. 
4. Open the management console and navigate to Main>Claims>List. 
5. Click on 'http://wso2.org/claims' and edit the Account Disabled claim. See Editing Claim Mapping for more information on how to do this. 
6. Tick the checkbox Supported by Default and click Update.
   
7. Navigate to Main>Users and Roles>List>Users and click on User Profile of the user account that you want to disable. 
8. Tick the Account Disabled checkbox and click Update.