QRCode login with ForgeRock Identity Cloud

6 min readFeb 23, 2022

If you’re using WhatsApp, maybe you’re also using their desktop app or the web interface (https://web.whatsapp.com/). When you access this web interface, the page is displaying a QRCode you have to scan with your phone to login. This user journey is fluid, easy and password-less; exactly what we want as a user. Let’s see in this post how you can do this with ForgeRock Identity Cloud.

How it works

QR Code login is a use case where the user is authenticated on a mobile device or has registered a mobile device as Trusted and wants to login to the application from another device. In this situation the user will enter his login and then a QR Code will be displayed on the screen and he’ll have to scan it with his Trusted device (or the device where he is already authenticated) to authenticate. This password-less use case is more and more common and doesn’t necessarily need a mobile app to work. The figure below presents the sequence in a sequence diagram.

How to configure it in ForgeRock

The ForgeRock Identity Platform has a great and powerful user journey designer called Intelligent Access. We will use this no-code/low-code designer to create our 2 journeys. The first journey will be the one the user will use from his web browser and the second will be the one used by the user with his mobile phone. The following figure shows these 2 trees in the sequence diagram.

Browser Tree step by step configuration

This first tree (orange in the previous figure) will generate a token, store it in user profile, display a QRCode to scan with the mobile phone of the user and wait until the token has been validated by the user with the Mobile Tree.

Now, connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

Create a script to generate the token:

Select your realm (default is alpha), browse to Scripts and click on New Script to create a new one and choose a Journey Decision Node type,
On the script creation page, name your script GenerateToken,
In the script field enter the following code and click on Save Changes.

Create another script to display the QRCode:

Select your realm, browse to Scripts and click on New Script to create a new one and choose a Journey Decision Node type,
On the script creation page, name your script displayQRCode,
In the script field enter the following code and click on Save Changes.

Create the Browser Tree to start the QR Code Login.

Select your realm, browse to Journeys and click on New Journey to create a new one called QRLogin for Identity Object Alpha realms - User,
Add a Patch Object node, name it Clean Profile and link Patched and Failed outputs to Failure exit (red circle icon),
Add a Scripted Decision node, name it Display QRCode, select displayQRCode script, add true and false outcomes, link true to Success exit (green circle icon) and false with the Clean Profile node,
Add a Patch Object node, name it Token In Profile and link Patched output to Display QRCode node, Failed outputs will be linked later,
Add a Scripted Decision node, name it Generate Token, select GenerateToken script, add true outcomes, link true to Token In Profile node,
Add an Identify Existing User node, link true output to Generate Token node and False output to Failure exit (red circle icon),
Add a Platform Username node in your tree, link it to Identify Existing User node and link the Start (blue circle icon) to this node,
Finally, link the Failed output from the Token In Profile node to Platform Username node.

At the end your tree should look like the following tree.

QRCodeLogin journey in ForgeRock Identity Platform

Mobile Tree step by step configuration

This second tree (green in the sequence diagram figure) will check if the device of the user is trusted and then check if the token is valid. If the token is valid, then it’ll remove the token from the user profile (allowing the previous tree to exit in success).

Now, connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

Create a script to retrieve the token from the request:

Browse to Scripts and click on New Script to create and choose a Journey Decision Node type,
On the script creation page, name your script getQRCode,
In the script field enter the following code and click on Save Changes.

Create a script to check the validity of the token:

Browse to Scripts and click on New Script to create and choose a Journey Decision Node type,
On the script creation page, name your script checkQRCodeToken,
In the script field enter the following code and click on Save Changes.

Create the Mobile Tree to validate the QRCode access.

Browse to Journeys and click on New Journey to create a new one called UnlockWithQR for Identity Object Alpha realms — User,
Add a Failure URL node in your tree and link the output to the Failure exit (red circle icon). In the Failure URL parameter, enter /.
Note: this node is used to redirect the user to a page saying that the access is validated. In this note I just redirect the user to the default login page but it can be any page you want (even Google if you want).
Add a Patch Object node, name it Clean Profile and link Patched and Failed outputs to Failure URL node,
Add a Scripted Decision node, name it check Token, select checkQRCodeToken script, add true and false outcomes, link true to Clean Profile node and false to Faillure URL node,
Add a Device Match node, link True output to check Token node andFailed and Unknown Device outputs to Failure URL node,
Add an Identify Existing User node, link true output to Device Match node and False output to Failure URL node,
Add a Scripted Decision node, name it get QRCode, select getQRCode script, add true outcomes, link true to Identify Existing User node,
Add a Device Profile Collector node, link it to get QRCode node.

At the end your tree should look like the following tree.

QRCode validation journey in ForgeRock Identity Platform

Demonstration

The next figure shows the result in action from the user perspective.

Important note: This scenario is only possible if you pre-associated your mobile phone with your ForgeRock account as a Trusted device.

Conclusion

This step by step configuration of a QR Code login with ForgeRock Identity Cloud is part of a series of blog notes where I show how to use ForgeRock’s Intelligent Access engine to configure cool user journeys. If you’re interested you can read theses two other blog notes : Unlock Pattern with ForgeRock Identity Cloud & Magic links with ForgeRock Access Management.

To strengthen this implementation, I recommend enriching these two user journeys with the use of persistent cookies or adding authentication mechanism in the Mobile tree.