How to Send Templated Emails in ForgeRock Identity Cloud

darinder · November 2, 2023, 5:04pm

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.

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

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.

From the ForgeRock Administrative Platform UI, navigate to Journeys > Click the ellipsis next to the default Login Journey > Duplicate > Call the new Journey HOTPViaEmailService
Configure it as follows. Note the Increment Login Counter and Progressive Profiling Inner Journey have been removed to simplify the flow - add if required:

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.

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.

Copy the preview URL and keep it handy, we’ll need it soon.

Execution

To test the flow complete the following steps:

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.
Call the URL stored from step 3 above e.g:

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

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:

Non templated email

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:

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!