Identity Cloud

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.

To delete an existing endpoint, 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://[.var]##<tenant-env-fqdn>##/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.

Configure which policies apply

  1. 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.

  2. Select the property you want to configure, such as password, then click on the Validation tab. This will list any policies currently in place.

  3. You can add, remove, or edit policies that are available in IDM.

    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

  1. Open the IDM admin UI, then select Configure > Email Settings.

  2. 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 Outbound email.

  3. 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

  1. 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.

  2. 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.

  3. 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).

Copyright © 2010-2022 ForgeRock, all rights reserved.