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.

This blog post was first published @, included here with permission from the author.

It’s The Little Things – Part 1

Since I began working with the ForgeRock technology I have been impressed by how much you can do with it in a very short time and from what I have seen this is really underpinned by an philosophy of developer friendliness. There are lots of small features throughout the platform that are solely there to make life for implementors and developers easier.

In this series I wanted to take the opportunity to call out some of these little things that can make a big difference to your day to day experience.

Simulated Attribute Mapping

One of my favourite features in OpenIDM. Say you need to create provisioning integration with a target system. More often than not you need to manipulate or transform source attributes to achieve this.

Below you can see I have created a mapping to Active Directory in OpenIDM. This is a fairly common requirement that comes up time and again. Among other attributes, when you create an Active Directory account you need to define a Distinguished Name (DN).

I have configured the following script to generate a DN:

This is fairly simple, it just takes the userName of the user in OpenIDM and appends the rest of the desired DN as a fixed string. This is all fairly standard stuff. What is really useful, is that I can simulate the output of my DN transformation before I actually provision any accounts. To do this you just need to select an existing OpenIDM user using the Sample Source feature:

You can now see what the target output will actually look like for a given user. This is a really handy timesaver if you need to write complex mappings and enables you to quickly get a feel whether or not your transformation is correct before you have to go back and forth with failed provisioning operations against Active Directory.

This blog post was first published @, included here with permission from the author.