How to Send Templated Emails in ForgeRock Identity Cloud

Setup
, , , , , , , ,
1

How to Send Templated Emails in ForgeRock Identity Cloud

By Darinder Shokar
Originally posted on https://medium.com/@darinder.shokar

Sending HMAC-based One-time Passwords (HOTPs) via email is common for scenarios like verifying a user’s email address as part of the registration journey, or during forgotten credential journeys. In this blog we’ll go through how to do this in ForgeRock Identity Cloud along with the option of applying a template to the outbound email for personalisation and a better user experience.

Prerequisites

  • ForgeRock Identity Cloud now supports Service Accounts to access ForgeRock APIs using a secure, scoped standards based OAuth2 Access Token generated using the JWT Bearer grant type. The prerequisite step is to configure a service account and a Scripted Decision Node to acquire a an OAuth2 Access Token using this account, follow this ForgeRock Knowledge Base for steps on how.

Deploy Scripts

The following steps will deploy two scripts:

  • send-hotp-platform-email-service — Uses the platform Email Service to send a non-templated HOTP with the SMTP Service

  • send-templated-hotp-platform-email-service — Uses the platform Email Service to send a templated HOTP with the SMTP Service

These scripts acquire the _id value of a user, checks for the presence of a service account access token, oneTimePassword and mail attribute, before issuing an API call to the Platform Email Service to send the HOTP via the SMTP Service. The templated script, references a templateID to send out templated emails.

  1. Ensure the pre-requisite step is completed which creates a Service Account, Environment Secrets and Variables (ESVs) and Scripted Decision Node to generate an fr:idm* scoped OAuth2 Access Token to access backend ForgeRock APIs.

  2. From the ForgeRock Administrative Platform UI, navigate to Scripts > Auth Scripts > Select New Script > Journey Decision Node > Next > Provide a name of New Script > Provide a name of send-hotp-platform-email-service > Description of Sends a HOTP via the Platform email service > copy the script from here and hit Save and Close

  3. Repeat step 2 but this time call the script send-templated-hotp-platform-email-service with a description of Sends a templated HOTP via the platform email service and copy and paste the script from here.

It should be noted that in Production the default SMTP Service should be replaced with your own via this guide.

Configure An Email Template

Configure a sample email template using these instructions. The key points are:

  • The template id is configurable but set it to otp to use the variable defined in the script.
  • {{object.givenName}} and {{object.otp}} must be defined to pass the first name and HOTP value to the email service.

See sample_template.txt from here for example content. It looks like this:

image
image1400×732 90.4 KB

Example Email Template Configuration

Build A Journey

Now all the configuration is in place, we can use the drag and drop power of ForgeRock Orchestration Journeys to put all this together. For this example I’ll just configure a basic authentication flow which requires successful verification of a HOTP sent via email, but the flows can be modified for Registration and Forgotten Credential journeys too.

  1. From the ForgeRock Administrative Platform UI, navigate to Journeys > Click the ellipsis next to the default Login Journey > Duplicate > Call the new Journey HOTPViaEmailService

  2. Configure it as follows. Note the Increment Login Counter and Progressive Profiling Inner Journey have been removed to simplify the flow - add if required:

image
image1400×583 75.9 KB

HOTP Journey

Key Points:

  • The Get IDM Access Token to Access ForgeRock APIs is a scripted decision node based on the pre-req KB which requires the outcomes to be set to success and error

  • The Identity Existing User node requires the Identifier to be set to userName and Identity Attribute set to userName. This ensures attributes can be retrieved for a user from the idRepository based on the _id value

  • The Send HOTP Via Platform Email Service and Send Templated HOTP Via Platform Email Service nodes are scripted decision nodes which require the outcomes to be set to sent noMail and error

  • The OTP Collector Node has also been placed in a Page Node to provide more context to the end user as they enter their OTP.

image
image1400×1516 126 KB

OTP Collector Decision Node within a Page Node Configuration

  • To switch between sending a HOTP with or without the template connect the HOTP Generator node to Send HOTP Via Platform Email Service or Send Templated HOTP Via Platform Email Service respectively.
  1. Copy the preview URL and keep it handy, we’ll need it soon.

Execution

To test the flow complete the following steps:

  1. From the ForgeRock Administrative Platform UI, goto Identities > Manage > New Alpha realm — User to create a new user. Be sure to set a email and password.
  2. Call the URL stored from step 3 above e.g:

https://<TENANT>/login/?realm=/alpha&authIndexType=service&authIndexValue=HOTPViaEmailService#/

  1. After entering the username and password if the Send HOTP Via Platform Email Service node is used an email like this will return and on successful entry login will succeed:

image
image1400×260 57.4 KB

Non templated email
  1. From the Journey connect HOTP Generator to Send Templated HOTP Via Platform Email Service save the Journey and call again. Re-enter the username and password but this time a templated email like this will return:

image
image1400×1137 149 KB

Templated Email

Conclusion

There you have it, an example of how to send HOTPs using the feature rich capabilities of the ForgeRock Identity Cloud Platform.

For even faster deployment import from the ForgeRock Admin UI > Journeys, import this Journey to re-create the Journey with associated scripts. Just the pre-req steps, the template creation step and user creation step are then required to everything working ;)

Thanks for reading!

1 Like
2

When using this during a registration journey where the user does not yet exist in the identity repository, the objectAttributes must be retrieved into a variable then retrieve the attribute values from the variable object. Example:

/**

  • Node entry point
    */

logger.message(config.nodeName + “: node executing”);

var username;
var accessToken;
var idmEndpoint;
var hotp;
var mail;

logger.error(config.nodeName + ": sharedState - " + nodeState.get(“objectAttributes”));
var objAttributes = nodeState.get(“objectAttributes”);

/*
if (!(username = nodeState.get(“_id”).asString())) {
logger.error(config.nodeName + “: Unable to retrieve username from sharedState”);
outcome = NodeOutcome.ERROR;
}
*/

if (!(accessToken = nodeState.get(config.ACCESS_TOKEN_STATE_FIELD).asString())) {
logger.error(config.nodeName + “: Unable to retrieve Access Token from transientState”);
outcome = NodeOutcome.ERROR;
}

else if (!(fqdn = systemEnv.getProperty(config.tenantFqdn))) {
logger.error(config.nodeName + ": Unable to retrieve tenant from ESV called: " + config.tenantFqdn);
outcome = NodeOutcome.ERROR;
}

else if (!(hotp = nodeState.get(“oneTimePassword”).asString())) {
logger.error(config.nodeName + “: Unable to retrieve HOTP from transientState”);
outcome = NodeOutcome.ERROR;
}

//If this is a registration journey adapt the following to try retrieve from sharedState
else if (!(mail = objAttributes.get(“mail”))) {
logger.error(config.nodeName + “: Unable to retrieve mail attribute from the sharedState”);
outcome = NodeOutcome.FAIL;
}

//If this is a registration journey adapt the following to try retrieve from sharedState
else if (!(givenName = objAttributes.get(“givenName”))) {
logger.error(config.nodeName + “: Unable to retrieve givenName attribute from the sharedState”);
outcome = NodeOutcome.FAIL;
}