Guide to configuring and using ForgeRock® Access Management User Self-Service features.

Perform the following steps to configure the Email Service:

1. Log in to the AM console as the administrator.

2. Navigate to Realms > Realm Name > Services.

3. Select Add a Service and choose Email Service from the list of available services.

4. Configure the Email Service:

   1. In the Mail Server Host Name field, enter the hostname of the mail server. If you are using the Google SMTP server, you must also configure the Google Mail settings to enable access for less secure applications.

   2. In the Mail Server Authentication Username field, enter the username to authenticate to the mail server. If you are testing on a Google account, you can enter a known Gmail address.

   3. In the Mail Server Authentication Password field, enter the password corresponding to the username used to authenticate to the mail server.

   4. In the Email From Address field, enter the email address from which to send the email notifications. For example, no-reply@example.com.

   5. Select Create.

   6. (Optional) Configure additional properties in the Email Service as needed.

      For more information about the different configuration properties, see "Email Service" in the Reference.

1. Register your web site at a Captcha provider, such as Google reCAPTCHA, to get your site and secret key.

   When you register your site for Google reCAPTCHA, you only need to obtain the site and secret key, which you enter in the User Self-Service configuration page in the AM console. You do not have to do anything with client-side integration and server-side integration. The Google reCAPTCHA plugin appears automatically on the Register Your Account, Reset Your Password, and Retrieve Your Username pages after you configure it in the AM console.

   Google reCAPTCHA Page

   
   
   

2. Log in to the AM console as an administrator.

3. Navigate to Realms > Realm Name > Services and select the User Self-Service service.

4. Select the General Configuration tab.

5. In the Google reCAPTCHA Site Key field, enter the site key that you obtained from the Google reCAPTCHA site.

6. In the Google reCAPTCHA Secret Key field, enter the secret key that you obtained from the Google reCAPTCHA site.

7. In the Google reCAPTCHA Verification URL field, leave the URL by default.

8. Save your changes.

9. Enable Google reCAPTCHA for the user self-service features. For more information see:

   • "To Configure User Self-Registration by AM"

   • "Configuring the Forgotten Password Reset Feature"

   • "Configuring the Forgotten Username Feature"

1. Log in to the AM console as the administrator.

2. Navigate to Realms > Realm Name > Services and select the User Self-Service service.

3. Select the General Configuration tab.

4. In the Security Questions field, several questions are available by default. Enter your own questions as required. The syntax is OrderNum|ISO-3166-2 Country Code|Security Question. For example, 5|en|What is your dog's name?. Make sure that order numbers are unique.

   Warning

   You should never remove any security questions as a user may have reference to a given question.

5. In the Minimum Answers to Define field, enter the number of security questions that will be presented to the user during the registration process.

6. In the Minimum Answers to Verify field, enter the number of security questions that must be answered during the Forgotten Password and Forgotten Username services.

7. Save your changes.

Although you can configure user self-registration without any additional security mechanisms, such as email verification or KBA security questions, we recommend configuring the email verification service with user self-registration at a minimum.

1. Log in to the AM console as the administrator.

2. Configure the Email Service as described in "Configuring the Email Service".

3. Navigate to Realms > Realm Name > Services and select the User Self-Service service.

4. Select the User Registration tab.

5. Enable User Registration.

6. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as described in "Configuring the Google reCAPTCHA Plugin".

7. Enable Email Verification to turn on the email verification service. We recommend you leave Email Verification enabled, so users who self-register must perform email address verification.

8. Enable Verify Email before User Detail to verify the user's email address before requesting the user details.

   By default, the user self-registration flow validates the email address after the user has provided their details. Enable this setting for backwards-compatibility with self-registration flows configured in OpenAM 13 or 13.5.

9. Enable Security Questions to display security questions to the user during the self-registration, after which the user must enter their answers to the questions. During the forgotten password or forgotten username services, the user will be presented with the security questions to be able to reset their passwords or retrieve their usernames if Security Questions is enabled.

10. In the Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user self-registers, then the user will need to restart the registration process over again.

    Default: 300 seconds.

11. To customize the User Registration outgoing email, perform the following steps:

    1. In the Outgoing Email Subject field, enter the Subject line of the email.

       The syntax is lang|subject-text, where lang is the ISO-639 language code, such as en for English, fr for French, and others. For example, the subject line values could be: en|Registration Email and fr|Inscription E-mail.

    2. In the Outgoing Email Body field, enter the text of the email.

       The syntax is lang|email-text, where lang is the ISO-639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.

       For example, the email body text could be: en|Thank you for registration to our site! Click <a href="%link%">here</a> to register to the site.

12. In the Valid Creation Attributes field, enter the user attributes the user can be set during user registration. The attributes are based on the AM identity repository.

13. For Destination After Successful Registration, select one of the following options:

    • auto-login. User is automatically logged in and sent to the appropriate page within the system.

    • default. User is sent to a success page without being logged in. In this case, AM displays a "You have successfully registered" page. The user can then click the Login link to log in to AM. This is the default selection.

    • login. User is sent to the login page to authenticate.

14. Save your changes.

15. Under the Advanced Configuration tab, configure the User Registration Confirmation Email URL for your deployment. The default is: https://openam.example.com:8443/openam/XUI/?realm=${realm}#register/.

16. Save your changes.

IDM offers user self-registration functionality, much like AM, but provides additional onboarding and provisioning features.

You can configure the IDM Provisioning service to allow IDM to complete user registration after authenticating to AM using a social identity authentication module, for example.

1. Verify the following pre-requisites:

   1. The AM and IDM instances are connected to the same user data store.

      For more information, see Reconciliation and AM in the ForgeRock Identity Management 6.5 Samples Guide.

   2. The AM instance has a copy of the signing and encryption keys from the IDM installation in its default keystore.

      Follow the instructions in "Copying Key Aliases" in the Setup and Maintenance Guide to copy the following key aliases to the AM default keystore:

      • openidm-selfservice-key

      • selfservice

      Restart AM when completed to apply the changes.

2. Log in to the AM console as the administrator, and navigate to Configure > Global Services > IDM Provisioning.

3. Perform the following actions on the IDM Provisioning page:

   1. Enable the IDM Provisioning service by selecting Enabled.

   2. Enter the URL of the IDM instance in the Deployment URL field, for example https://openidm.example.com.

   3. (Optional) If you created new signing or encryption keys, enter their details, ensuring the keys are identical and available in the default keystores of both AM and IDM.

      For more information on IDM security, see Securing and Hardening Servers in the ForgeRock Identity Management 6.5 Integrator's Guide.

      If you have copied the openidm-selfservice-key and selfservice key alises from IDM, you can leave the default values for the key-related properties.

   4. If you are using IDM 6 or earlier, enable the Signing Compatibility Mode property.

   For more details of the available properties, see "IDM Provisioning".

4. Save your changes.

5. In the AM console, navigate to Realms > Realm Name > Authentication > Modules, and create or select a social authentication module in which to enable IDM user registration.

6. On the social authentication module page, perform the following actions on the Account Provisioning tab:

   1. Select Use IDM as Registration Service.

   2. Ensure Create account if it does not exist is enabled.

7. Save your changes.

   Successfully authenticating to a social authentication module that has IDM as the registration service redirects the user to IDM to complete the user registration.

   For a complete walkthrough, including details on configuring IDM to perform user self-registration, see Integrating IDM With the ForgeRock Identity Platform in the ForgeRock Identity Management 6.5 Samples Guide.

1. Log in to the AM console as the administrator.

2. Navigate to Realms > Realm Name > Services and select the User Self-Service service.

3. Select the Forgotten Password tab.

4. Enable Forgotten Password.

5. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as described in "Configuring the Google reCAPTCHA Plugin".

6. Enable Email Verification to turn on the email verification service. ForgeRock recommends that you keep it enabled.

   Note that the recovery link AM emails to the user contains a code that can only be used once.

7. Enable Security Questions to display security questions to the user during the forgotten password reset process. The user must have security questions defined in their profile, and must correctly answer the presented questions to be able to reset passwords.

   You can also configure AM to lock an account if the user fails to answer their security questions a number of times. To enable this feature, perform the following steps:

   1. Enable Enforce password reset lockout.

   2. In the Lock Out After number of attempts field, set the number of questions the user must fail to answer for AM to lock their account.

8. In the Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user resets their password, then the user will need to restart the forgotten password process over again.

   Default: 300 seconds.

9. To customize the Forgotten Password outgoing email, perform the following steps:

   1. In the Outgoing Email Subject field, enter the subject line of the email.

      The syntax is lang|subject-text, where lang is the ISO-639 language code, such as en for English, fr for French, and others. For example, the subject line value could be: en|Forgotten Password Email.

   2. In the Outgoing Email Body field, enter the text of the email.

      The syntax is lang|email-text, where lang is the ISO-639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.

      For example, the email body text could be: en|Thank you for request! Click <a href="%link%">here</a> to reset your password.

10. Save your changes.

11. Under the Advanced Configuration tab, change the default Forgotten Password Confirmation Email URL for your deployment. The default is: https://openam.example.com:8443/openam/XUI/?realm=${realm}#passwordReset/.

12. Save your changes.

1. Log in to the AM console as the administrator.

2. Navigate to Realms > Realm Name > Services and select the User Self-Service service.

3. Select the Forgotten Password tab.

4. Enable Forgotten Username.

5. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as described in "Configuring the Google reCAPTCHA Plugin".

6. Enable Security Questions to display security questions to the user during the forgotten password reset process. The user must have security questions defined in their profile, and must correctly answer the presented questions to be able to reset passwords.

7. Enable Email Username for the user to receive the retrieved username by email.

8. Enable Show Username for the user to see their retrieved username on the browser.

9. In the Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user resets their password, then the user will need to restart the forgotten password process over again.

   Default: 300 seconds.

10. To customize the Forgotten Username outgoing email, perform the following steps:

    1. In the Outgoing Email Subject field, enter the subject line of the email.

       The syntax is lang|subject-text, where lang is the ISO 639 language code, such as en for English, fr for French, and others. For example, the subject line value could be: en|Forgotten username email.

    2. In the Outgoing Email Body field, enter the text of the email.

       The syntax is lang|email-text, where lang is the ISO 639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.

       For example, the email body text could be: en|Thank you for your inquiry! Your username is %username%.

11. Save your changes.

Before performing the steps in this procedure, ensure that Verify Email before User Detail (Realms > Realm Name > Services > User Self-Service > User Registration) is disabled.

1. Create a GET request to the /selfservice/userRegistration endpoint. Notice that the request does not require any form of authentication.

   $ curl \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/userRegistration
   {
      "requirements": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "New user details",
        "properties": {
           "user": {
               "description": "User details",
               "type": "object"
           }
        },
        "required": [
           "user"
        ],
        "type": "object"
      },
      "tag": "initial",
      "type": "userDetails"
   }

   AM sends a request to complete the user details. The required array defines the data that must be returned to AM to progress past this step of the registration. In the example, the required type is a user object that contains the user details.

2. Create a POST response back to the /selfservice/userRegistration 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, AM requests an object named user. Ths object should contain values for the username, givenName, sn, mail, userPassword, and inetUserStatus properties.

   $ curl \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
          "user": {
            "username": "DEMO",
            "givenName": "Demo User",
            "sn": "User",
            "mail":"demo@example.com",
            "userPassword": "forgerock",
            "inetUserStatus": "Active"
          }
       }
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/userRegistration?_action=submitRequirements
   {
       "requirements": {
         "$schema": "http://json-schema.org/draft-04/schema#",
         "description": "Verify emailed code",
         "properties": {
            "code": {
                "description": "Enter code emailed",
                "type": "string"
            }
         },
         "required": [
             "code"
         ],
         "type": "object"
       },
       "tag": "validateCode",
       "token": "eyJ0eXAiOiJKV.....QiLCJjmqrlqUfQ",
       "type": "emailValidation"
   }

   If the response is accepted, AM continues with the registration process and sends the next request for information.

   The value of the token element should be included in this and any subsequent responses to AM for this registration; AM uses this information to track which stage of the registration process is being completed.

   Note that the request for information is of the type emailValidation. Other possible types include:

   • captcha, if the Google reCAPTCHA plugin is enabled

   • kbaSecurityAnswerDefinitionStage, if knowledge-based security questions are required

   For an example of Google reCAPTCHA validation, see "Retrieving Forgotten Usernames".

3. Return the information required by the next step of the registration, along with the token element.

   In this example, the user information was accepted and a code was emailed to the email address. AM requires this code in the response in an element named code before continuing:

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   --data \
   '{
       "input": {
           "code": "cf53fcb6-3bf2-44eb-a437-885296899699"
       },
       "token": "eyJ0eXAiOiJKV.....QiLCJjmqrlqUfQ"
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/userRegistration?_action=submitRequirements
   {
       "type": "selfRegistration",
       "tag": "end",
       "status": {
           "success": true
       },
       "additions": {}
   }

   When the process is complete, the response from AM has a tag property with value of end. If the success property in the status object has a value of true, then self-registration is complete and the user account was created.

   In the example, AM only required email verification to register a new user. In flows containing Google reCAPTCHA validation or knowledge-based security questions, you would continue returning POST data to AM containing the requested information until the process is complete.

Before performing the steps in this procedure, ensure that Verify Email before User Detail (Realms > Realm Name > Services > User Self-Service > User Registration) is enabled.

1. Create a GET request to the /selfservice/userRegistration endpoint. Notice that the request does not require any form of authentication.

   $ curl \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/userRegistration
   {
      "type":"emailValidation",
      "tag":"initial",
      "requirements":{
         "$schema":"http://json-schema.org/draft-04/schema#",
         "description":"Verify your email address",
         "type":"object",
         "required":[
            "mail"
         ],
         "properties":{
            "mail":{
               "description":"Email address",
               "type":"string"
            }
         }
      }
   }

   AM sends the first request for security information. In this example, the first request is of type emailValidation, but other types include captcha if the Google reCAPTCHA plugin is enabled, and kbaSecurityAnswerDefinitionStage if knowledge-based authentication is required.

   The required array defines the data that must be returned to AM to progress past this step of the registration.

   The properties element contains additional information about the required response, such as a description of the required field, or the site key required to generate a reCAPTCHA challenge.

2. Create a POST response back to the /selfservice/userRegistration 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 mail value was requested.

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   --data \
   '{
       "input": {
           "mail": "demo.user@example.com"
       }
   }' \
   https://openam.example.com:8443/openam/json/selfservice/userRegistration\
   ?_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":"eyAicHis...PIF-lN4s"
   }

   If the response was accepted, AM continues with the registration process and sends the next request for information. In this example, the email address was accepted and a code was emailed to the address, which AM requires in the response in an element named code before continuing.

   The value of the token element should be included in this and any subsequent responses to AM for this registration.

3. 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 registration process is being completed.

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   --data \
   '{
       "input": {
           "code": "cf53fcb6-3bf2-44eb-a437-885296899699"
       },
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/selfservice/userRegistration\
   ?_action=submitRequirements
   {
      "type":"userDetails",
      "tag":"initial",
      "requirements":{
         "$schema":"http://json-schema.org/draft-04/schema#",
         "description":"New user details",
         "type":"object",
         "required":[
            "user"
         ],
         "properties":{
            "user":{
               "description":"User details",
               "type":"object"
            }
         }
      },
      "token":"eyAicHis...PIF-lN4s"
   }

4. When requested—when the type value in the request is userDetails—supply the details of the new user as an object in the POST data.

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Accept-API-Version: resource=1.0, protocol=1.0" \
   --data \
   '{
       "input": {
           "user": {
               "username": "demo",
               "givenName": "Demo User",
               "sn": "User",
               "userPassword": "d3m0",
               "inetUserStatus": "Active"
           }
       },
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/selfservice/userRegistration\
   ?_action=submitRequirements
   {
        "type": "selfRegistration",
        "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 self-registration is complete and the user account was created.

1. Create a GET request to the /selfservice/forgottenUsername 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/forgottenUsername
   {
     "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/forgottenUsername 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 \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Accept-API-Version: resource=1.0" \
   --data \
   '{
       "input": {
           "response": "03AHJ...qiE1x4"
       }
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername?_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 username retrieval process and sends the next request for information. In this example, the Google reCAPTCHA was verified and AM is requesting details about the account name to retrieve, 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 retrieval process.

3. Create a POST response to AM with a queryFilter value in the POST data containing the user's email address associated with their account.

   For more information on query filters, see "Query" in the Development Guide.

   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --data \
   '{
       "input": {
           "queryFilter": "mail eq \"demo.user@example.com\""
       },
       "token": "eyAicHis...PIF-lN4s"
   }' \
   https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername?_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 retrieval process continues.

   If KBA is enabled, AM requests answers to the configured number of KBA questions, as in this example.

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

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

4. Return a POST response with the answers as values of the elements specified in the required array, in this example answer1. Ensure the same token value is sent with each response.

   $ 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/forgottenUsername?_action=submitRequirements
   {
       "type": "retrieveUsername",
       "tag": "end",
       "status": {
           "success": true
       },
       "additions": {
           "userName": "demo"
       }
   }

   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 username retrieval is complete and the username is emailed to the registered address.

   If the Show Username option is enabled for username retrieval, the username retrieved is also returned in the JSON response as the value of the userName element, as in the example above.

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" in the Development Guide.

   $ 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, and 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, and an error message in the JSON data:

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