How do I unlock a user's account using the REST API in AM (All versions)?
The purpose of this article is to provide information on using the REST API to unlock user accounts in AM. The REST API can be used to unlock a user's account that has been locked using either persistent (physical) lockout or memory lockout.
2 readers recommend this article
Background information
The way in which a user account can be unlocked using the REST API depends on how it has been locked in the first place. You can lock user accounts using persistent lockout or memory lockout as detailed in How do I enable account lockout in AM (All versions)?
Persistent lockout and Account lockout node
The ability to unlock a user's account that has been persistently locked relies on resetting the inetUserStatus attribute to Active. When a user is persistently locked out, their user status (the inetUserStatus attribute) is changed to Inactive in the user store (both the attribute and status value are configurable).
See the Unlocking a user's account (physical lockout) section for details on unlocking a user's account using the REST API.
Memory lockout
The ability to unlock a user's account that is locked via memory lockout relies on using the Store Invalid Attempts in Data Store option. When the Store Invalid Attempts in Data Store option is enabled, AM stores information about invalid authentication attempts in the user's profile. By default, this information is stored in the sunAMAuthInvalidAttemptsData attribute; however, you can store this information in a different attribute by setting the Invalid Attempts Data Attribute Name field to the required attribute (this must be a valid attribute in the user data store).
The purpose of the Store Invalid Attempts in Data Store option is primarily to allow other AM servers to determine the lockout state across a cluster; however, you can also delete the value of this attribute to manually unlock a user's account. Since memory lockout is being used, the inetUserStatus attribute is not changed and remains set to Active even when the user's account is locked.
In summary, you must set at least the following Account Lockout options to be able to use the REST API to unlock user accounts:
- Login Failure Lockout Mode - enabled.
- Login Failure Lockout Duration - set to a value greater than 0 to enable memory lockout.
- Store Invalid Attempts in Data Store - enabled.
See the Unlocking a user's account (memory lockout) section for details on unlocking a user's account using the REST API.
Note
Please observe the following when constructing REST calls:
- Make the REST call to the actual AM server URL (not lb).
- Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
- Set this session cookie header to the token returned when you authenticated.
- Ensure the Accept-API-Version header contains a valid resource version.
See How do I avoid common issues with REST calls in AM (All versions)? for further information.
Unlocking a user's account (persistent lockout)
The following example assumes you are using the default inetUserStatus attribute; if you have changed it, substitute your attribute for the inetUserStatus attribute in the curl command.
- Authenticate as an admin user. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
- Unlock the user's account (in this example, demo) using the following curl command: $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.0" -d'{ "inetUserStatus": "Active" }' https://am.example.com:8443/am/json/realms/root/users/demoExample response: { "username": "demo", "realm": "/", "uid": [ "demo" ], "universalid": [ "id=demo,ou=user,dc=am,dc=forgerock,dc=org" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn": [ "uid=demo,ou=people,dc=am,dc=forgerock,dc=org" ], "inetUserStatus": [ "Active" ], "sn": [ "demo" ], "cn": [ "demo" ], "iplanet-am-user-auth-config": [ "ldapService" ], "createTimestamp": [ "20160721105610Z" ], "modifyTimestamp": [ "20160727134147Z" ] }
Unlocking a user's account (memory lockout)
The following example assumes you are using the default sunAMAuthInvalidAttemptsData attribute; if you have changed it, substitute your attribute for the sunAMAuthInvalidAttemptsData attribute in the curl command.
- Authenticate as an admin user. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
- Unlock the user's account (in this example, demo) using the following curl command: $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.0" -d'{ "sunAMAuthInvalidAttemptsData": [] }' https://am.example.com:8443/am/json/realms/root/users/demoExample response: { "username": "demo", "realm": "/", "uid": [ "demo" ], "universalid": [ "id=demo,ou=user,dc=am,dc=forgerock,dc=org" ], "objectClass": [ "iplanet-am-managed-person", "inetuser", "sunFederationManagerDataStore", "sunFMSAML2NameIdentifier", "devicePrintProfilesContainer", "inetorgperson", "sunIdentityServerLibertyPPService", "iPlanetPreferences", "pushDeviceProfilesContainer", "iplanet-am-user-service", "forgerock-am-dashboard-service", "organizationalperson", "top", "kbaInfoContainer", "sunAMAuthAccountLockout", "person", "oathDeviceProfilesContainer", "iplanet-am-auth-configuration-service" ], "dn": [ "uid=demo,ou=people,dc=am,dc=forgerock,dc=org" ], "inetUserStatus": [ "Active" ], "sn": [ "demo" ], "cn": [ "demo" ], "iplanet-am-user-auth-config": [ "ldapService" ], "createTimestamp": [ "20160721105610Z" ], "modifyTimestamp": [ "20160727134147Z" ] }
See Also
How do I enable account lockout in AM (All versions)?
Minimum password length is 8 error in AM (All versions) when updating identities using the REST API
Core authentication attributes
Specify realms in REST API calls
Related Training
N/A