To provide user self service features, you must configure suitable key aliases.Perform the following steps to populate the values of the Encryption Key Pair Alias and the Signing Secret Key Alias properties:

1. Log in to the AM console as an administrator, for example, amadmin.

2. Navigate to Configure > Global Services > User Self Service.

3. Populate the values of the Encryption Key Pair Alias and the Signing Secret Key Alias properties with the names of the key pair aliases in your JCEKS keystore. For example, if you are using the demo keys in the default keystore.jceks file, set the properties as follows:

   • Encryption Key Pair Alias to selfserviceenctest.

   • Signing Secret Key Alias to selfservicesigntest.

   User Self Service Key Pair Aliases

   
   
   

4. Save your changes.

By default, OpenAM expects the SMTP service to listen on localhost:465. You can change this setting.

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

2. On the Realms page, click the realm in which you will install the Email Service, and then click Services.

3. Click Services, and then click Add a Service.

4. On the Choose a Service drop-down list, select Email Service, and then enter the following:

   1. Enter the Mail Server Hostname. If you are using the Google SMTP server, you must also configure the Google Mail settings to enable access for less secure applications.

   2. Enter the Mail Server Authentication Username. The default is amadmin. If you are testing on a Google account, you can enter a known Gmail address.

   3. Enter the Mail Server Authentication Password property value.

   4. Enter the Email From Address. The default is no-reply@example.com.

   5. Click Create.

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. Click Configure > Global Services > User Self Service.

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

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

6. In the Google Recaptcha Verification URL field, keep the default.

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

2. Click Configure > Global Services > User Self Service.

3. On the User Self Service page, scroll to the Security Questions section. Enter your own security question in the New Value field, and then click Add. 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.

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

5. 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.

6. Click Finish to save your changes.

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

2. Configure the email service presented in "Configuring the Email Service".

3. Click Configure > Global Services > User Self Service.

4. On the User Self Service page, click Enabled next to User Registration.

5. For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".

6. For Email Verification, clear the Enabled box if you want to turn off the email verification service. We recommend that you keep it selected.

7. For Security Questions, click Enabled 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.

8. 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: 900 seconds.

9. To customize the Self Registration outgoing email, run the following steps:

   1. In the Outgoing Email Subject field, enter the Subject line of your email in the New Value field, and then click Add.

      The subject line format 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 your email in the New Value field, and then click Add.

      The email body text format 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.

10. In the Valid Creation Attributes field, enter the user attributes the user can set during the User Self Registration. The attributes are based on the OpenAM identity repository.

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

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

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

    • User is sent to the login page to authenticate.

12. Under Advanced Configuration, configure the User Registration Confirmation Email URL for your deployment. The default is: http://openam.example.com:8080/openam/XUI/?realm=/#register/.

13. Click Finish to apply your changes.

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

2. Click Configure > Global Services > User Self Service.

3. On the User Self Service page, click Enabled next to Forgotten Passwords.

4. For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".

5. For Email Verification, clear the Enabled box if you want to turn off the email verification service. We recommend that you keep it selected.

6. For Security Questions, click Enabled to display security questions to the user during the forgotten password reset process. The user must correctly answer the security questions to be able to reset passwords.

7. In the Forgotten Password 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: 900 seconds.

8. To customize the Forgotten Password outgoing email, run the following steps:

   1. In the Outgoing Email Subject field, enter the subject line of your email in the New Value field, and then click Add.

      The subject line format 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 your email in the New Value field, and then click Add.

      The email body text format 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.

9. Under Advanced Configuration, change the default Forgotten Password Confirmation Email URL for your deployment. The default is: http://openam.example.com:8080/openam/XUI/?realm=/#passwordReset/.

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

2. Click Configure > Global Services > User Self Service.

3. On the User Self Service page, click Enabled next to Forgotten Username.

4. For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".

5. For Security Questions, click Enabled to display security questions to the user during the forgotten username process. The users must correctly answer the security questions to be able to retrieve their usernames.

6. For Email Username, click Enabled if you want the user to receive the retrieved username by email.

7. For Show Username, click Enabled if you want the user to see their retrieved username on the browser.

8. In the Forgotten Username Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user retrieves their username, then the user will need to restart the forgotten username process.

   Default: 900 seconds.

9. To customize the Forgotten Username outgoing email, run the following steps:

   1. In the Outgoing Email Subject field, enter the subject line of your email in the New Value field, and then click Add.

      The subject Line format 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 your email in the New Value field, and then click Add.

      The email body text format 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%.

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

   $ curl \
   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"
   }

   OpenAM sends a request to complete the user details. The required array defines the data that must be returned to OpenAM 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, OpenAM requests an object named user. Ths object should contain values for the username, givenName, sn, mail, userPassword, and inetUserStatus properties.

   $ curl \
   --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, OpenAM 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 OpenAM 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" \
   --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.

   Note

   The User Self-Service feature provides options to set the user's destination after a successful self-registration. These options include redirecting the user to a 'successful registration' page, to the login page, or automaticatically logging the user into the system. Use the Destination After Successful Self-Registration property to set the option (on the console: Realm Name > Services > User Self-Service > User Registration). When you select User sent to 'successful registration' page or User sent to login page, the JSON response after a successful registration is as follows:

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

   If you select User is automatically logged in, the JSON response is:

   {
     "type": "autoLoginStage",
     "tag": "end",
     "status": {
         "success": true
     },
     "additions": {
         "tokenId": "AQIC5...MQAA*",
         "successUrl": "/openam/console"
     }
   }

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

   $ curl \
   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" \
    --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, OpenAM continues with the username retrieval process and sends the next request for information. In this example, the Google reCAPTCHA was verified and OpenAM 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 OpenAM for this retrieval process.

3. Create a POST response to OpenAM 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, OpenAM 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. Create a GET request to the /selfservice/forgottenPassword endpoint. Notice that the request does not require any form of authentication.

   $ curl \
     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 \
   --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, OpenAM continues with the password reset process and sends the next request for information. In this example, the Google reCAPTCHA was verified and OpenAM 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 OpenAM for this reset process.

3. Create a POST response to OpenAM 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 returning POST data to OpenAM containing the requested information, in the format specified in the request. Also return the token value in the POST data, so that OpenAM 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": "User1234"
         },
         "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, and an error message in the JSON data:

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