Each self-service process advances through the stages in the order in which they are listed in the stageConfigs array in the process configuration file. The password reset process, for example, might include the following stages:

{
    "stageConfigs" : [
        {
            "name": "parameters",
            ...
        },
        {
            "name" : "userQuery",
            ...
        },
        {
            "name" : "validateActiveAccount",
            ...
        },
        {
            "name" : "emailValidation",
            ...
        },
        {
            "name" : "kbaSecurityAnswerVerificationStage",
            ...
        },
        {
            "name" : "resetStage",
            ..
        }
    ],
    ...
}

A process definition also includes an optional snapshotToken and storage parameter, for example:

{
    "stageConfigs" : [
    ],
    "snapshotToken" : {
        "type" : "jwt",
        "jweAlgorithm" : "RSAES_PKCS1_V1_5",
        "encryptionMethod" : "A128CBC_HS256",
        "jwsAlgorithm" : "HS256",
        "tokenExpiry" : 300
    },
    "storage" : "stateless"
}

The snapshotToken specifies the format of the token that is passed between the client and the server with each request. By default, this is a JWT token, stored statelessly, which means that the state is stored in the client, rather than on the server side. Because some legacy clients cannot handle the long URLs provided in a JWT token, you can store the snapshot token locally, as a uuid with the following configuration:

{
...
    "snapshotToken" : {
        "type" : "uuid"
    },
    "storage" : "local"
}

In this case, the 16-character token is stored in the IDM repository, in the jsonstorage table. The configuration for the uuid token is stored in the /conf/jsonstore.json file and includes the following settings:

For more information on the self-service tokens, see "Tokens and User Self-Service" in the Integrator's Guide.

If you do not include the snapshotToken and storage in the configuration, the default stateless configuration applies.

When a stage advances, it can optionally insert parameters into the process context or state for consumption by stages that occur later in the process. The snapshot token is essentially the state of the stage. It is the container in which state, successAdditions and other data are stored, and then returned to the client at the end of the process, as an encrypted blob named token.

Sample configurations for each default self-service process are available in the /path/to/openidm/samples/example-configurations/self-service directory.

Each self service process has a specific endpoint under openidm/selfservice with the name of the process; for example openidm/selfservice/reset for the Password Reset process. If you create a custom self-service process with a configuration file such as selfservice-myprocess.json, you produce an endpoint such as http://localhost:8080/openidm/selfservice/myprocess.

All REST actions occur against that endpoint. For example, the following initial GET request against the password reset endpoint returns the requirements for the following stage:

$ curl \
 --header "X-OpenIDM-Username: anonymous" \
 --header "X-OpenIDM-Password: anonymous" \
 --request GET \
 "http://localhost:8080/openidm/selfservice/reset"
{
  "_id": "1",
  "_rev": "-852427048",
  "type": "captcha",
  "tag": "initial",
  "requirements": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Captcha stage",
    "type": "object",
    "required": [
      "response"
    ],
    "properties": {
      "response": {
        "recaptchaSiteKey": "6LcvE1IUAAAAAA5AI1SZzZJl-AlGvHM_dzUg-0_S",
        "description": "Captcha response",
        "type": "string"
      }
    }
  }
}

The remainder of this guide describes each stage, its requirements, and expected responses. It also describes the logical flow for each default self-service process.

A registration process that consists of more than one stage can include an optional "super stage" named allInOneRegistration, that is set outside of the stageConfigs array as follows:

"allInOneRegistration" : true

All-in-one registration covers a number of registration stages. If this property is true, in the registration process configuration, IDM scans the configuration for any of the following stages:

If any of these stages are found, the individual stages are effectively removed from the configuration and a new configuration is generated that accumulates all the found stages.

The purpose of all-in-one registration is to obtain a set of initial requirements, then to advance to the end of all six stages simultaneously. This enables self-registration to be completed on a single registration form. As the process advances, it gathers any output, errors, and so on from all six stages (or however many stages have been configured). The process then returns whatever was gathered from the cumulative stages, including any outstanding requirements. Depending on the output, the process might be required to go through the stages more than once, as the outstanding requirements are provided.

This stage is used to perform auto-login when IDM is configured with {am.name.full} (AM). The stage is similar to the local auto-login stage but also requires the returnParams in state (populated in the Parameters Stage).

For an example of how to set up returnParams redirection to a dedicated URL, see "Registering Users Through IDM" in the Samples Guide.

The purpose of this stage is to collect managed object properties to insert into the user profile. The list of properties to be collected is defined as part of the configuration.

This stage updates the managed object directly, and checks whether attributes are required. If required attributes are not provided, the stage returns the list of requirements again. This stage can throw an exception if there is an error attempting to save the updated attributes.

This stage verifies a response variable populated in state by the reCaptcha mechanism. If the response is missing, or if validation fails (typically if the configuration does not include the required reCaptcha configuration parameters) the stage throws a bad request exception. If validation succeeds, the process advances to the next stage.

Defines a condition, that results in a boolean (true or false). The outcome of the condition determines which stage should be executed next.

This stage evaluates a boolean consentGiven (true or false). If consent is required but not given, the stage fails with an exception. It is up to the client to handle that exception, for example, to prevent registration if the user does not provide consent.

This stage retrieves the email address from state (or in response to initial requirements) then verifies the validity of the email address with the user who submitted the requirements through an email process.

This stage collects new user data and stores it in state. This is the only stage that sets up a user from nothing. The stage does not create a managed object directly—it simply gathers and stores the data. The Self-Registration Stage consumes the stored user data and creates the managed object from it.

The IDM User Details stage executes multiple times, requesting additional requirements each time. There are different ways for the stage to advance, depending on how the user create request is initiated.

If the user completes a self-service registration form, the input contains a user object, collected from the form, and populates that user in state. If the user registers through social authentication, the stage reads the profile from the remote identity provider, normalizes it, then maps it to a user object. That user object is then put into state.

If the new user object in state is incomplete or does not meet policy requirements, the stage returns a new set of requirements, indicating the collected data and the missing data. The registering user is requested to submit the additional data, then the stage revalidates the object in state. When all of the required data to register a user is present, the process advances to the next stage.

In the context of registration, this stage supplies security questions to the user and captures the answers provided by the user.

The stage validates any answers against the user object. If the requirement is not met (incorrect number of questions answered correctly) the stage throws a bad request exception and increments the failure count of the managed user. If the requirement is met (correct number of questions answered correctly) the process advances to the next stage.

This stage also disallows users from entering custom questions that duplicate any questions defined by the administrator, regardless of the locale. It does this comparison by removing any special characters and making a lower case comparision. For example, What Is YoUr FaVorite COLOR???? would be evaluated as the same question as what is your favorite color?.

This stage verifies security answers and validates user lockout. The stage requires a user ID in state.

The stage reads the user object and validates that the user has not already failed to answer the security questions. The stage then obtains the configured security questions, and returns the minimum number of randomly selected questions as a requirement.

The stage validates any answers against the user object. If the requirement is not met (incorrect number of questions answered correctly) the stage throws a bad request exception and increments the failure count of the managed user. If the requirement is met (correct number of questions answered correctly) the process advances to the next stage.

The KBA Update stage is used as part of progressive profile completion to enable users to update their existing security questions and to add any additional questions that are needed. This stage updates the user object directly. If a user fails to provide sufficient questions, the stage returns the requirements again. If the object cannot be updated, the stage throws an exception. The stage outputs nothing to the state and has no downstream dependencies.

This stage is used to perform auto-login with IDM. The stage obtains the OAuth Login from state and populates the user object (username and password) in state.

The stage adds the OAuth login to the successAdditions (with a value of true) and adds the successURL from its own configuration. If IDM can obtain all those details from state, it takes the user object, locates the username and password, and generates a CREDENTIAL_JWT. That JWT is then placed in the successAdditions parameter.

If IDM is unable to generate the CREDENTIAL_JWT it generates an internal server error (500).

This stage captures parameters in the original request. To advance, the stage assesses the input body. Any values that have been passed in and are listed in the configuration are put into state. The stage ignores any values that are not listed in the configuration. The self-service mechanism passes the parameters back to the client at the end of the process.

By default, this stage is required only if you are integrating IDM with ForgeRock Access Management. The stage is added automatically if you use the UI to configure a self-service process, but can generally be ignored unless a custom client or UI requires it.

Currently, this stage is used only to patch the managed object with the terms and conditions acceptance obtained from state. If the terms and conditions state is not present, the stage simply advances to the next stage in the process.

This stage updates the managed object directly, changing the value of the configured identityPasswordField. To gather the initial requirements the stage reads the managed user object, and checks that the email and userID of the object match what is in state. If they do not match, the stage exits with a Bad request exception.

If they do match, the stage returns with its requirements (the new password value). When the requirements are submitted, the stage advances, locates the userId again, the new password. If the password is empty, the stage throws an exception. If the password is valid, the stage patches the managed user object directly to update the password. If the patch fails, the stage returns the requirements again, along with an error message (for example, a password policy requirement).

This is currently the final stage in the default user registration process. The stage obtains all the user details from state. When the stage advances, it checks state for any idpdata, combines that with the user data, and creates the managed user object. This stage must occur in any registration process.

This stage enables an existing managed user to claim a social identity. The stage obtains a CLIENT_TOKEN from some social identity provider. That token includes the following data:

Using the CLIENT_TOKEN, the stage retrieves the user profile from the social identity provider and normalizes the profile into a user object (using the regular normalization mapping for social identity providers). For more information on this mapping, see "Many Social Identity Providers, One Schema" in the Integrator's Guide.

If the stage is unable to retrieve the user profile, or unable to normalize it using the mapping, it exits with an exception. It does not return any missing requirements.

When the user profile has been normalized, the stage attempts to identify any existing managed users that match the profile. If there are no matches, it simply advances to the next stage in the process. If it finds a match, it extracts the existing managed object and returns that as a new set of requirements.

The new requirement is that the user must provide their password, either their managed/user password, or the password to another social identity provider if they registered through a separate identity provider.

The stage then does the following:

This stage evaluates a boolean accepted (true or false).

This stage queries the managed user repository for a user, based on the supplied query fields. If the stage identifies a user, it populates the mail, userId, userName, and accountStatus fields in state.

The REST calls shown in this chapter assume that user registration is enabled with the default security questions and that the configuration is similar to that shown in the sample registration configuration file (samples/example-configurations/self-service/selfservice-registration.json):

{
    "allInOneRegistration" : true,
    "stageConfigs" : [
        {
            "name": "parameters",
            "parameterNames" : [
                "returnParams"
            ]
        },
        {
            "name" : "idmUserDetails",
            "identityEmailField" : "mail",
            "socialRegistrationEnabled" : true,
            "identityServiceUrl" : "managed/user",
            "registrationProperties" : [
                "userName",
                "givenName",
                "sn",
                "mail"
            ],
            "registrationPreferences": ["marketing", "updates"]
        },
        {
            "name" : "termsAndConditions"
        },
        {
            "name" : "emailValidation",
            "identityEmailField" : "mail",
            "emailServiceUrl" : "external/email",
            "emailServiceParameters" : {
                "waitForCompletion" : false
            },
            "from" : "info@admin.org",
            "subject" : "Register new account",
            "mimeType" : "text/html",
            "subjectTranslations" : {
                "en" : "Register new account",
                "fr" : "Créer un nouveau compte"
            },
            "messageTranslations" : {
                "en" : "<h3>This is your registration email.</h3><h4><a href=\"%link%\">Email verification link</a></h4>",
                "fr" : "<h3>Ceci est votre email d'inscription.</h3><<h4><a href=\"%link%\">Lien de vérification email</a></h4>"
            },
            "verificationLinkToken" : "%link%",
            "verificationLink" : "https://idm.example.com:8443/#/registration/"
        },
        {
            "name" : "kbaSecurityAnswerDefinitionStage",
            "kbaConfig" : null
        },
        {
            "name" : "selfRegistration",
            "identityServiceUrl" : "managed/user"
        },
        {
            "name" : "localAutoLogin",
            "successUrl" : "",
            "identityUsernameField": "userName",
            "identityPasswordField": "password"
        }
    ],
    "storage" : "stateless"
}

The following REST requests and responses demonstrate the flow through a simple password reset process. To keep the process simple, this flow does not include the Google ReCAPTCHA stage, or the Security Answer Verification stage:

The REST calls shown in this chapter assume the configuration in the samples/example-configurations/self-service/selfservice-profile.json file:

{
    "stageConfigs" : [
        {
            "name" : "conditionaluser",
            "identityServiceUrl" : "managed/user",
            "condition" : {
                "type" : "loginCount",
                "interval" : "at",
                "amount" : 25
            },
            "evaluateConditionOnField" : "user",
            "onConditionTrue" : {
                "name" : "attributecollection",
                "identityServiceUrl" : "managed/user",
                "uiConfig" : {
                    "displayName" : "Add your telephone number",
                    "purpose" : "Help us verify your identity",
                    "buttonText" : "Save"
                },
                "attributes" : [
                    {
                        "name" : "telephoneNumber",
                        "isRequired" : true
                    }
                ]
            }
        }
    ]
}

The default progressive profile completion process involves two mandatory stages:

With the previous configuration, users logging in to the End User UI must submit a telephone number on the 25th login.

The following REST requests and responses demonstrate the flow through a profile completion process, given the previous configuration:

The following REST requests and responses demonstrate the flow through a forgotten username process:

ForgeRock provides a sample custom stage project with the minimum classes and project file required for any self-service stage. Before you start, clone the sample custom stage project from the ForgeRock Commons repository. The sample project has a dependency on the forgerock-selfservice-core artifact. Engage ForgeRock support for access to the required repositories.

The sample project implements a stage named MathProblem. This stage generates a simple math problem that must be completed in order to progress to the next stage.

To build the sample stage, you must have Apache Maven installed.

The project includes the following files, required for any custom self-service stage:

To build the sample stage, follow these steps:

To create a configuration for this stage, examine the configuration class (MathProblemStageConfig.java). Three configuration properties must be specified in the corresponding configuration file:

The configuration for this stage will therefore look something like the following:

{
    "class" : "org.forgerock.selfservice.custom.MathProblemStageConfig",
    "leftValue" : int,
    "rightValue" : int
}, 

Stages are implemented as part of a self-service process. For more information, see "The Self-Service Process Flow". To test your custom stage, you need to add it to a self-service process. You can create a new process, or use one of the default processes available through the Admin UI.