Skip to content

Lock accounts by failed OTP attempts

WSO2 Identity Server can be configured to lock a user account when the number of consecutive failed OTP attempts is exceeded.

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.

Note

  • A user account locked by failed login attempts can be unlocked by setting the Account Unlock Time period.
  • If the lock time is set to 0, the account has to be unlocked by an admin user. For more information about this, see Lock and Unlock User Accounts.
  • 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.

Configure the WSO2 IS server

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

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

Enable claims

  1. Navigate to Main > Identity > Claims > Add > Add Local Claim.
  2. Click http://wso2.org/claims.
  3. 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.
  4. 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.

Enable 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 by adding the following configuration to the <IS_HOME>/repository/conf/deployment.toml file.

    Note

    If you haven't changed these configurations previously, you can skip this step since these are the default values.

    [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 (https://<IS_HOST>:<PORT>/carbon) using your tenant credentials.

  3. Click Main > Identity > Identity Providers > Resident.

  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.

  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:

Configuration

Description

Maximum Failed Login Attempts

This indicates the number of consecutive attempts that a user can try to log in without the account getting locked. If the value you specify is 2, the account gets locked if the login attempt fails twice.

Tip

Add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file to configure the Maximum Failed Login Attempts property by default for all the tenants at tenant creation.
[identity_mgt.account_locking]
allowed_failed_attempts=5

Lock Timeout Increment Factor

This indicates how much the account unlock timeout is incremented by after each failed login attempt. For example, according to the values configured in the above screen, when a user exceeds the specified limit of 4 Maximum Failed Login Attempts, the account is locked for 10 minutes. This account unlock timeout is calculated as follows.

Account unlock timeout = Configured Account Unlock Time * (Lock Timeout Increment Factor ^ failed login attempt cycles)

i.e.,10 minutes = 5 * ( 2 ^ 1 )

Tip

Add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file to configure the Lock Timeout Increment Factor property by default for all the tenants at tenant creation.
[identity_mgt.account_locking]
auto_unlock_time_increment_ratio=2

If the user attempts to log in with invalid credentials again after the wait time has elapsed and the account is unlocked, the number of login attempt cycles is now 2 and the wait time is 20 minutes.

Account Unlock Time

The time specified here is in minutes. According to the values in the screenshot above, the account is locked for 5 minutes after the user's second failed attempt and authentication can be attempted once this time has passed.

Tip

Add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file to configure the Account Unlock Time property by default for all the tenants at tenant creation.
[identity_mgt.account_locking]
auto_unlock_after=5

Account Lock Enabled

This enables locking the account when authentication fails.

Tip

Add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file to Enable Account lock on failed login by default for all the tenants at tenant creation.
[identity_mgt.account_locking]
enable_account_locking=true

Configure the email sender

Enable the email sending configurations of the WSO2 Identity Server.

Top