AM 7.3.1

Account lockout

Account lockout is a security mechanism that locks a user account after repeated failed login attempts. It is used to slow down brute-force attacks, and to compensate for weak password policies.

Most deployments use the identity store’s password policy to control account lockout. If this is not an option in your deployment, configure account lockout, as explained in this section.

You can configure account lockout in one of the following ways:

Persistent lockout

Persistent (physical) lockout locks the user’s account indefinitely, until unlocked by an administrator. This is the default type of account lockout.

For persistent lockout, AM sets the user account status to inactive in the user profile, and tracks failed authentication attempts by writing to the user repository.

Persistent lockout works independently of account lockout mechanisms in the underlying directory server that serves as the user data store.

Duration lockout

Duration lockout locks the user account for a specified duration, keeping track of the locked state either in memory or in the data store. Duration lockout is released when AM restarts.

Unlike persistent lockout, the user account status remains active for duration lockout.

The default configuration is to record invalid authentication attempts in the data store. This avoids the need for sticky load balancing. If you choose to store the count of invalid attempts in memory, the counter applies to the current AM instance only.

Failed login attempts during the transactional authorization flow do not increment account lockout counters.

If login failures are stored in AM’s memory, this may result in user accounts not being locked out, even after multiple login failures. To avoid this issue, rather implement persistent lockout.

Configure account lockout

  1. Configure account lockout:

    • In the AM admin UI, go to Realms > Realm Name > Authentication > Settings > Account Lockout.

    • Enable lockout by checking Login Failure Lockout Mode, then set the number of attempts and the lockout interval.

      You can also opt to warn users after several consecutive failures.

    • To save account login failures to the data store, enable Store Invalid Attempts in Data Store. This setting is necessary when using server-side or client-side authentication sessions. If you do not set this, users might not be locked out, even after multiple login failures.

      When you store the count of failed attempts in the data store, other AM servers accessing the user data store can also see that count.

    • If AM is configured to send mail, you can set up email notification of lockouts to an administrator. To configure AM to send mail, go to Configure > Server Defaults > General > Mail Server.

  2. Configure persistent lockout:

    • For persistent lockout, AM sets the value of the user’s inetuserstatus profile attribute to inactive. You can specify an additional attribute to update on lockout.

    • You can also define a custom attribute to store the number of failed authentication attempts.

  3. Configure duration lockout:

    • Set the lockout duration to a positive value to enable duration lockout. Optionally, configure a multipier to increase the lockout duration on each successive lockout.

    • Enable the Store Invalid Attempts in Data Store property so that lockout attempts are not stored in memory, but persisted in the repository, and applied across all AM instances.

    • Set Invalid Attempts Data Attribute Name to the default attribute sunAMAuthInvalidAttemptsData to prevent invalid attempts from being stored only in memory.

    For more information, refer to Realm authentication configuration.

To unlock a user’s account:

  • Locate the user under Realms > Realm Name > Identities.

  • Choose the user you want to unlock.

  • Set their User Status property to Active.

  • Click Save.

For specific information on how authentication trees handle account lockout, refer to Account lockout for trees.

Customize account lockout messages

To customize the messages shown to end users when their accounts are locked, follow these steps:

  1. Locate the openam-core-7.3.0.jar file in the WEB-INF/lib/ folder where AM is deployed.

  2. Extract the amAuth.properties file.

  3. Change the value of the field that controls the lockout message:

    1. If you are using an authentication tree, change the value of the lockOut field, for example:

      lockOut=Your example.com account has been locked. Please contact your support agent.|user_inactive.jsp

    2. If you are using an authentication chain, change the value of the 112 field, for example:

      112=Your example.com account has been locked. Please contact your support agent.|user_inactive.jsp

  4. Copy the amended amAuth.properties file to the WEB-INF/classes/ folder where AM is deployed.

  5. When a user whose account is locked attempts to authenticate, the custom lockout message is displayed:

    Custom account lockout message
Copyright © 2010-2024 ForgeRock, all rights reserved.