How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Mar 30, 2021

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.

  1. 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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  2. 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" }' http://host1.example.com:8080/openam/json/realms/root/users/demoExample response: {  "username": "demo",   "realm": "/",   "uid": [     "demo"   ],   "universalid": [     "id=demo,ou=user,dc=openam,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=openam,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. 

  1. 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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  2. 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": [] }' http://host1.example.com:8080/openam/json/realms/root/users/demoExample response: {  "username": "demo",   "realm": "/",   "uid": [     "demo"   ],   "universalid": [     "id=demo,ou=user,dc=openam,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=openam,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

Authentication and Single Sign-On Guide › Core Authentication Attributes

Authentication and Single Sign-On Guide › Account lockout Node

Getting Started with REST › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


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