Account Locking by Failed Login Attempts¶

WSO2 Identity Server can be configured to lock a user account when a number of consecutive failed login attempts are exceeded. First, you need to configure WSO2 Identity Server for user account locking and disabling. The following section explain how to configure this.

Configuring WSO2 IS for account locking¶

1. Ensure that the identity listener with the priority=50 is set to false and the identity listener with the priority=95 is set to true in the <IS_HOME>/repository/conf/deployment.toml file by adding the following configuration.

   Info

   This is already configured this way by default. You can skip this step if you have not changed this configuration previously.

   Click to see the code block

   [event.default_listener.identity_mgt]
   priority= "50"
   enable = false
   [event.default_listener.governance_identity_mgt]
   priority= "95"
   enable = true

2. Start the Identity Server and log into the management console using your tenant credentials.

   Tip

   Alternatively, you can also use the IdentityGovernanceAdminService SOAP service to do this instead of using the management console UI. See Calling Admin Services for more information on how to invoke this SOAP service. If you are using the SOAP service to configure this, you do not need to follow the steps given below this note.

3. Click Resident under Identity Providers found in the Main tab.

4. Expand the Login Attempts Security tab.

5. Expand the Account Lock tab and select the Lock user accounts checkbox. Click Update to save changes.
   

   Tip

   If a user is assigned the Internal/system role, the user can bypass account locking even if the user exceeds the specified number of Maximum Failed Login Attempts.

   Note

   WSO2 Identity Server has the Internal/system role configured by default. But generally a new user is not assigned the Internal/system role by default. Required roles can be assigned to a user depending on the set of permission a user needs to have. For more information on roles and permission, see Configuring Roles and Permissions.

   Although the Internal/system role is configured by default in WSO2 Identity Server, you can delete the role if necessary. To allow users with the Internal/system role to bypass account locking, you need to ensure that the role exists in WSO2 Identity Server.

6. To enable account locking for other tenants, log out and repeat the steps given above from step 2 onwards.

The following table describes the configuration properties and descriptions you need to configure:

[identity_mgt.account_locking]
allowed_failed_attempts=5

[identity_mgt.account_locking]
auto_unlock_time_increment_ratio=2

[identity_mgt.account_locking]
auto_unlock_after=5

[identity_mgt.account_locking]
enable_account_locking=true

If you want to configure different settings for another tenant, log out and follow the same steps to configure these properties for the other tenants.

Sending email notifications for account locking¶

Once you have configured WSO2 Identity Server for account locking by failed login attempts, you can also configure the WSO2 IS to send an email to the user's email address when the user account is locked due to failed login attempts. To configure this, follow the steps below.

• Enable the email sending configurations of the WSO2 Identity Server as explained here.

  Tip

  The email template used to send the email notification for account locking is the AccountLock template and the template used for account disabling is the AccountDisable template. You can edit and customize the email template. For more information on how to do this, see Customizing Automated Emails.

WSO2 Identity Server uses separate email templates for notifying,

• Account locking by exceeding Maximum Failed Login Attempts
• Account unlocking by exceeding Account Unlock Time

Add the following email templates by referring to the instructions in Customizing AutomatedEmails.

Following are the sample email templates.

Configuring WSO2 IS for Failed OTP attempts based account locking¶

WSO2 Identity Server can be configured to lock a user account when the number of consecutive failed OTP attempts is exceeded. First, you need to configure the WSO2 Identity Server for user account locking and disabling according to Configuring WSO2 IS for account locking.

1. Add the following configurations into <IS_HOME>/repository/conf/deployment.toml file to enable account locking for each type of OTP attempts.

   • For Email OTP:

     [authentication.authenticator.email_otp.parameters]
     EnableAccountLockingForFailedAttempts = true

   • For SMS OTP:

     [authentication.authenticator.sms_otp.parameters]
     EnableAccountLockingForFailedAttempts = true

     Note

     Since BackupCode = true in the default configuration, configure the backup code claim according to Configuring Backup Codes for SMSOTP. Alternatively, you can disable the backup codes for SMS OTP by setting the property to false.

     [authentication.authenticator.sms_otp.parameters]
     BackupCode = false

   • For TOTP:

     [authentication.authenticator.totp.parameters]
     EnableAccountLockingForFailedAttempts = true

2. Navigate to Main > Identity > Claims > Add > Add Local Claim.

3. Click http://wso2.org/claims.

4. Once the user account gets locked, the Account Locked attribute will be updated to true. To check this via the user profile:

   1. Click Edit under the Account Locked claim.
   2. Select Supported by Default and click Update.
   3. Navigate to the relevant user's user profile and you will see that the attribute has been updated.

5. Failed Email OTP Attempts, Failed SMS Attempts, and Failed TOTP Attempts attribute values will be incremented for the wrong attempt of Email OTP, SMS OTP, and TOTP attempt respectively. To check this via the user profile.

   • For Email OTP:

     1. Click Edit under the Failed Email OTP Attempts claim.
     2. Select Supported by Default and click Update.
     3. Navigate to the relevant user's user profile and you will see that the attribute has been updated.

   • For SMS OTP:

     1. Click Edit under the Failed SMS Attempts claim.
     2. Select Supported by Default and click Update.
     3. Navigate to the relevant user's user profile and you will see that the attribute has been updated.

   • For TOTP:

     1. Click Edit under the Failed TOTP Attempts claim.
     2. Select Supported by Default and click Update.
     3. Navigate to the relevant user's user profile and you will see that the attribute has been updated.