It’s The Little Things – Authentication Chains

Authentication Chains

We have not talked much about OpenAM on the blog. AM has some really great features that make it very simple to use. Perhaps my favourite feature is the authentication chains UI.

Let’s take a quick look at what an authentication chain looks like, then we will talk through it and have a go at creating a brand new one. I assume you are using OpenAM 13.

You can see what an auth chain looks like above. Essentially it is a series of steps ( I think of them as Lego like building blocks ) for authentication. Each block represents a different mechanism for authenticating. In addition each block is also assigned one of four authentication behaviors (required, optional, requisite & sufficient) which determine how ( and if ) one block flows into the next depending whether that block succeeds.

As stated above, successful authentication required at least one pass and no fail flags.

In the above example there are four blocks, lets look at each in turn:

  • DataStore: Basic username and password authentication against the OpenAM data store. If this step is a:
    • FAIL: The user hasn’t even got their username and password right. We definitely are not letting them in, and as such exit the chain with a FAIL.
    • PASS: The username and password is correct. We move to the next block in the chain DeviceMatch.
  • DeviceMatch: First step of device match authentication ( essentially asking the question: has OpenAM seen the use log in from this device before? ). If this step is a:
    • CONTINUE: OpenAM has not seen the user log in using this particular laptop or mobile before. This block has failed but, because it is sufficient this does not equate to a fail flag. We have to be a bit more suspicious and go into the TwoFactor block.
    • PASS: This is a device the user has used before and OpenAM recognises it. At this point the user has authenticated with username and password from a recognised device. We exit the chain with a PASS. 
  • TwoFactor: Challenge the user to provide the code from a two factor mobile soft token. This second factor proves that not only does the user have the right username and password, but also that they have the mobile device they originally registered with in their possession. If this step is a:
    • FAIL: The user has failed 2FA. At this point we don’t have the confidence this is really the user being claimed and exit with a FAIL.
    • PASS:
  • DeviceSave: The last step of device match authentication. We save a record of the device so we can match it next time in the DeviceMatch step. If this step is a fail:
    • FAIL: The user is not actually being challenge for anything. Authentication is complete. We just need to save the device which will not fail.
    • PASS: We have now saved the device, in future, so long as the user continues to use this particular laptop or mobile to login. They will not have to do the TwoFactor step.

Note that I have chosen the above authentication “blocks” for this particular blog. I could easily have used others. There are many different types of blocks available in OpenAM covering nearly every conceivable authentication requirement.

I think the way OpenAM allows you to quickly use these building blocks to build authentication visually is really neat.

Let’s now try building the above chain in OpenAM.

Building an Authentication Chain

Firstly we need to create the authentication building blocks we want. I am going to assume you have an installation of OpenAM up and running with a Top Level Realm configured ( though you can do this any realm ).
Select the realm:
And navigate to Authentication, then Modules.
Out of the box the above modules are configured. We need to configure a few more.
Press Add Module, select “Device Match” from the drop down and give it a name ( I used DeviceMatch earlier ).
Press Create and you should see the configuration screen:
The defaults are fine here, just press Save Changes.
Now repeat the last two steps for the Device Id ( Save ) and ForgeRock Authenticator (OATH) modules.
When this is done you should have the following modules:
Now we need to create a new authentication chain. Navigate to Authentication, then Chains.
Press Add Chain, and give it a name ( I used secureAuthService above ) then press Create, you will now have an empty authentication chain.
Now just Add Module‘s. You don’t have to worry about the order, just add all the modules as in my example at the start of this blog:
If you get the order wrong, don’t worry about it! Just drag and drop authentication blocks to move them around. Ensure you have set the Criteria as follows:
DataStore: Requisite
DeviceMatch: Sufficient
TwoFactor: Requisite
DeviceMatch: Required
Save Changes and you are done. That’s all there is to it!
Not quite… there is one additional step I want to do here. By default Two Factor is optional for end users. In some cases that is desirable, it’s an additional security control and if you are big retailer you don’t want to force it on users but you do want it to be an option for them.
However in this demo, I want to make it mandatory to do so, navigate to Authentication, Settings, then General and check the Two Factor Authentication Mandatory box.
Then Save Changes.

Testing the Authentication Chain

So how do we test the authentication chain? Well, remember we named it secureAuthService? Let’s try logging in using the following URL:
Then try entering the standard demo and changeit credentials.
You would normally be logged into OpenAM at this point, however instead, you should see the following:
This is the DeviceMatch module doing it’s work. Make sure to press Share Location.
Note: this is just a default and that capturing location is optional.
As this is the first time I am logging in using this device. I need to use the ForgeRock authenticator as a second factor.
Note: for this explanation I have already download the ForgeRock authenticator from the Apple App ( or Google Play ) stores. I have also already registered it with OpenAM. The first time you do this you will be asked to register and need to take a photo of a QR code in OpenAM. This is relatively straight forward but feel free to leave questions in the comments.
I now enter the code generated by the ForgeRock authenticator on my phone, and assuming I get that right and press SUBMIT. I am then asked if I want to trust this device ( the laptop I am logging in from ) and to give it a name:
After which I am successfully logged into OpenAM!
Now, if you try logging out and back in. You won’t be challenged for 2FA authentication! So long as you are using the same laptop.
One more thing. If you log in again and navigate to DASHBOARD, you can see the trusted profile for your Laptop and the 2FA token. If you want you can delete the trusted profile, at which point OpenAM no longer knows about your laptop and will challenge you for 2FA again.
Authentication chains are really easy to understand and configure, and incredibly powerful.

Comments are closed.

  1. johns 6 years ago


    Thanks for the tutorial. I am wondering whether it is possible to pass a parameter value from one module to another in a chain. For instance, we can acquire userid in the first module, I need to use this one for further process in the third module. is it doable?


  2. johns 6 years ago

    Hi, Wayne,

    Never mind, I just discovered that the parameters are passing via sharedState parameter in customized authentication module.

©2022 ForgeRock - we provide an identity and access platform to secure every online relationship for the enterprise market, educational sector and even entire countries. Click to view our privacy policy and terms of use.

Log in with your credentials

Forgot your details?