Unlock Pattern with ForgeRock Identity Cloud

5 min readJul 9, 2021

A few weeks ago a customer asked me if we can do schema authentication with ForgeRock Identity Cloud. You don’t know what it is? I didn’t know either before I was asked by this customer. This is most commonly named Unlock Pattern and if you use and Android mobile phone you may use it to unlock your screen. In this article, we’ll see what it is and how to do this with ForgeRock Identity Cloud. It’ll be a great opportunity to understand how authentication journeys work in ForgeRock and how to use ScriptTextOutputCallback in Javascript decision nodes.

Unlock Pattern

Unlock Pattern authentication is a mechanism used to authenticate a person with a login and a schema drawn on the screen by the user. This is common on some mobile phone to unlock the screen. This figure shows an example of an Unlock Pattern screen.

Note: this screenshot comes from the Unlock pattern javascript example available here : http://jsfiddle.net/ChfGh/6/

Authentication journey with Unlock Pattern

How it will work

To create an authentication journey with an Unlock Pattern we wi use the Intelligent Access feature of the ForgeRock Identity Cloud Platform. This feature is a designer where you can define the workflow your user will go through when he authenticates. This drag and drop designer comes with a large set of out-of-the-box functionalities : username/password collector, FIDO2 support, Push authentication, OTP, … In some cases you may want more specific function; in this situation you case use Javascript extensions. We will use this scripting functionality to display the Unlock pattern screen, translate the pattern into a sequence number and check it with the password. The following figure shows a sequence to explain how it will work.

Sequence of the authentication journey with Unlock Pattern

Note: in this schema UI is the End-User Interface and IA is the Intelligent Access engine of the ForgeRock platform.

In this blog we will consider you have access to a tenant of ForgeRock Identity Cloud or a ForgeRock Identity Cloud platform deployed locally.

Create the journey

First we will duplicate the default Login journey and test it:

In the platform-ui, browse to the Journey menu, click on the 3 dots on the right raw of Login and click on Duplicate.
In the popup name the duplicated tree : “LoginWithSchema” and enter the description you want.
Now, in the list of Journeys you should see your journey “LoginWithSchema”, click on it.
In the section detailing the tree, copy the Preview URL.
Then open a new browser (or the same but with a separate session) and past the URL you just copied (it should be something like this: https://<YOURTENANT>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=LoginWithSchema) and that’s it you are using your new journey (which is exactly the same as the default one for now)!

Detail of the LoginWithSchema (step3 &4) Journey with the Preview URL

Now that we have our new journey we will modify it to use Javascript to extend the features.

Insert a Scripted Decision node with a PasswordCallback

In this step, we will add a scripted decision node to be able to use Javascript to extend the functionalities of the solution. For now, this script will be used to display a classical password input field. We will do this using PasswordCallback.

Login to ForgeRock platform-ui, browse to the Journey menu and click on “LoginWithSchema”.
In the section detailing the journey, click on the journey preview (an Edit button will appear). the Intelligent Access designer will display.
In the left menu search the node “Platform Username” and drag it into the main page of the designer.
Link the blue Start box to the “Platform Username” node.
In the left menu search the node “Scripted Decision” and drag it into the main page of the designer.
Link the “Platform Username” node to the “Scripted Decision” node.
Configure the Scripted node with the following informations:
Name: SchemaPassword
Output: true
Clic on “Save”, and that’s it your tree is ready.

The last thing to do is to create the script and insert it into the tree.

Re-open the “LoginWithSchema”journey.
Select the SchemaPassword “Scripted Decision” node and in the parameter part of the node, clic on the “+” button to create a new script.
In the windows enters the following informations:
Name: SchemaScript
Description: A JS Script used to display a screen allowing for schema authentication
Javascript: Copy/paste the code below
Click on “Save” to save the tree and “Save” to save the modification on the journey.

Below, the code to copy/paste in the SchemaScript:

Note: This code just use a PasswordCallback to display a password input field, retrieve the value and put it into the transientState. Then the “Data Store Decision” node checks the username and password correspondance.

At this stage we have a simple tree that does and authentication with login and password BUT the super-cool thing is that we displayed the password input field with a scripted node. See below the end-user experience.

Add a ScriptTextOutputCallback to display the unlock pattern

Now that we’ve seen how to use interactive call back with a script, we will use a ScriptTextOutputCallback to load a Javascript on the client-side. This Javascript is highly inspired by this one http://jsfiddle.net/ChfGh/6 created by Shmiddty. Note that I tested this script only with Chrome.

Re-open the “LoginWithSchema”journey.
Select the SchemaPassword “Scripted Decision” node and in the parameter part of the node, clic on the “pen” icon right to SchemaScript in the Script dropdown list.
In the windows enters the following informations:
Javascript: Copy/paste the code below
Click on “Save” to save the tree and “Save” to save the modification on the journey.

Below, the code to copy/paste in the SchemaScript:

Demo

Now you should have a journey that uses an Unlock Pattern instead of a password. To test it, just goo to this url : https://<YOURTENANT>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=LoginWithSchemaThe following figures shows and example of the result.

Unlock Pattern with ForgeRock Identity Cloud

Conclusion

In this post we’ve seen a quick and funny example of what can be done with a few lines of Javascript and the ForgeRock Identity Platform. I hope you enjoyed it and that it’ll help you in your projects!