Self-service

Self-service components offer a way to register self-service processes (e.g. forgotten password reset) and handle their execution. A self-service process is an anonymous process consisting of a set of discrete stages that the user progresses in a predefined order (e.g. user input or email verification). Each individual stage can access and mutate the shared process state (read necessary data from it or update it with data that may be useful to subsequent stages).

OSGi service class: org.forgerock.openidm.selfservice.impl.SelfService
OSGi persistent identifier: org.forgerock.openidm.selfservice
Configuration file: selfservice-<processName>.json
Router mapping: /selfservice/<processName>

Wren:IDM provides support for three different self-service processes that can be configured out-of-the-box from the Admin UI (see Predefined Processes).

Process Definition

Self-service process is defined inside conf/selfservice-<processName>.json project file. The configuration requires following properties:

stagesConfig – array of stage configurations (see chapter Stage Configuration)
snapshotToken – snapshot token configuration (see chapter Snapshot Token Configuration)
storage – process state persistence configuration
- allowed values: "stateless"

Simple password reset process definition example

{
  "stageConfigs" : [
    {
      "name" : "userQuery",
      "identityServiceUrl" : "managed/user",
      "identityIdField" : "_id",
      "identityEmailField" : "mail",
      "identityUsernameField" : "userName",
      "identityAccountStatusField" : "accountStatus",
      "validQueryFields" : ["userName", "mail"]
    },
    {
      "name" : "resetStage",
      "identityServiceUrl" : "managed/user",
      "identityPasswordField" : "password"
    }
  ],
  "snapshotToken" : {
    "type" : "jwt",
    "jweAlgorithm" : "RSAES_PKCS1_V1_5",
    "encryptionMethod" : "A128CBC_HS256",
    "jwsAlgorithm" : "HS256",
    "tokenExpiry" : 180
  },
  "storage" : "stateless"
}

Stage Configuration

Stage configurations vary from stage to stage. Documentation for all default stages can be found in chapter Supported Stages.

Type of the stage that is being defined by the configuration object must be specified with one of the following properties:

name – default stage name (e.g. "resetStage")
class – custom stage configuration class name (e.g. "org.forgerock.selfservice.stages.reset.ResetStageConfig")

Snapshot Token Configuration

Self-service processes utilize JSON Web Token (JWT) for storing process context / state details. The configuration of snapshotToken property requires the following properties:

type – token type
- allowed values: "jwt"
jweAlgorithm – JWE algorithm
- allowed values: see JweAlgorithm class in wrensec-commons GitHub repository
encryptionMethod – encryption method
- allowed values: see EncryptionMethod class in wrensec-commons GitHub repository
jwsAlgorithm – JWS algorithm
- allowed values: see JwsAlgorithm class in wrensec-commons GitHub repository
tokenExpiry – token life time in seconds (optional)
- if not provided, the token never expires (stateless tokens should always have an expiry configured)

Supported Stages

Wren:IDM provides a number of default stages that can be used in a self-service process. These stages are supported by the default End User UI.

Captcha Stage

Verification stage based on reCAPTCHA service.

Configuration:

name – "captcha"
recaptchaSiteKey – reCAPTCHA site key
recaptchaSecretKey – reCAPTCHA secret key
recaptchaUri – URI for verifying reCAPTCHA

Example configuration

{
  "name" : "captcha",
  "recaptchaSiteKey" : "123",
  "recaptchaSecretKey" : "abc",
  "recaptchaUri" : "https://www.google.com/recaptcha/api/siteverify"
}

Email Validation Stage

Stage for verifying the user’s email address. This stage reads the email address from the process state and sends a verification email to that address. The verification email message contains a verification link (including query parameter with process state token) for process continuation. The user has to open the link to progress to the next process stage.

Configuration:

name – "emailValidation"
emailServiceUrl – URL of the email service that will be used to send verification email
emailServiceParameters – additional parameters for the email service
subjectTranslations – map of verification email subjects for different locales
- expected format: Map<locale, subject>
messageTranslations – map of verification email messages for different locales
- expected format: Map<locale, message>
mimeType – verification email message MIME type
from – verification email sender address
verificationLinkToken – string token representing where the verification URL should be substituted
verificationLink – verification URL to be passed into the verification email message
identityEmailField – field name for the identity email address

Example configuration

{
  "name" : "emailValidation",
  "emailServiceUrl" : "external/email",
  "emailServiceParameters" : {
    "someflag" : "true"
  },
  "subjectTranslations" : {
    "en" : "Email subject in EN",
    "fr" : "Email subject in FR"
  },
  "messageTranslations" : {
    "en" : "Email message with verification link %link% in EN",
    "fr" : "Email message with verification link %link% in FR"
  },
  "mimeType" : "text/plain",
  "from" : "noreply@example.com",
  "verificationLinkToken" : "%link%",
  "verificationLink" : "https://localhost:8080/#/emailVerification/",
  "identityEmailField" : "mail"
}

KBA Security Answer Definition Stage

Stage responsible for providing configured KBA questions to the user and storing provided answers to the process state.

Configuration:

name – "kbaSecurityAnswerDefinitionStage"
kbaConfig
- questions – predefined security questions for users to answer
  - expected format: Map<id, Map<locale, question>>
- kbaPropertyName – user property name where KBA details will be set
numberOfAnswersUserMustSet – number of answers that user must set

If kbaConfig is set to null, Self-service service will try to read the configuration from conf/selfservice.kba.json file.

Example configuration

{
  "name" : "kbaSecurityAnswerDefinitionStage",
  "numberOfAnswersUserMustSet" : "1",
  "kbaConfig" : {
    "kbaPropertyName" : "kbaInfo",
    "questions" : {
      "1" : {
        "en" : "Question 1 in EN",
        "fr" : "Question 1 in FR"
      },
      "2" : {
        "en" : "Question 2 in EN",
        "fr" : "Question 2 in FR"
      }
    }
  }
}

KBA Security Answer Verification Stage

Stage responsible for verifying user provided answers to KBA questions stored in the process state.

Configuration:

name – "kbaSecurityAnswerVerificationStage"
kbaConfig
- questions – predefined security questions for users to answer
  - expected format: Map<id, Map<locale, question>>
- kbaPropertyName – user property name where KBA details were set
numberOfQuestionsUserMustAnswer – number of questions that user must answer
identityServiceUrl – identity service URL used to read the user object

If kbaConfig is set to null, Self-service service will try to read the configuration from conf/selfservice.kba.json file.

Example configuration

{
  "name" : "kbaSecurityAnswerVerificationStage",
  "identityServiceUrl" : "managed/user",
  "numberOfQuestionsUserMustAnswer" : "2",
  "kbaConfig" : {
    "kbaPropertyName" : "kbaInfo",
    "questions" : {
      "1" : {
        "en" : "Question 1 in EN",
        "fr" : "Question 1 in FR"
      },
      "2" : {
        "en" : "Question 2 in EN",
        "fr" : "Question 2 in FR"
      }
    }
  }
}

User Registration Stage

Using the configured identity service, this stage creates a new user with data stored in the process context by previous stages.

Configuration:

name – "selfRegistration"
identityServiceUrl – resource URL used to create new user

Example configuration

{
  "name" : "selfRegistration",
  "identityServiceUrl" : "managed/user"
}

Password Reset Stage

Using the configured identity service, this stage patches the user object with the newly provided password.

Configuration:

name – "resetStage"
identityServiceUrl – resource URL used to patch the user
identityPasswordField – user property name where password should be stored

Example configuration

{
  "name" : "resetStage",
  "identityServiceUrl" : "managed/user",
  "identityPasswordField" : "password"
}

Terms and Conditions Stage

Stage presents the configured Terms and Conditions text to the user for acceptance.

Configuration:

name – "termsAndConditions"
termsTranslations – map of terms and conditions for different locales
- expected format: Map<locale, terms and conditions string>

Example configuration

{
  "name" : "termsAndConditions",
  "termsTranslations" : {
    "en" : "Terms and conditions in EN",
    "fr" : "Terms and conditions in FR",
  }
}

Email Based Username Retrieval Stage

Stage for retrieving user’s username via email.

Configuration:

name – "emailUsername"
emailServiceUrl – URL of the email service that will be used to send verification email
emailServiceParameters – additional parameters for the email service
subjectTranslations – map of verification email subjects for different locales
- expected format: Map<locale, subject>
messageTranslations – map of verification email messages for different locales
- expected format: Map<locale, message>
mimeType – verification email message MIME type
from – verification email sender address
usernameToken – string token representing where the username should be substituted

Example configuration

{
  "name" : "emailUsername",
  "emailServiceUrl" : "external/email",
  "emailServiceParameters" : {
    "someflag" : "true"
  },
  "subjectTranslations" : {
    "en" : "Email subject in EN",
    "fr" : "Email subject in FR"
  },
  "messageTranslations" : {
    "en" : "Email message with username %username% in EN",
    "fr" : "Email message with username %username% in FR"
  },
  "mimeType" : "text/plain",
  "from" : "noreply@example.com",
  "usernameToken" : "%username%"
}

Retrieve Username Stage

Stage for retrieving the user’s username that is stored to process context’s successAdditions property.

Configuration:

name – "retrieveUsername"

Example configuration

{
  "name" : "retrieveUsername"
}

User Details Stage

Stage responsible for storing provided user data to the process context. If process context already contains user email, it must match the provided email. If no email is provided, the user email from the process context will also be added among other user data in the process context.

Configuration:

name – "userDetails"
identityEmailField – field name for the identity email address

Example configuration

{
  "name" : "userDetails",
  "identityEmailField" : "mail"
}

User Query Stage

Stage is responsible for querying the configured identity service for a user based on the provided query fields. Once identified, it populates mail and userId fields in process context.

Configuration:

name – "userQuery"
validQueryFields – list of query fields to be used when looking up the user
identityServiceUrl – identity service URL used to lookup the user
identityIdField – field name for the identity ID
identityEmailField – field name for the identity email address
identityUsernameField – field name for the identity username
identityAccountStatusField – field name for the identity account status

Example configuration

{
  "name" : "userQuery",
  "validQueryFields" : ["userName", "mail"],
  "identityServiceUrl" : "managed/user",
  "identityIdField" : "_id",
  "identityEmailField" : "mail",
  "identityUsernameField" : "userName",
  "identityAccountStatusField" : "accountStatus"
}

Validate Active Account Stage

Stage responsible for validating user account status prior to password reset.

Configuration:

name – "validateActiveAccount"
validStatusValue – account status value that is considered valid

Example configuration

{
  "name" : "validateActiveAccount",
  "validStatusValue" : "active"
}

Social User Details Stage

Stage responsible for collecting user profile details from the integrated OAuth2 or OpenID Connect social identity provider. It expects the mail field to be populated in the process context, which it uses to verify against the email address specified in the provided user object.

Configuration:

name – "socialUserDetails"
identityEmailField – field name for the identity email address
providers – list of identity provider configurations
- name – unique provider name
- type – authentication type (e.g., OPENID_CONNECT, OAUTH)
- icon – icon HTML
- authorization_endpoint – endpoint for authentication and authorization of a user
- token_endpoint – endpoint for requesting access and ID tokens
- userinfo_endpoint – endpoint for requesting user information
- well-known – well-known endpoint for OpenID Connect configuration key-value pairs
- client_id – OAuth client ID
- client_secret – OAuth client secret
- scope – OAuth scopes being requested
  - expected value: List<scope>
- authenticationId – property that maps to unique user identifier
- propertyMap – property mapping from provider fields to Wren:IDM fields (optional)
- enabled – enabled-state
  - expected value: true / false

Example configuration

{
  "name" : "socialUserDetails",
  "identityEmailField" : "mail",
  "providers" : [
    {
      "name" : "google",
      "type" : "OPENID_CONNECT",
      "icon" : "google",
      "authorization_endpoint" : "authorization_endpoint",
      "token_endpoint" : "token_endpoint",
      "userinfo_endpoint" : "userinfo_endpoint",
      "well-known" : "",
      "client_id" : "",
      "client_secret" : "",
      "scope" : [
        "openid",
        "profile",
        "email"
      ],
      "authenticationId" : "sub",
      "enabled" : true
    }
  ]
}

Predefined Processes

Wren:IDM comes with three out-of-the-box self-service processes:

User Registration
Password Reset
Forgotten Username

In addition to the standard JSON file configuration, these processes can also be configured directly in the Admin UI.

The configuration file for each of the above predefined processes is created after the process is explicitly enabled in the Admin UI. When a process is enabled or disabled in Admin UI, the option is saved to the corresponding boolean property in conf/ui-configuration.json file.

User Registration Process

User registration process serves to collect user data and create new user object.

Corresponding property in conf/ui-configuration.json: selfRegistration

Configuration file: conf/selfservice-registration.json

Default configuration

{
  "stageConfigs" : [
    {
      "name" : "userDetails",
      "identityEmailField" : "mail"
    },
    {
      "name" : "emailValidation",
      "identityEmailField" : "mail",
      "emailServiceUrl" : "external/email",
      "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 mail d'inscription.</h3><h4><a href=\"%link%\">Lien de vérification email</a></h4>"
      },
      "verificationLinkToken" : "%link%",
      "verificationLink" : "https://localhost:8443/#register/"
    },
    {
      "name" : "kbaSecurityAnswerDefinitionStage",
      "numberOfAnswersUserMustSet" : 1,
      "kbaConfig" : null
    },
    {
      "name" : "selfRegistration",
      "identityServiceUrl" : "managed/user"
    }
  ],
  "snapshotToken" : {
    "type" : "jwt",
    "jweAlgorithm" : "RSAES_PKCS1_V1_5",
    "encryptionMethod" : "A128CBC_HS256",
    "jwsAlgorithm" : "HS256",
    "tokenExpiry" : 1800
  },
  "storage" : "stateless"
}

Stage kbaSecurityAnswerDefinitionStage uses default KBA configuration from conf/selfservice.kba.json file.

Default KBA configuration

{
  "kbaPropertyName" : "kbaInfo",
  "questions" : {
    "1" : {
      "en" : "What's your favorite color?",
      "en_GB" : "What's your favorite colour?",
      "fr" : "Quelle est votre couleur préférée?"
    },
    "2" : {
      "en" : "Who was your first employer?"
    }
  }
}

Password Reset Process

Password reset process allows users to reset their forgotten password from End User UI’s login page.

Corresponding property in conf/ui-configuration.json: passwordReset

Configuration file: conf/selfservice-reset.json

Default configuration

{
  "stageConfigs" : [
    {
      "name" : "userQuery",
      "validQueryFields" : [
        "userName",
        "mail",
        "givenName",
        "sn"
      ],
      "identityIdField" : "_id",
      "identityEmailField" : "mail",
      "identityUsernameField" : "userName",
      "identityServiceUrl" : "managed/user"
    },
    {
      "name" : "emailValidation",
      "identityEmailField" : "mail",
      "emailServiceUrl" : "external/email",
      "from" : "info@admin.org",
      "subject" : "Reset password email",
      "mimeType" : "text/html",
      "subjectTranslations" : {
        "en" : "Reset your password",
        "fr" : "Réinitialisez votre mot de passe"
      },
      "messageTranslations" : {
        "en" : "<h3>Click to reset your password</h3><h4><a href=\"%link%\">Password reset link</a></h4>",
        "fr" : "<h3>Cliquez pour réinitialiser votre mot de passe</h3><h4><a href=\"%link%\">Mot de passe lien de réinitialisation</a></h4>"
      },
      "verificationLinkToken" : "%link%",
      "verificationLink" : "https://localhost:8443/#passwordReset/"
    },
    {
      "name" : "kbaSecurityAnswerVerificationStage",
      "kbaPropertyName" : "kbaInfo",
      "identityServiceUrl" : "managed/user",
      "numberOfQuestionsUserMustAnswer" : "1",
      "kbaConfig" : null
    },
    {
      "name" : "resetStage",
      "identityServiceUrl" : "managed/user",
      "identityPasswordField" : "password"
    }
  ],
  "snapshotToken" : {
    "type" : "jwt",
    "jweAlgorithm" : "RSAES_PKCS1_V1_5",
    "encryptionMethod" : "A128CBC_HS256",
    "jwsAlgorithm" : "HS256",
    "tokenExpiry" : 1800
  },
  "storage" : "stateless"
}

Stage kbaSecurityAnswerVerificationStage uses default KBA configuration from conf/selfservice.kba.json file.

Default KBA configuration

{
  "kbaPropertyName" : "kbaInfo",
  "questions" : {
    "1" : {
      "en" : "What's your favorite color?",
      "en_GB" : "What's your favorite colour?",
      "fr" : "Quelle est votre couleur préférée?"
    },
    "2" : {
      "en" : "Who was your first employer?"
    }
  }
}

Forgotten Username Process

Forgotton username process allows users to retrieve their forgotten username from End User UI’s login page.

Corresponding property in conf/ui-configuration.json: forgotUsername

Configuration file: conf/selfservice-username.json

Default configuration

{
  "stageConfigs" : [
    {
      "name" : "userQuery",
      "validQueryFields" : [
        "mail",
        "givenName",
        "sn"
      ],
      "identityIdField" : "_id",
      "identityEmailField" : "mail",
      "identityUsernameField" : "userName",
      "identityServiceUrl" : "managed/user"
    },
    {
      "name" : "emailUsername",
      "emailServiceUrl" : "external/email",
      "from" : "info@admin.org",
      "mimeType" : "text/html",
      "subjectTranslations" : {
        "en" : "Account Information - username"
      },
      "messageTranslations" : {
        "en" : "<h3>Username is:</h3><br />%username%"
      },
      "usernameToken" : "%username%"
    },
    {
      "name" : "retrieveUsername"
    }
  ],
  "snapshotToken" : {
    "type" : "jwt",
    "jweAlgorithm" : "RSAES_PKCS1_V1_5",
    "encryptionMethod" : "A128CBC_HS256",
    "jwsAlgorithm" : "HS256",
    "tokenExpiry" : 1800
  },
  "storage" : "stateless"
}