Unlock user account using OpenAM Forgot Password flow

OpenAM provides “Account Lockout” functionality which can be used to configure various lockout parameters such as failure count, lockout interval etc.

Note that OpenDJ also provides Account Lockout functionality, this article is based on OpenAM Account Lockout policies. Refer this KB article for more differences between OpenAM and OpenDJ lockout polices.

Using OpenAM “Account Lockout” policies, users may get locked out with invalid login attempts. OpenAM offers both Memory and Physical lockouts. Using memory lockout, users get unlocked automatically after specified duration.

Many deployments use “Physical lockout” due to security requirements. When this lockout mode is used then there should be some Self-service flow so that user can unlock themselves. Why not use OpenAM forgot password self-service flow ?

OpenAM forgot password allows user to reset password after successfully completing various stages (such as KBA, email confirmation, reCaptcha etc). Unfortunately, the problem is that the account is not unlocked when this flow is used. There is already an open RFE for this issue.


Versions used for this implementation: OpenAM 13.5, OpenDJ 3.5
One of the solution can include extending out of the box OpenAM’s forgot password self-service flow by adding custom stage to unlock user’s account:
  • Implement ForgottenPasswordConfigProviderExt to include account unlock stage.
  • Implement unlock custom stage
  • Extend selfServiceExt.xml to include custom provider.


  • Build the custom stage by using maven.
  • Delete all instances of User Self-Service from all realms.
  • Remove existing selfService
./ssoadm delete-svc --adminid amadmin --password-file /tmp/pwd.txt -s selfService
  • Restart OpenAM
  • Register custom selfService
  • Restart OpenAM
./ssoadm create-svc --adminid amadmin --password-file /tmp/pwd.txt --xmlfile ~/softwares/selfServiceExt.xml
  • Add User Self-Service to specified realm and enable forgot password flow.


  1. Lock user by authenticating using wrong password till user is locked out.
  2. Follow forgot password flow to reset password and unlock account.
  3. Try authenticating again with new password. This should succeed.

This blog post was first published @ theinfinitelooper.blogspot.com, included here with permission.

OpenIDM Forgot Password: Randomly select security questions

Configuration Changes

This note describes the customizations necessary to use 2 or more security questions for the following OpenIDM features: user self-registration, change security data and forgot password. Please note that this article was originally written for v3.0.

Common Configurations


Add the new user profile attributes under allowed properties.


Add policies to the newly added security question and answer attributes.


Include the security answer as a managed object.


Return a comma separated list of values in the endpoint that is called before security questions are to be shown to the user:


Ensure the new security question gets aggregated as shown here:

Self Registration

HTML Template Changes


Edit the template to include another security question as shown here:


If you want questions pre-selected when viewing the registration page, add this script to the page:

setTimeout(function () {
document.getElementById("securityQuestion").selectedIndex = 1;
document.getElementById("securityQuestion2").selectedIndex = 2;
}, 200);

JavaScript Changes


Here we setup the registration code such that it allows the user to setup 2 security questions at the time of self-registration.

Change Security Data

HTML Template Changes


Change the template to include the option of setting up 2 security questions instead of a default of one OpenIDM ships with:

JavaScript Changes


In the javascript, we need to ensure that whenever the user wants to change their security questions, the previously configured ones show up as selected:

Note that this demo does not attempt to manage the UI display order of the previous security questions.

Forgot Password

This code change in UserDelegate.js enables randomly showing any of the 2 configured security questions.



When a user has forgotten their password, they need to click on the Forgot Password link. The security question presented to them is randomly selected from the 2 configured list of questions.

User Interface Views

Self Registration

Change Security Data

Forgot Password



The following REST calls are made to manage a user’s password reset.

List of Questions

The list of security questions can be received via this API call:

GET http://openidm-server:port/openidm/config/ui/secquestions

User Defined Security Question(s)

This pulls up the security question(s) defined for the user indicated by user-name:

POST http://openidm-server:port/openidm/endpoint/securityQA?_action=securityQuestionForUserName&uid=user-name

Submit Security Response

A security response can be submitted to OpenIDM via:

POST http://openidm-server:port/openidm/endpoint/securityQA?_action=checkSecurityAnswerForUserName&uid=user-name&securityAnswer=<user-response>

Reset User Password

Once the user has entered the correct security response, you may change the password via this API call:

POST http://openidm-server:port/openidm/endpoint/securityQA?_action=setNewPasswordForUserName&newPassword=new-password&uid=user-name&securityAnswer=<response>