Account Locking Based on OTP Failed Attempts

Try WSO2 Identity Server (IS) capability to lock user accounts based on SMS/Email OTP and TOTP failed attempts

Anuradha Karunarathna
7 min readMar 12, 2021


If the user makes multiple failed OTP verification attempts, the user account gets locked


I’m sure all of you may know password brute force attacks. It’s nothing but guessing the password of a user account systematically trying out every possible combination of allowed characters(letters, numbers, symbols, etc). In order to mitigate this attack Identity and Access Management solutions provide multiple options. Some of them are as follows.

  1. Strong Password Policies

By enforcing strong password policies in terms of allowed length and allowed characters, the users are forced to set a strong password for their accounts. Therefore, password guessing is not an easy task. There could be millions, billions, or even trillion possibilities based on password length and complexity. However, this solution is good in terms of user experience because remembering a long, complex password feels like a curse for a human being.

2. Account Locking

This means locking out the user account after a defined number of failed password attempts. An account lockout could remain

  • for a specified period of time
  • until the next successful attempt after a specified time
  • until manual unlock by system admin.

Even account lockout can’t mitigate the password brute-force attack fully, because if an attacker reveals multiple accounts’ passwords, the attacker can cause a denial of service (DoS) by locking out large numbers of accounts.

3. Multi-Factor Authentication(MFA)

With multi-factor authentication, the password brute force attack can be mitigated up to a certain level because just revealing the password doesn't allow the attacker to log in to the user account. If MFA is enabled there is one or more other security verification step that belongs to something you know (like a password/ pin), something you have (OTPs received to mobile/ email), or something you are (fingerprint, face/retina recognition). The hassle of going through multiple authentication steps in every login attempt due to MFA has been addressed by adaptive authentication.

4. Adaptive Authentication

Obviously, adaptive authentication is a precaution for password brute-force attack as well as a handy solution for the user experience issue in MFA. Adaptive authentication is a thread off to usability and security. If your application enables adaptive authentication, authentication steps get change based on the user’s risk profile, geolocation, login device type, or any other conditional factor.

WSO2 Identity Server which is a leading open-source IAM solution has all the above-discussed options. Not only that !! It has another amazing feature. Let’s see what it is!

Account Locking Based on OTP Failed Attempts

The user can access the application after one successful OTP attempt, even after multiple wrong attempts in the OTP verification step

Let’s think about an application that enables two-factor authentication.

  • The first factor is basic authentication (username and password)
  • The second factor is SMS OTP

The user gets succeeded in the first step by providing the correct username and password. Then he/she receives an SMS OTP to his/her mobile phone. When typing the OTP he/she does a mistake and the authentication step gets failed.

What will be the next step ??

  • Will the user redirect again to the first-factor authentication?
  • Will the user get another attempt to try SMS OTP?

Normally it is the second option to ensure a better user experience. The user will be prompted to re-enter the SMS OTP. As the above image illustrates, the user can be successful in the login attempt even after multiple wrong attempts in the OTP verification.

❓The problem is…….

If the user can do that, why not an attacker?? If the user account’s username and password are revealed there is a vulnerability to succeed in the next step after multiple wrong attempts, but the chance is very low. The chance is low because, as the initial step the attacker needs to reveal the username and password, then guess the OTP. Since the OTP is changing every time he tries after the OTP expiration or starts from the beginning of the authentication process. So, it has a low probability of passing both steps.

Let’s see the solutions for this problem:

  • Send a new OTP if an attempt goes wrong — It is a costly option. Need to send newly generated code via SMS/email. Also, this is not valid for TOTP as it is generated based on time.
  • Make shorter expiry time for OTPs — Then OTP is valid for a short period of time. That might harm the user experience.
  • Lockout the account after a specified number of wrong attempts — Similar to locking out the user account after a defined number of failed password attempts, we can lock out the account after a defined number of wrong OTP verification attempts.
  • Adaptive authentication — Already discussed in the above section.

Out of the above four options, we are going to see the “Lockout the account after a specified number of wrong attempts” option.

How does it work in WSO2 IS?

Try Out

Let’s try out the scenario by configuring SMS OTP as the second-factor authentication step in WSO2 IS 5.11.0 (NOTE: This supports for Email OTP and TOTP too. Check the configs here). You have to get the WUM updated pack of previous versions to support this feature.

  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.
priority= "50"
enable = false
priority= "95"
enable = true

2. Enable account locking based on SMS OTP.

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

(If you specify “BackupCode = false” follow the instructions to add the backup code claim.)

3. Start the server.

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

5. Expand the Login Attempts Security tab.

6. Expand the Account Lock tab and select the Lock user accounts checkbox.

7. Change Maximum Failed Login Attempts if allow more than or less than failed attempts than 5.

8. Click Update to save changes.

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

10. Click

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

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

12. Failed SMS Attempts attribute values will be incremented for every wrong attempt of SMS OTP and reset to zero when the account gets locked when the maximum count is exceeded. To check this via the user profile.

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

13. Follow this guide to configure SMS OTP for an application.

14. Then try to login into the application. Make the basic authentication is a success and make incorrect attempts in SMS OTP. Same time check the user profile. You can see that Failed SMS Attempts value increases per each attempt.

  • If you make a successful SMS OTP attempt, Failed SMS Attempts will be reset to 0.
  • If you exceed the incorrect SMS OTP attempts than the configured number in Maximum Failed Login Attempt, Failed SMS Attempts will be reset to 0, and Account Locked will be set to true.
  • The following error message will be shown to the user when the account gets locked.

If showAuthFailureReason = true is configured under “[authentication.authenticator.sms_otp.parameters]”, the user will be prompted a detailed error when the account gets locked. Otherwise, this general message will be displayed.

We are done! It’s your time. Try and See.




Anuradha Karunarathna

Associate Technical Lead @ WSO2 | Computer Science and Engineering graduate@ University of Moratuwa, SriLanka