PingIDM 7.5.0

The self-service process flow

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. To use this feature, copy /path/to/openidm/samples/example-configurations/self-service/jsonstore.json to your project’s conf/ directory. This file stores the configuration for the uuid token and includes the following settings:

  • entryExpireSeconds—the amount of time before the password reset URL expires.

  • cleanupDwellSecondsliteral—how often the server checks for and expires tokens.

    The value of cleanupDwellSecondsliteral should be a fraction of entryExpireSeconds so that expiration occurs close to the expected expiration time. The check is performed on a periodic basis.

For more information on the self-service tokens, refer to Tokens and User Self-Service.

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 {hostname}/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" \
 --header "Accept-API-Version: resource=1.0" \
 --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 default End User UI implements the following processes:

  • Self-registration (under the endpoint selfservice/registration)

  • Social registration (under the endpoint selfservice/socialUserClaim)

    Social authentication is deprecated and will be removed in a future release of IDM. For more information, refer to Deprecation.

  • Password reset (under the endpoint selfservice/reset)

  • Forgotten username retrieval (under the endpoint selfservice/username)

  • Progressive profile completion (under selfservice/profile)

    Progressive profiling is deprecated and will be removed in a future release of IDM. For more information, refer to Deprecation.

  • Security question updates (under selfservice/kbaUpdate)

  • Terms and conditions (under selfservice/termsAndConditions)

The remainder of this guide describes each stage, its requirements, and expected responses.