How To
Archived

How do I initiate the password reset functionality in IDM 5.x and OpenIDM 4.x via the REST API?

Last updated Apr 7, 2021

The purpose of this article is to provide information on initiating the password reset functionality in IDM/OpenIDM via the REST API. This article also includes the REST calls needed to reset the password if you do not want to use the UI to reset the password.


3 readers recommend this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Overview

To initiate the password reset functionality via the REST API, you can send a POST request to the selfservice/reset endpoint and provide a queryFilter as input to locate the managed user within the repository. The parameters required in the body of the request are specific to your setup.

You can initiate a password reset as follows:

Initiating the password reset functionality

You can determine what parameters are required using your browser's developer tools:

  1. Access the IDM/OpenIDM Self-Service login page using your browser.
  2. Launch the Developer tools for your browser.
  3. Select the Network tab to trace communications between the browser and server.
  4. Walk through the Password Reset functionality in the browser; the Network trace will show exactly which request the UI is sending to the server, what HTTP Headers are being supplied and the content of the request body.

Refer to Integrator's Guide › Constructing Queries for further information on how the queryFilter should be constructed in your curl command.

Curl commands for the following examples are provided below:

  • Example 1 - Initiating the password reset process via REST. This relies on the user receiving an email and then resetting their password via the UI.
  • Example 2 - Performing the entire password reset process via REST.

One stage process

The following examples demonstrate password reset as a two stage process. However, you may want it to be a one stage process, for example, if you are doing provisioning with the workflow sample and want password reset triggered with a single call. 

To make password reset a one stage process, you can remove the following stage from the selfservice-reset.json file:

 {             "name": "parameters",             "parameterNames": [                 "returnParams"             ]         },

This stage is automatically added when you change the password reset configuration via the Admin UI, so will need to be removed every time you make changes. Alternatively, you can create a custom selfservice-[something].json file for the password reset process which wouldn't be altered by Admin UI changes.

Example 1 - Initiating the password reset process via REST

The following example demonstrates initiating a password reset where the Password Reset functionality has been configured to send an email to the user for verification:

  1. Use a curl command such as the following with an empty payload to return a JWT token: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -d '{"input":{}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response: { "type": "userQuery", "tag": "initial", "requirements": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Find your account", "type": "object", "required": [ "queryFilter" ], "properties": { "queryFilter": { "description": "filter string to find account", "type": "string" } } }, "token": "eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVY...W5ywOcr8" }
  2. Use a curl command such as the following to initiate the reset process, making sure to include the JWT token returned in the previous step and the appropriate queryFilter; this example is looking for a managed user who has the username jdoe: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -H "Accept-Language:en-US,en;q=0.8" -d '{"token": "eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVY...W5ywOcr8","input":{"queryFilter":"userName eq \"jdoe\""}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response; an email will be sent to jdoe for verification: { "type": "emailValidation", "tag": "validateCode", "requirements": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Verify emailed code", "type": "object", "required": [ "code" ], "properties": { "code": { "description": "Enter code emailed", "type": "string" } } }, "token": "eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0....U0djycrxM5WFGEc" }

Example 2 - Performing the entire password reset process via REST

The following example demonstrates performing the entire password reset process via REST:

  1. Use a curl command such as the following with an empty payload to return a JWT token: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -d '{"input":{}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response: { "type": "userQuery", "tag": "initial", "requirements": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Find your account", "type": "object", "required": [ "queryFilter" ], "properties": { "queryFilter": { "description": "filter string to find account", "type": "string" } } }, "token": "eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVY...W5ywOcr8" }
  2. Use a curl command such as the following to obtain the reset token, making sure to include the JWT token returned in the previous step and the appropriate queryFilter; this example is looking for a managed user who has the username jdoe: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -H "Accept-Language:en-US,en;q=0.8" -d '{"token": "eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVY...W5ywOcr8","input":{"queryFilter":"userName eq \"jdoe\""}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response: { "type": "kbaSecurityAnswerVerificationStage", "tag": "initial", "requirements": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Answer security questions", "type": "object", "required": [ "answer1" ], "properties": { "answer1": { "systemQuestion": { "en": "What's your favorite color?" }, "type": "string" } } }, "token": "eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0....U0djycrxM5WFGEc" }
  3. Use a curl command such as the following to submit your answers to the security questions detailed in the above response along with the returned token: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -H "Accept-Language:en-US,en;q=0.8" -d '{"token":"eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0....U0djycrxM5WFGEc","input":{"answer1":"Blue"}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response: { "type": "resetStage", "tag": "initial", "requirements": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Reset password", "type": "object", "required": [ "password" ], "properties": { "password": { "description": "Password", "type": "string" } } }, "token": "eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0....U0djycrxM5WFGEc" }
  4. Use a curl command such as the following to provide your new password; this uses the token returned in step 1: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: anonymous" -H "X-OpenIDM-Password: anonymous" -H "Accept-Language:en-US,en;q=0.8" -d '{"token":"eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0....U0djycrxM5WFGEc","input":{"password":"newPassw0rd"}}' "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements" Example response: { "type": "resetStage", "tag": "end", "status": { "success": true }, "additions": {} }
Note

If email validation has been configured in this scenario, you will need to execute an additional REST call between steps 1 and 2 to submit the code from the validation email. This call will use the same format as the examples in steps 2 and 3, where the input value is in the format: {"code":"02a5c58a-5f20-45e1-9cf9-cad0d0b78cba"}.

See Also

Self-Service REST API Reference › REST Requests in a Password Reset Process

Integrator's Guide › Customizing the End User UI

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-7108 (Password Reset Token issued by one process cannot be validated by a different process)


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