Platform configuration

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.

For details, refer to:

Configure self-service endpoints

AM includes a service to map journeys to endpoints in self-service. To reach this service in the AM admin UI, 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 journey for registering devices, you could create a journey 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.

The platform End User UI depends on the journeys mapped through the Self Service Trees service for self-service options:

Configure a connectSocial journey to let users connect to social identity providers through their profile page.
Configure an updatePassword journey to let users reset their password through their profile page.

To delete an existing endpoint over REST, call this service’s endpoint to update the treeMapping object. The following example updates 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://platform.example.com:8443/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. For details, refer to Use policies to validate data.

Configure which policies apply

Open the IDM admin UI, and select Configure > Managed Objects, then select the type of managed object you want to configure, such as User. This will take you to a list of properties which are part of that object type.
Select the property you want to configure, such as 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. To create a custom policy, refer to Extend the policy service.

You cannot create custom policies through the UI, but you can set them through the IDM admin UI after creation.

It is also possible to configure password policies in 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, you must configure the email service.

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, refer to Configure outbound email.
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 journeys:

Forgotten Username

Used in the Forgotten Username journey. When calling this template in a node, the template name is forgottenUsername.

Registration

This template is not used in any of the example journeys, but is available if you want 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 journey. When calling this template in a node, the template name is resetPassword.

Update Password

This template is not used in any of the example journeys, but is available if you want to configure the Update Password journey 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 journeys, but is available if you want 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 want to set up an email notification when the user’s password is updated. This functionality is not currently available in the UI, however.

Create an 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 you add the template, you can then reference the email template in your Email Template node or Email Suspend node using the template name.

In the preceding example, this is 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 journey 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 want to include an email verification step, or in a password reset journey, 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 journey. 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: the email is successfully sent, or the email is not sent. An email may not be sent for different reasons, but the most common reason is that 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.5