IDM 7.3.0

Password reset REST requests

The following REST requests and responses demonstrate the flow through a simple password reset process. To keep the process simple, this flow does not include the Google ReCAPTCHA stage, or the Security Answer Verification stage:

  1. Client initiates the password reset,

    The server returns the initial tag:

    curl \
    --request GET \
    "https://localhost:8443/openidm/selfservice/reset"
    {
      "type": "parameters",
      "tag": "initial",
      "requirements": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Parameters",
        "type": "object",
        "properties": {
          "returnParams": {
            "description": "Parameter named 'returnParams'",
            "type": "string"
          }
        }
      }
    }
  2. Initial requirements submission with an empty payload.

    The server returns requirements for the userQuery stage, and the JWT:

    curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "input":{}
    }' \
    "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements"
    {
      "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": "eyJ0e…​FYkE"
    }
  3. The client provides the requirements for the userQuery stage, along with the JWT. The process progresses to the emailValidation stage:

    curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "token": "eyJ0e…​FYkE",
      "input": {"queryFilter": "userName eq \"bjensen\""}
    }' \
    "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements"
    {
      "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": "eyJ0e…​FYkE"
    }

    The server converts that requirement and token to a URL that is emailed.

  4. The user receives an email with the password reset link.

    Clicking the link sends another POST request to the emailValidation stage, along with the token, and a code:

    curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "Content-Type: application/json" \
    --request POST \
    "https://localhost:8443/#/passwordreset/&token=eyJ0e…​FYkE&code=code"

    The process advances to the reset stage and returns its requirements.

  5. After email validation, the client submits the new password. The process advances to the reset stage, updates the managed object, and exits:

    curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --request POST \
    --header "Content-Type: application/json" \
    --data {
      "token": "eyJ0e…​FYkE",
      "input": {
        "password": "Passw0rd"
      }
    } \
    "https://localhost:8443/openidm/selfservice/reset?_action=submitRequirements"
    {
      "type": "resetStage",
      "tag": "end",
      "status": {
        "success": true
      },
      "additions": {
      }
    }
Copyright © 2010-2023 ForgeRock, all rights reserved.