How do I enable account lockout in AM (All versions)?
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:
- AM 7 and later: see Authentication and Single Sign-On Guide › About Account Lockout for Trees for further information on the available nodes.
- AM 6.x: use the Account lockout node with the Retry Limit Decision node. See Authentication and Single Sign-On Guide › Account lockout Node and Retry Limit Decision Node for further information.
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)?
Related Training
N/A
Related Issue Tracker IDs
OPENAM-10393 (Account lockout messages need to be more configurable)