How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I enable account lockout in AM (All versions)?

Last updated Apr 13, 2021

The purpose of this article is to provide information on enabling account lockout in AM and conversely, unlocking the user's account. It also discusses the different types of account lockout.


2 readers recommend this article

Overview

The following types of account lockout are available, which determine how user accounts are locked and unlocked:

  • Persistent (physical) lockout
  • Memory lockout (AM 7 and later: applicable to authentication trees and chains; pre-AM 7: only applicable to authentication chains)
  • Directory server-based account lockout
Note

Please be aware of the following:

  • If you are using account lockout across different realms that use the same user store and the realms are used interchangeably to authenticate the same users, you must either:
    • Avoid mixing Persistent and Memory lockout modes by having the same account lockout configuration in all realms.
    • Use a different Invalid Attempts Data Attribute Name in each realm to ensure each realm has its own attribute to track invalid login attempts.
  • It is not possible to have both the user status updated (persistent lockout) and the user account automatically unlocked (memory lockout) using the account lockout functionality in AM.

Persistent lockout

Persistent lockout is the default account lockout type. When a user is locked out with persistent lockout, their user status (the inetUserStatus attribute) is changed to Inactive in the user store (both the attribute and status value are configurable). The user is not unlocked automatically; the amAdmin user must unlock them using the REST API (see How do I unlock a user's account using the REST API in AM (All versions)?) or the console:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > [User Name] > User Status and select Active.
  • Pre-AM 6 console: navigate to: Realms > [Realm Name] > Subjects > User > [User Name] > User Status and select the Active option.

See the Enabling account lockout section for further information on configuring this account lockout behavior.

Memory lockout

Memory lockout locks the user account for a specified duration and does not change the user's status (the inetUserStatus attribute) in the user store. A user's account is automatically unlocked after the specified number of minutes. Additionally, the amAdmin user can unlock a user account using the REST API (see How do I unlock a user's account using the REST API in AM (All versions)?) or by disabling the memory account lockout behavior, but this unlocks all users locked in memory. Similarly, if AM is restarted, all users locked via memory lockout are unlocked.

Memory lockout can be used with authentication trees and chains in AM 7 and later, but only with authentication chains in pre-AM 7.

See the Enabling account lockout section for further information on configuring this account lockout behavior.

Directory server-based account lockout

If you use DS as your user store, you should refer to: Maintenance Guide › Account Lockout for further information on configuring account lockout.

Additionally, if you want DS to warn users of impending lockouts, you must enable the LDAP Behera Password Policy Support option in the LDAP Decision node or LDAP authentication module depending on whether you use trees or chains for authentication.

Authentication trees

If you use authentication trees, there are nodes for checking the status of a user and changing their status:

Note

If you have specified multiple attributes for Attributes Used to Search for a User to be Authenticated in the LDAP decision node, you must also add those attributes to the realm level Alias Search Attribute Name for account lockout to work. See Authentication and Single Sign-On Guide › Core Authentication Attributes (User Profile) for further information on this setting.

Enabling account lockout

You can enable account lockout and define the attributes that will result in account lockout (such as number of failed login attempts) at the global or realm level (navigation details and ssoadm commands given below).

The following table indicates which attributes must, or can, be set according to the account lockout type:

Attributes Persistent lockout Memory lockout
Login Failure Lockout Mode Must be set to enable account lockout. Must be set to enable account lockout.
Login Failure Lockout Count Optional. Optional.
Login Failure Lockout Interval Optional. Optional.
Email Address to Send Lockout Notification Optional. Optional.
Warn User After N Failures Optional. Optional.
Login Failure Lockout Duration N/A Must be set to a value greater than 0 to enable memory lockout. Setting this back to 0 disables memory lockout and re-enables persistent lockout. 
Lockout Duration Multiplier N/A Optional.
Lockout Attribute Name Optional. N/A
Lockout Attribute Value Optional. N/A
Invalid Attempts Data Attribute Name Optional. Optional.
Store Invalid Attempts in Data Store Optional. Optional.

See Security Guide › Configuring Account Lockout for further information on the available configuration attributes and the equivalent ssoadm attribute names.

Global level

You can configure account lockout at the global level using either the console or ssoadm:

  • Console: navigate to: Configure > Authentication > Core Attributes > Account Lockout and set the relevant fields.
  • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-login-failure-lockout-mode=true [attributes]replacing [adminID], [passwordfile] and [attributes] with appropriate values. You can specify multiple attribute names and values by using a space between them as a separator.

An example ssoadm command to set three account lockout attributes at the global level looks like this:

  • AM 7 and later: $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10
  • Pre-AM 7: $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u amadmin -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10

Realm level 

You can configure account lockout at the realm level using either the console or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Authentication > Settings > Account Lockout and set the relevant fields.
  • ssoadm: enter the following command: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-login-failure-lockout-mode=true [attributes]replacing [realmname], [adminID], [passwordfile] and [attributes] with appropriate values. You can specify multiple attribute names and values by using a space between them as a separator.

An example ssoadm command to set three account lockout attributes at the realm level looks like this:

  • AM 7 and later: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e employees -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10
  • Pre-AM 7: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e employees -u amadmin -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10

Checking persistent account lockout status

You can check the persistent account lockout status of a user by querying the inetUserStatus attribute using the ldapsearch command, for example:

  • DS 7 and later: $ ./ldapsearch --port 50389 --bindDN uid=admin --bindPassword password --baseDN "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" "objectclass=*"
  • Pre-DS 7: $ ./ldapsearch --port 50389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" "objectclass=*"

Example response, which shows the status of the inetUserStatus attribute:

dn: uid=demo,ou=people,dc=openam,dc=forgerock,dc=org objectClass: person objectClass: inetorgperson objectClass: sunFederationManagerDataStore objectClass: iplanet-am-auth-configuration-service objectClass: kbaInfoContainer objectClass: organizationalperson objectClass: sunIdentityServerLibertyPPService objectClass: inetuser objectClass: sunAMAuthAccountLockout objectClass: iPlanetPreferences objectClass: devicePrintProfilesContainer objectClass: forgerock-am-dashboard-service objectClass: sunFMSAML2NameIdentifier objectClass: iplanet-am-managed-person objectClass: iplanet-am-user-service objectClass: top objectClass: oathDeviceProfilesContainer uid: demo mail: demo@test.com sn: demo userPassword: {SSHA}Os1Rlw0qGB+hrhRCQDBna+NlKQ+/BDNUoMYVlg== cn: demo givenName: demo kbaInfo: { "answer": { "$crypto": { "value": { "algorithm": "SHA-256", "data": " JDz7McsAgRJkeMpCdPp3D702kA7GTPFRkjhd2qys+DJXmluzcVwaT0CXCrQtn0mf" }, "type": "s  alted-hash" } }, "questionId": "2" } inetUserStatus: Inactive sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjA8L0lud  mFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWRvdXRBdD4wPC9M  b2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2tvdXREdXJhdGlvbj4  8L0ludmFsaWRQYXNzd29yZD4=

See Also

How do I unlock a user's account using the REST API in AM (All versions)?

How do I lock a user's account if they do not authenticate to AM (All versions) within a specific period of time?

Administrator and user accounts in AM

Security Guide › Configuring Account Lockout

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10393 (Account lockout messages need to be more configurable)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.