Platform configuration for user self-service

Some configuration is necessary to enable self-service for the platform. Depending on your method of deployment, some or all of these steps may already be complete, but should be checked to make sure everything is set up correctly.

Most of the configuration for Self-Service is located in AM, with a few exceptions:

Configure self-service trees endpoints

AM includes a service to map authentication trees that you created to endpoints in self-service. To reach this service, from the top-level realm in AM, go to Services and select the Self Service Trees service. If the service isn’t already present, add it using the Add Service button at the top of the page.

You can add multiple endpoints to handle different behavior you want to include. For instance, if you wanted a separate registration flow for registering devices, you could create a tree called Device Registration, then add a new endpoint here called device-registration, with "Device Registration" as the value.

The login endpoint is handled elsewhere. The login endpoint is determined by the Organization Authentication Configuration setting for your realm in Authentication > Settings.

To delete an existing endpoint, you need to call this service’s endpoint directly, and update the treeMapping object:

curl \
--request PUT \
--header 'accept: application/json, text/javascript, /; q=0.01' \
--header 'accept-api-version: protocol=1.0,resource=1.0' \
--header 'accept-language: en-US' \
--header 'content-type: application/json' \
--header 'cookie: <omitted for length>' \
--header 'x-requested-with: XMLHttpRequest' \
--cookie '<omitted for length>' \
--data '{
  "treeMapping":{
    "resetPassword":"PlatformResetPassword",
    "updatePassword":"PlatformUpdatePassword",
    "forgottenUsername":"PlatformForgottenUsername",
    "registration":"PlatformRegistration",
  },
  "_id":"",
  "_type":{
    "_id":"selfServiceTrees",
    "name":"Self Service Trees",
    "collection":false
  }
}' \
https://default.iam.example.com/am/json/realms/root/realm-config/services/selfServiceTrees

Configure self-service policies

You can set up policies to determine how different features in self-service should behave, such as determining password requirements, or confirming that required fields have been filled out. Policies are configured in IDM. More information about using policies can be found in Use policies to validate data in the IDM documentation.

To configure which policies are applied:

Open the IDM admin UI, and select Configure > Managed Objects, then select the type of managed object you wish to configure (for example, User). This will take you to a list of properties which are part of that object type.
Select the property you wish to configure (for example, password), then click on the Validation tab. This will list any policies currently in place.
You can add, remove, or edit policies that are available in IDM. If you need to create a custom policy, see Extend the policy service in the IDM documentation. Note: creating custom policies is not available through the UI, though they can be set through the IDM admin UI once the policies have been created.

It’s possible to also set password policies within DS. If policies are set in both IDM and DS, make sure the policies match. If the DS password policy is more restrictive than the IDM policy, the user may get an error when updating their password, despite satisfying the policy set in IDM.

Configure email for self-service

The Email Template node and Email Suspend node make use of the email service in IDM. To use email in platform self-service, this will need to be configured.

To configure email:

Open the IDM admin UI, then select Configure > Email Settings.
If the email service is not yet enabled, select Enable. It will then prompt you to fill out the settings for the email service you intend to use. For more information about configuring email, see Configure outbound email in the IDM documentation.
Once email service is configured, set up the email templates used in self-service by selecting the Templates tab in Email Settings. There are five templates used in default self-service flows:
- Forgotten Username: Used in the Forgotten Username tree. When calling this template in a node, the template name is forgottenUsername.
- Registration: This template is not used in any of the example trees, but is available if you wish to configure registration to include email verification. When calling this template in a node, the template name is registration.
- Reset Password: Used in the Reset Password tree. When calling this template in a node, the template name is resetPassword.
- Update Password: This template is not used in any of the example trees, but is available if you wish to configure the Update Password to include an email step. When calling this template in a node, the template name is updatePassword.
- Welcome: This template is not used in any of the example trees, but is available if you wish to include a welcome email after the user is registered. When calling this template in a node, the template name is welcome.

It is possible to set up additional email templates according to your needs. For example, you may wish to set up an email notification when the user’s password is updated. This functionality is not currently available in the UI, however.

To create a new email template:

In your IDM conf/ directory, create a new file called emailTemplate-newTemplateName.json. For example, to send a password change notification when a user updates their password, create emailTemplate-changedPassword.json.

In the new file you created, add the template information. For example, if you wanted to create an changedPassword email template:

{
    "enabled" : true,
    "from" : "",
    "subject" : {
        "en" :  "Password Change Notification"
    },
    "message" : {
        "en" : "<html><body>Your password has just been changed.<br/> If you did not change your password, or believe you received this email in error, please contact Customer Support.</body></html>",
    },
    "defaultLocale" : "en",
    "mimeType" : "text/html"
}

Note that both subject and message are localized, and can include HTML tags allowed in HTML emails.

Once the template has been added, you can then reference the email template in your Email Template or Email Suspend nodes using the template name (in the above example, changedPassword).

The following nodes are associated with platform email services:

Email Suspend node: The Email Suspend node emails the user using an email template that you have configured in IDM. It then pauses the tree it is used in, until it receives a response from a link the email that was sent. This can be useful in cases of registration, where you wish to include an email verification step, or in a password reset flow, where you want additional verification before proceeding with the password reset.

When using this node, make sure the email template you are using includes a resume link, so the node can continue after the email is received. This is done using the {{object.resumeURI}} template variable.
Email Template node: The Email Template node emails the user using an email template that you have configured in IDM. Unlike the Email Suspend node, this node does not pause the tree. This makes it more useful for cases where you don’t need to wait for feedback from the user, such as a Welcome email, or when recovering a username.

There are two possible outcomes: either the email is successfully sent, or the email is not sent. An email might not be sent for different reasons, but most commonly because the email doesn’t exist on any known user. For security reasons, send both Email Sent and Email Not Sent the same response (Success).

ForgeRock Identity Platform 7.2