Resetting Forgotten Passwords

When performing user self-service functions, you can enable one or more security methods, such as email validation, Google reCAPTCHA, knowledge-based authentication, or custom plugins. Each configured security method requires particular security data that AM requests from the client for verification.

A unique token is provided in the second response to the client that must be used in any subsequent requests, so that AM can maintain the state of the user self-service process.

1. Send a GET request to the /selfservice/forgottenPassword endpoint. Notice that the request does not require any form of authentication:

   $ curl \
   --header "Accept-API-Version: resource=1.0" \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenPassword
   {
     "type": "captcha",
     "tag": "initial",
     "requirements": {
       "$schema": "http://json-schema.org/draft-04/schema#",
       "description": "Captcha stage",
       "type": "object",
       "required": [
         "response"
       ],
       "properties": {
         "response": {
           "recaptchaSiteKey": "6Lfr1...cIqbd",
           "description": "Captcha response",
           "type": "string"
         }
       }
     }
   }

   In this example, the Google reCAPTCHA plugin is enabled, so the first request is of the captcha type.

2. Send a POST request to the /selfservice/forgottenPassword endpoint with a query string containing _action=submitRequirements. In the POST data, include an input element in the JSON structure, which should contain values for each element in the required array of the response.

   In this example, the response value required is the user input provided after completing the Google reCAPTCHA challenge:

   $ curl \
   --header "Accept-API-Version: resource=1.0" \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "response": "03AHJ...qiE1x4"
       }
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenPassword?_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": "eyAicHis...PIF-lN4s"
   }

   If the input value is accepted, AM continues with the password reset process and specifies the information required next. In this example, the Google reCAPTCHA was verified and AM is requesting details about the account for the password reset, which must be provided in a queryFilter element.

   The value of the token element should be included in this and all subsequent requests to AM for this reset process.

3. Send a POST request to AM with a queryFilter value in the POST data containing the username of the subject with the password to replace.

   For more information on query filters, see "Query".

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "queryFilter": "uid eq \"demo\""
       },
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements
   {
       "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 was the model of your first car?"
                   },
                   "type": "string"
               }
           }
       },
       "token": "eyAicHis...PIF-lN4s"
   }

   If a single subject is located that matches the provided query filter, the password reset process continues.

   If a subject is not found, an HTTP 400 Bad Request status is returned, along with an error message in the JSON data:

   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Unable to find account"
   }

4. Continue sending POST data to AM containing the requested information, in the format specified in the response. Also return the token value in the POST data, so that AM can track the stages of the password reset process.

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "answer1": "Mustang"
       },
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements
   {
       "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"
               }
           }
           "code": "cf88bb63-b59c-4792-8fdf-2bcc00b0ab06"
       },
       "token": "eyAicHis...PIF-lN4s"
   }

5. When AM has received all the requested information, it sets type to resetStage and returns a unique code value in the response. You can now specify a new password in the POST data, along with both the code and token values:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "password": "5tr0ng~P4s5worD!"
       },
       "code": "cf88bb63-b59c-4792-8fdf-2bcc00b0ab06",
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenPassword?_action=submitRequirements
   {
       "type": "activityAuditStage",
       "tag": "end",
       "status": {
           "success": true
       },
       "additions": {}
   }

   When the process is complete, the tag element has a value of end. If the status element's success value is true, then password reset is complete and the new password is now active.

   If the password is not accepted, an HTTP 400 Bad Request status is returned, along with an error message:

   {
       "code": 400,
       "reason": "Bad Request",
       "message": "Minimum password length is 8."
   }