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