ForgeRock Identity Platform
Does not apply to Identity Cloud

Password reset link is invalid error when resetting password via Self-Service in IDM 6.x

Last updated Jan 12, 2023

The purpose of this article is to provide assistance if a "Password reset link is invalid" error is received when attempting to reset a password in IDM. This issue occurs regardless of whether the password reset process is triggered via the End User UI or the REST API.


When a user triggers the password reset process via the End User UI and then clicks the email verification link in the Password Reset email, they see a "Password reset link is invalid" error in the UI.

If the password reset process is triggered via REST instead, you get the following response:

{"code": 400, "reason": "Bad Request", "message": "Password reset link is invalid"}

The following error is shown in the IDM log (logging level=FINE) when this happens:

FINE: Resource exception intercepted org.forgerock.json.resource.BadRequestException: Password reset link is invalid at org.forgerock.openidm.selfservice.stage.PasswordResetStage.gatherInitialRequirements( at org.forgerock.openidm.selfservice.stage.PasswordResetStage.gatherInitialRequirements( at org.forgerock.selfservice.core.ProgressStageBinder$ProxyProgressStage.gatherInitialRequirements( at org.forgerock.selfservice.core.ProgressStageBinding.gatherInitialRequirements( at org.forgerock.selfservice.core.AnonymousProcessService.handleProgression( at org.forgerock.selfservice.core.AnonymousProcessService.enactContext( at org.forgerock.selfservice.core.AnonymousProcessService.progressProcess( at org.forgerock.selfservice.core.AnonymousProcessService.handleAction( at org.forgerock.openidm.selfservice.impl.SelfServiceProcessHandler.handleAction( at org.forgerock.json.resource.Router.handleAction(

Recent Changes

Enabled the self-service password reset functionality.

Changed the Identity Email Field in the password reset configuration to any attribute other than the default mail attribute.


This issue happens when you use an attribute other than mail for the Identity Email Field. The actual cause behind this differs depending on which version of IDM you are using:

Although you can choose an attribute in the Identity Email Field when you configure the password reset functionality, the password reset process is hard-coded to use the mail attribute. Meaning IDM uses the email address stored in the mail attribute to locate the user. If you specified a different attribute, IDM cannot locate the user when the password reset process is triggered, which results in this error.


This issue can be resolved as follows depending on your IDM version:

  • IDM and later, or IDM Ensure you have configured the password reset functionality correctly to use an alternative attribute as shown in the process below.
  • IDM 6.5, and Pre-IDM Upgrade to IDM and later, or IDM; you can download this from Backstage. Once you have upgraded, you should ensure you have set up your alternative attribute correctly as shown in the process below.

Configuring the password reset functionality to use an alternative attribute

Once you have upgraded if necessary, you can configure the password reset functionality to use an alternative attribute for the Identity Email Field as follows:

  1. Edit the selfservice-reset.json file (located in the /path/to/idm/conf directory) and change mail to the name of your attribute in the following places:
    • validQueryFields (under userQuery):
    • identityEmailField in all stages. Double-check you have updated it for resetStage as this is commonly missed.

The following example shows a replacement attribute called personalEmail in the relevant places:{ "stageConfigs" : [ { "name" : "userQuery", "validQueryFields" : [ "userName", "personalEmail", "givenName", "sn" ], "identityIdField" : "_id", "identityEmailField" : "personalEmail", ... }, ... { "name" : "emailValidation", "identityEmailField" : "personalEmail", ... } { "name" : "resetStage", "identityServiceUrl" : "managed/user", "identityPasswordField" : "password", "identityEmailField" : "personalEmail" } ], ] }

  1. Add the attribute to managed.json (located in the /path/to/idm/conf directory). For example: "personalEmail" : { "title" : "Personal Email", "description" : "Personal Email", "type" : "string", "viewable" : true, "searchable" : true, "userEditable" : true }
  2. This step only applies to IDM 6.5.x. The End User UI contains a hard-code mail attribute, which needs to be changed to match your replacement attribute. Download the latest End User UI, update it to use your attribute and recompile it per the instructions in Identity Management (End User) - UI. The file that needs updating is the UserQuery.vue file (located in the end-user-ui/src/components/selfservice/common directory). Update the query filter to use your attribute instead of mail (this is line 45 in IDM 6.5). For example: getData () { return { queryFilter: `personalEmail eq "${this.mail}"` }; },

See Also

Password Reset Process

User Password Reset

Common Steps: User Self-Registration, Password Reset, Forgotten Username

Related Training


Related Issue Tracker IDs

OPENIDM-12359 (Changing "Identity Email Field" in "User Query Form" from "mail" to another managed object property throws an error)

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