Access Management 7.4.1

User self-service

These topics show you how to configure, maintain, and troubleshoot the user self-service feature provided by ForgeRock Access Management, which automates account registration and account name retrieval, and forgotten password reset.

User self-service

Enable self-registration, password reset, and username retrieval.
Configure user registration

Register users, or delegate user registration to IDM.
Configure password reset

Allow existing users to reset their password.
Configure username retrieval

Allow existing users to retrieve their username.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

User self-service

The user self-service feature lets your customers self-register on your website, securely reset forgotten passwords and retrieve their usernames.

AM’s user self-service capabilities greatly reduce help desk costs and provide a rich online experience that strengthens customer loyalty.

Features
User self-registration

Lets non-authenticated users register on your site. You can add security features like email verification, knowledge-based authentication (KBA) security questions, Google reCAPTCHA, and custom plugins to augment the self-registration process.

Knowledge-based authentication security questions

Supports the capability to present security questions during the registration process. When enabled, the user is prompted to enter answers to pre-configured or custom security questions. Then, during the forgotten password or forgotten username process, the user is presented with the security questions, and must answer them correctly to continue the process.

Forgotten password reset

Lets registered users already in your system reset their passwords. The default password policy is set in the underlying directory server and requires a minimum password length of eight characters by default. If security questions are enabled, users must also correctly answer their pre-configured security questions before resetting their passwords.

Forgotten username support

Lets users retrieve their forgotten usernames. If security questions are enabled, users must also correctly answer their pre-configured security questions before retrieving their usernames.

Google reCAPTCHA plugin

Supports the ability to add a Google reCAPTCHA plugin to the registration page. This plugin protects against any software bots that can be used against your site.

Configurable plugins

Supports the ability to add plugins to customize the user services process flow. You can develop your custom code and drop the .jar file into your container.

Customizable confirmation emails

Supports the ability to customize or localize confirmation emails in plain text or HTML.

The OTP Email Sender node supports plain text notifications only. You cannot include HTML-rich notifications that use information from shared or transient state. If you need to support HTML notifications, you can use a Groovy script with a private HTTP client that makes the REST API calls and place the output in a scripted decision node.
Password policy configuration

Supports password policy configuration, which is enforced by the underlying DS server and manually aligned with frontend UI templates. The default password policy requires a password with a minimum length of eight characters.

Self-registration user attribute allowlist

Supports attribute allowlisting, which lets you specify which attributes can be set by the user during account creation.

The user self-service feature supports a number of different user flows depending on how you configure your security options. These options include email verification, security questions, Google reCAPTCHA, and any custom plugins that you create.

Forgotten username retrieval and forgotten password reset support various user flows, depending on how you configure your security options. If you enabled security questions and the user entered responses to each question during self-registration, the security questions are presented to the user in random order.

Configure user self-service

You can configure the user self-service features to use email address verification, which sends an email containing a link for user self-registration and forgotten password reset via AM’s email service. You can also send the forgotten username to the user by email if configured.

To configure user self-registration and password recovery in the ForgeRock Identity Platform, refer to the ForgeRock Identity Platform self-service documentation.

The following table summarizes the high-level tasks required to configure the user self-service features:

Task Resources

Create encryption and signing keys

The user self-service features require a key pair for encryption and a signing secret key. Create one of each for each instance of user self-service you plan to configure.

Configure a user self-service instance

Each realm requires its own instance.

Configure user self-service security

Configure at least one security method for each feature:

  • Configure the email service to send an email to users that are registering, or users that are resetting their passwords.

  • Configure knowledge-based questions that users must answer to reset their passwords.

  • Configure Google reCAPCHA to protect any of the user self-service features from bots.

Configure user self-service features

Configure the features that your environment requires.

You can also delegate user self-registration to IDM.

Create a user self-service instance

  1. In the AM admin UI, go to Realms > Realm Name > Services and select Add a Service.

  2. Select User Self-Service from the list of possible services.

  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.

    Note that the name of the demo keys shows with a gray color; that does not mean the fields are filled in.

    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.

      The demo key aliases are for test or evaluation purposes. Do not use them in production environments. To create new key aliases, see Create self-service key aliases.

  4. Enable the user self-service features.

  5. Select Create.

Configure the email service

The user self-service feature lets you send confirmation emails to users who are registering on your site or resetting forgotten passwords. Mails are sent using AM’s SMTP or OAuth 2.0 REST-based email service. You can configure the email service by realm or globally.

If the user enters an invalid first or last name, username, or email address during the username or password reset flows, AM presents them with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, but does not actually send an email.

If the user enters an existing username while registering, AM presents them with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, and then sends an email with a registration link to the address that the user entered. Clicking on the link sends the user to the registration page again, and AM shows a message similar to One or more user account values are invalid.

This is to protect the service against account enumeration attacks.

Each user must have a unique email address to use the email features of user self-service.

Perform the following steps to configure the email service:

  1. In the AM admin UI, go to Realms > Realm Name > Services.

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

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

    For Microsoft Graph API transport configurations, this address must exist in the Microsoft Exchange administration center.

    The Transport Type drop-down menu is empty until a secondary configuration is created.

  4. Click Create.

  5. Configure the generic attributes that apply to both types of email service, such as the profile attribute for the user’s email address, the subject, and content for notification messages.

    For more information about the different configuration properties, refer to Email service.

  6. Save your changes.

  7. On the Secondary Configurations tab, click Add a Secondary Configuration.

  8. To configure an OAuth 2.0 REST-based transport type, select Microsoft Graph API.

    Refer to the details of your Microsoft account to complete these settings.

    • Provide a name for the Microsoft REST transport secondary configuration.

      This name is used later to map the client secret in the secret store.

      The name must include alphanumeric characters only.

    • In the Email Rest Endpoint URL field, enter the URL for the endpoint URL for sending emails.

      The format for this is https://graph.microsoft.com/v1.0/users/USER ID/sendMail, for example: https://graph.microsoft.com/v1.0/users/bjensen@xftq8.onmicrosoft.com/sendMail.

    • In the OAuth2 Token Endpoint URL field, enter the OAuth 2.0 authentication endpoint.

      The format for this is https://login.microsoftonline.com/TENANT ID/oauth2/v2.0/token, for example: https://login.microsoftonline.com/d258d3da-98a2-492b-875e-059a6abfbdf9/oauth2/v2.0/token.

    • In the OAuth2 Client Id field, enter the ID for the OAuth 2.0 client. This is the client ID or application ID provided by the Microsoft Application Registration portal.

    • In the OAuth2 Scopes field, enter the scopes to be requested as part of the OAuth 2.0 authentication. The value supported by Microsoft Graph API is https://graph.microsoft.com/.default.

    You must also save the client secret obtained from Microsoft in the secret store. This example uses the file system secret store:

    1. Create a file system secret volume if one does not exist already.

    2. Map the secret ID to a file:

      1. Create a file named am.services.email.microsoftrest.TRANSPORT CONFIGURATION NAME.clientsecret; for example, if you named the Microsoft REST transport secondary configuration msrest, create a file named am.services.email.microsoftrest.msrest.clientsecret.txt.

        The filename must use alphanumeric characters only.

      2. Add the secret to the file and save.

  9. To configure an SMTP Basic authentication transport type, select SMTP.

    Note that SMTP Basic authentication is deprecated and you should use the OAuth 2.0 REST-based Microsoft Graph API transport configuration instead where possible.

    • Provide a name for the SMTP transport secondary configuration.

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

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

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

    • Select Create.

    • Configure additional properties in the email service as needed.

You can configure different realms to use different email transport configuration types.

Configure the Google reCAPTCHA plugin

The user self-service feature supports the Google reCAPTCHA plugin, which can be placed on the Register Your Account, Reset Your Password, and Retrieve Your Username pages. The Google reCAPTCHA plugin protects your user self-service implementation from software bots.

Google reCAPTCHA is the only supported plugin for user self-service. AM works with Google reCAPTCHA v2. Any other Captcha service will require a custom plugin.

To configure JVM properties for proxy support, see Configure AM for outbound communication.

  1. Register your website 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 admin UI. 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 admin UI.

    AM supports the Google reCAPTCHA plugin to protect against software bots.
    Figure 1. Google reCAPTCHA Page

  2. In the AM admin UI, go to Realms > Realm Name > Services and select the User Self-Service service.

  3. Select the General Configuration tab.

  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, leave the URL by default.

  7. Save your changes.

  8. Enable Google reCAPTCHA for the user self-service features.

    For more information see:

Configure knowledge-based security questions

Knowledge-based authentication (KBA) is an authentication mechanism in which the user must correctly answer a number of pre-configured security questions that are set during the initial registration setup. If successful, the user is granted the privilege to carry out an action, such as registering an account, resetting a password, or retrieving a username. The security questions are presented in a random order to the user during the User Self-Registration, forgotten password reset, and forgotten username processes.

AM provides a default set of security questions and easily allows AM administrators and users to add their own custom questions.

Security questions must be set in order for users to reset their password.

If the user enters an invalid username, email, or first name/surname pair as part of a recovery flow, AM presents them with a random KBA question before failing the flow. This is to protect the service against account enumeration attacks. If both the security questions and the confirmation emails are enabled for a given flow, AM presents the user with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, but does not actually send an email.

  1. In the AM admin UI, go to Realms > Realm Name > Services and select the User Self-Service service.

  2. Select the General Configuration tab.

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

    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. Save your changes.

  7. Ensure that the kbainfo attribute is set in the profile attribute allowlist.

The profile attribute allowlist controls the information returned to non-administrative users when they access json/user endpoints. For example, the allowlist controls the attributes shown in the user profile page.

Common profile attributes are allowlisted by default. You must add any custom attributes that you want non-administrative users to see.

The allowlist can be set globally, or per realm, in the user self-service service. To modify the list:

  • Globally: Go to Configure > Global Services > User Self-Service > Profile Management, and edit the Self readable attributes field.

  • By realm: Go to Realms > Realm Name > Services > User Self-Service > Profile Management, and edit the Self readable attributes field.

    Note that you need to add the user self-service service to the realm if you have not done so already, but you do not need to configure anything other than the allowlist.

Configure user registration

User self-registration lets end users create their own accounts in AM. You can configure AM to perform user registration, or you can delegate user registration to IDM.

Configure AM for user self-registration

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. In the AM admin UI, configure the email service.

  2. Go to Realms > Realm Name > Services and select User Self-Service.

  3. On the User Registration tab, enable User Registration.

  4. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you have configured the plugin, as described in Configure the Google reCAPTCHA plugin.

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

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

  7. Enable Security Questions to display security questions during the self-registration process.

    If you enable security questions, the user is presented with the configured questions during the forgotten password and forgotten username flows. The user must answer these questions in order to reset their passwords or retrieve their usernames .

  8. In the Token LifeTime field, set an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user self-registers, they will need to restart the registration process.

    Default: 300 seconds.

  9. To customize the user registration outgoing email, perform the following steps:

    • 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, or fr for French. For example, the subject line values could be: en|Registration Email and fr|E-mail d’inscription.

    • 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. The email body text must be all on one line, and can contain any HTML tags within the body of the text.

      For example:

      en|Thank you for registering with example.com! Click <a href="%link%">here</a> to register.`

  10. In the Valid Creation Attributes field, enter the attributes that the user can set during registration.

    These attributes are based on the AM identity repository.

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

  12. Save your changes.

  13. On 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/.

  14. Save your changes.

Delegate user self-registration to IDM

Like AM, IDM offers user self-registration functionality. However, IDM provides additional onboarding and provisioning features.

You can delegate user registration to IDM after a user has authenticated to AM, using a social identity authentication module, for example.

For IDM to complete the registration process:

  • AM and IDM must be connected to the same user data store.

    For more information, refer to the shared identity store sample in the platform documentation.

  • AM and IDM must share the signing and encryption keys used for self-service.

    You can supply your own keys for both servers, or you can use the default IDM keys.

    To use the default IDM keys, follow the instructions in Copy key aliases to copy the following key aliases from the IDM keystore to the AM keystore:

    • openidm-selfservice-key—encrypts JWT self-service tokens using HS256 (HMAC with SHA-256) (SecretKeyEntry)

    • selfservice—Signs JWT session tokens using RSA (PrivateKeyEntry)

    When you have copied the keys, restart AM to apply the changes.

Configure AM to let IDM handle registration

  1. In the AM admin UI, go to Configure > Global Services > IdmIntegrationService and enable the service.

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

  3. Enter the signing and encryption key information:

    1. If you used the default IDM keys, enter the following key information:

      • In the provisioningSigningKeyAlias field, enter selfservice.

      • In the provisioningEncryptionKeyAlias field, openidm-selfservice-key.

      • In the provisioningSigningAlgorithm field, enter HS256.

      • In the provisioningEncryptionAlgorithm field, enter RSAES_PKCS1_V1_5.

      • In the provisioningEncryptionMethod field, enter A128CBC_HS256.

    2. If you created new signing or encryption keys, enter the details of these keys. The keys must be identical and available in the default keystores of both AM and IDM.

      For more information, see Security in the IDM documentation.

    3. If you are using IDM 6 or earlier, enable the jwtSigningCompatibilityMode property.

    For details of the configuration properties, see IDM provisioning.

  4. Save your changes.

  5. In the AM admin UI, go 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:

    • Select Use IDM as Registration Service.

    • Enable Create account if it does not exist.

  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 basic information on integrating AM and IDM, refer to the sample platform setup documentation.

User management of passwords and security questions

Once the user has self-registered to your system, they can change their password and security questions at any time on the user profile page. The user profile page provides tabs to carry out these functions.

The User Profile page supports the ability to change the user’s password on the Password tab.
Figure 2. User Profile Page Password Tab
The User Profile page supports the ability to change the user’s security questions on the Security Questions tab.
Figure 3. User Profile Page Security Questions Tab

Configure forgotten password reset

The forgotten password feature allows existing users to reset their passwords when they cannot remember them.

  1. In the AM admin UI, go to Realms > Realm Name > Services and select the User Self-Service service.

  2. Select the Forgotten Password tab.

  3. Enable Forgotten Password.

  4. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as described in Configure the Google reCAPTCHA plugin.

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

  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.

    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:

    • Enable Enforce password reset lockout.

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

  7. In the Token LifeTime (seconds) 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.

  8. To customize the forgotten password outgoing email, perform the following steps:

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

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

  9. Save your changes.

  10. 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/.

  11. Save your changes.

Configure forgotten username retrieval

The forgotten username feature allows existing users to retrieve their usernames when they cannot remember them.

  1. In the AM admin UI, go to Realms > Realm Name > Services and select User Self-Service.

  2. Select the Forgotten Username tab.

  3. Enable Forgotten Username.

  4. Enable Captcha to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as described in Configure the Google reCAPTCHA plugin.

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

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

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

  8. In the Token LifeTime (seconds) 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 username outgoing email, perform the following steps:

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

    • 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%.

  10. Save your changes.

Register a user

The AM UI includes pages for users to register to AM. You can, however, create a RESTful application to leverage the user self-service features.

AM’s User Self-Registration basic flow with optional features disabled.
Figure 4. User self-registration basic flow (UI)
User self-registration flow with options (UI)
AM’s user self-registration supports various user flows, depending on how you configure your options.

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.

By default, the user self-registration flow validates the email address after the user has provided their details. AM also provides a backwards-compatible mode for user self-registration flows configured in OpenAM 13 and 13.5 that lets AM validate the email address before the user has provided their details.

Register a user over REST

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

Register a user over REST (backwards-compatible mode)

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.

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"
    }
}

Reset forgotten passwords

The AM UI includes pages for users to reset their forgotten passwords. You can, however, create a RESTful application to leverage the user self-service features.

Forgotten password flow in the UI

The forgotten password feature supports multiple user flows, depending on how it is configured.

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 required item of security data 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 was 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 success element in status has a value of true, the 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."
}

Retrieve forgotten usernames

The AM UI includes pages for users to recover their forgotten usernames. You can, however, create a RESTful application to leverage the user self-service features.

AM’s Forgotten Username supports multiple user flows, depending on how you configure your options.
Figure 5. Forgotten Username Flow (UI)

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/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:

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

    For more information on query filters, see Query.

    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.