Getting started with ForgeRock Identity Cloud journeys: Part 3 - Twilio MFA journey with SMS or Voice OTP

rajeshr · July 12, 2023, 11:28am

This is Part 3 of 8 in the series Getting started with ForgeRock Identity Cloud journeys.

Twilio MFA journey with SMS or Voice OTP ~ 15 minutes

This guide requires an active account with Twilio. It includes steps on creating a free trial Twilio account and configuring it to Verify Service. For further information, please refer to Twilio’s official documentation.

Creating a free Twilio account

Go to https://www.twilio.com/try-twilio.
Complete all the required fields and click Start your free trial.
Verify the email address provided in the step above.
Enter a mobile number, when prompted, and click Send Verification Code.
Enter the verification code received to the phone. On the next page, complete the form using below information as reference:
- Which Twilio product are you here to use? SMS
- What do you plan to build with Twilio? Other
- How do you want to build with Twilio? With no code at all
- What is your goal today? Something else
Click Get Started with Twilio.
On the Twilio console, click Get a Twilio phone number.
The Account Info section on the Twilio console shows:
- Account SID [Required while configuring the journey in Identity Cloud]
- Auth Token [Required while configuring the journey in Identity Cloud]
- My Twilio phone number
gs_twilio_account_info1378×918 99.3 KB
On the Twilio console, click Explore Products + > Account Security > Verify > Create new.
Complete the form, using the following information as a reference:
- Friendly name: fridcloudvs
- Turn on SMS
- Click Next
- Do not select the Enable Fraud Guard option
- Click Continue and then click Save.
This creates a new service with auto generated SID. The Service SID is required while configuring the Twilio journey in Identity Cloud.

Building a journey that uses Twilio for SMS or Voice OTP for MFA

ForgeRock Marketplace has authentication nodes shared by the ForgeRock Community. You can also find some of these nodes in your Identity Cloud tenant under the ‘Marketplace’ category. This journey will be using the Twilio nodes from the Marketplace category.

On a supported browser, log into the Identity Cloud tenant URL.
On the Identity Cloud Admin UI alpha realm, Journeys > + New Journey.
Use the below information as a reference to complete the new journey form:
- Name: Twilio
- Identity Object: Alpha realm – Users managed/alpha_user
- Description: Journey that uses Twilio for MFA
Click Save.
Click and drag the following nodes from the Nodes list onto the canvas:
- Page Node
- Platform Username
- Platform Password
- Data Store Decision
- Twilio Identifier
- Twilio Verify Sender
- Twilio Verify Collector Decision
Drag the Platform Username into the Page Node and then drag the Platform Password node into the page node below Platform Username.
Connect the nodes to build the journey as shown in the screenshot below.

gs_twilio_journey1600×577 143 KB
Click on Twilio Identifier node and set the Identifier Attribute value to ‘telephoneNumber’.

gs_twilio_identifier_node478×780 61.4 KB
Click on the Twilio Verify Sender node and set the following node properties to the values from the Twilio console:
- Account SID
- Authentication Token
- ServiceSID
gs_twilio_verify_sender_node478×1268 81.9 KB
Click Save to save the journey.

Testing the ‘Twilio’ journey

In the Identity Cloud Admin UI alpha realm, go to Identities > Manage, and choose a user to test the authentication using the ‘Twilio’ journey. We will use ‘fruser2’ as an example.
In the ‘Telephone Number’ attribute, enter the mobile number including the country code. This is the mobile number that was verified with Twilio in the earlier steps.
Scroll down to the bottom of the page and click Save.
On the side navigation bar, click Journeys > Twilio. Copy the preview URL.
In a browser different from the Identity Cloud administrator active session, paste and go to the journey preview URL.
On the login page, enter the credentials of the user you chose in step 1, and click Next.

The login journey now expects a One-time Passcode (OTP).

An SMS OTP is sent the mobile number entered for the ‘Telephone Number’ attribute of the user.

gs_twilio_sms_number475×1026 71.3 KB
Enter the passcode at the OTP prompt and click Next.

gs_twilio_enter_otp1600×385 25 KB

On successful login, the end user dashboard is displayed.
Sign out of the end user dashboard.

Changing the journey to trigger Voice OTP

The ‘Twilio’ journey can be modified to send a Voice OTP instead of SMS OTP for MFA.

Log in to the Twilio console, go to the Verify Service, select the ‘fridcloudvs’ service and enable the Voice channel.

gs_twilio_service_settings1600×825 208 KB
Edit the ‘Twilio’ journey in Identity Cloud, select the Twilio Verify Sender node, and change the node property channel to CALL.

gs_twilio_verify_sender_node_call472×1194 76.3 KB
Repeat the test process to verify the changes made to the journey work as expected. This time, a call will be received on the phone number instead of an SMS.