Replacing 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 requests to be sent from AM to the client, and completed responses returned to AM to verify.

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

1. Create 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. Create a POST response back 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 request.

   In this example, a response value was requested, which should be the user input as 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 response was accepted, AM continues with the password reset process and sends the next request for information. In this example, the Google reCAPTCHA was verified and AM is requesting details about the account with the password to replace, which must be provided in a queryFilter element.

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

3. Create a POST response 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 returning POST data to AM containing the requested information, in the format specified in the request. Also return the token value in the POST data, so that AM can track which stage of the password reset process is being completed.

   $ 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"
               }
           }
       },
       "token": "eyAicHis...PIF-lN4s"
   }

5. When requested—when the type value in the request is resetStage—supply the new password in the POST data.

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

   When the process is complete, the tag element has a value of end. If the success element in the status element has a value of 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 in the JSON data:

   {
       "type": "resetStage",
       "tag": "end",
       "status": {
           "success": true
       },
       "additions": {}
   }