ForgeRock Authenticator (OATH) in ForgeRock OpenAM 13

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

If you’re in possession of a Smart Phone that runs either the Apple iOS or Android, you may probably be interested to know that the ForgeRock’s newer version of its Access Management solution now has an Authenticator App for you. Once installed and the device registered with ForgeRock OpenAM 13, one could use this Mobile App to generate One Time Password to validate his/her identity and thereby gain access to resources protected by the OpenAM. Needless to add, the ForgeRock Authenticator Mobile App is available on Apple iTunes Store for the iOS users and the Google Playstore for the Android fans.

Once installed, you’ll see on your phone something close to what is in the picture below:

Here’s what I did with my copy of ForgeRock Authenticator App on my iPhone:

– Configured an Authentication Chain ‘myAuthChain’ in my OpenAM 13 instance
– The said chain consisted of two Authentication Modules namely DataStore & ForgeRock Authenticator (OATH)
– When a subject authenticates against the ‘myAuthChain’ Authentication Chain in OpenAM, he/she is prompted for the DataStore credentials (an embedded OpenDJ instance), which on success is followed by another prompt where the user can register his/her device (using QR Code), generate an OTP that can be used to gain access to the resources protected by OpenAM.


If you are interested to see all of this in action, please spare five minutes to watch the video below.


Related documents/videos:
ForgeRock Documentation
Smart Security Using Phone App Demo

ForgeRock OpenAM Multi Factor Authentication Using Adaptive Risk Authentication Module & OTP

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

In this episode, you’ll see ForgeRock OpenAM’s two factor authentication feature employing it’s Adaptive Risk Authentication Module instance and HOTP module instance

So in the video demonstration that follows this post, you’ll see a user attempting to login against an Authentication Chain (say ‘MyAuthChain’) which has three module instances namely (i) Data Store, (ii) Adaptive Risk and (iii) HOTP. If the user is able to supply the right credentials against the Data Store, he or she is allowed in without any further challenge. On the other hand, if the the attempt to authenticate against the first Module instance (Data Store) fails, then the user is prompted for additional credentials like One Time Password.

The following illustration might give a rough idea on the what’s discussed above and the video that follows might make it pretty clear.



Customer Data: Convenience versus Security

Organisations in both the public and private sector are initiating programmes of work to convert previously physical or offline services, into more digital, on line and automated offerings.  This could include things like automated car tax purchase, through to insurance policy management and electricity meter reading submission and reporting.

Digitization versus Security

This move towards a more on line user experience, brings together several differing forces.  Firstly the driver for end user convenience and service improvement, against the requirements of data security and privacy.  Which should win?  There clearly needs to be a balance of security against service improvement.  Excessive and prohibitive security controls would result in a complex and often poor user experience, ultimately resulting in fewer users.  On the other hand, poorly defined security architectures, lead to data loss, with the impact for personal exposure and brand damage.

Customer Confidence, Brand Damage & Ethics 

Any on line service, needs to provide a layer of confidence to the end user.  The delivery of on line government services for example, could require the collection and storage of deeply personal data such as social security numbers, dates of birth, previous postal addresses, car registration details, health care numbers and so on.  Data, that in the wrong hands, could lead to a proliferation of identity fraud.

A flip side to distilling confidence in the end user, that their personal identifiable information (PII) is being kept secure, is that if (and when) a breach occurs, the potential damage to the service provider will be significant.

An ethical question is also raised - how will the data submitted by an end user be actually used? Initially, there has to be an "exchange of wants", when personal information is asked for.  For example, what does the end user get in return for revealing their email address, data of birth or address?  There has to be a service improvement, increased convenience aspect or price reduction, to make the exchange of information worth while.  But once that exchange has been implicitly agreed upon, the service provider then has an ethical duty to manage that data in accordance to transparent conditions published to the end user.  This would include the redistribution or selling of that data to third parties.

Customer Data Storage - Repositories, Hashes & Migration

There are clearly several physical requirements to how data is transferred and storage.  The use of transport level encryption (SSL/TLS) is a given, as is the symmetric encryption of sensitive data. Password data should be stored using a well known and modern hashing algorithm, possibly along with a salt.

End user or customer data is likely to exist in several different internal service provider repositories, with varying levels of detail.  Customer relationship management (CRM) systems are popular as are marketing and analytics databases, especially in the e-commerce world.  Other authoritative sources of data are likely to exist, most likely in large scale relational databases, with master data management and reporting services integrated into them.  That data may well need to be migrated into a new, highly scalable and highly available directory, possibly after consolidation and data cleansing activities have taken place.

Identifying High Risk Users - Device Printing & OTP

From a service provider perspective, once data has been securely captured and stored, there often needs to be a level of risk analysis integrated into the user login journey.  This can help to identify users of high risk - such as those accessing with stolen credentials or devices or users that have registered with fraudulent details.

Contextual login processes can help here.  This refers to things like identifying trusted networks or devices and mixing with environmental factors such as time.  The key is to identify high risk, then act upon it - perhaps by reducing that users capabilities within the service, or making them go through more rigorous levels of assurance, such as having to supply a one time password (OTP) via a token, mobile or email address.

Frictionless Signup & Login

The introduction of new digital services is a complex process.  Even if the security architecture has been agreed upon and implemented effectively, it cannot interfere with the end user journey from both a signup and login perspective.  Most users now assume a one-click style approach to registration - perhaps through the re-use of social media credentials.  The login approach needs to be equally simple, and seamless across a range of different platforms and devices, from laptops, mobile and tablets.

As more and more organisations go through digital transformation programmes, there needs to be a fine balance between end user convenience and security, that benefits and protects, not only the service provider, but the end user too.

By Simon Moffatt

One-Time Passwords – HOTP and TOTP

About One-Time Passwords in general

One-Time Passwords (OTP) are pretty much what their name says: a password that can be only used one time. Comparing to regular passwords OTP is considered safer since the password keeps on changing, meaning that it isn’t vulnerable against replay attacks.

When it comes to authentication mechanisms, usually OTP is used as an additional authentication mechanism (hence OTP is commonly referred to as two factor authentication/second factor authentication/step-up authentication). The main/first authentication step is still using regular passwords, so in order your authentication to be successful you need to prove two things: knowledge and possession of a secret.

Since the OTP is only usable once, memorizing them isn’t quite simple. There is two main way of acquiring these One-Time Passwords:

  • hardware tokens: for example YubiKey devices, which you can plug in to your USB port and will automatically type in the OTP code for you.
  • software tokens: like Google Authenticator, in this case a simple Android application displays you the OTP code which you can enter on your login form.

There is two main standard for generating One-Time Passwords: HOTP and TOTP, both of which are governed by the Initiative For Open Authentication (OATH). In the followings we will discuss the differences between these algorithms and finally we will attempt to use these authentication mechanisms with OpenAM.

Hmac-based One-Time Password algorithm

This algorithm relies on two basic things: a shared secret and a moving factor (a.k.a counter). As part of the algorithm an HmacSHA1 hash (to be precise it’s a hash-based message authentication code) of the moving factor will be generated using the shared secret. This algorithm is event-based, meaning that whenever a new OTP is generated, the moving factor will be incremented, hence the subsequently generated passwords should be different each time.

Time-based One-Time Password algorithm

This algorithm works similarly to HOTP: it also relies on a shared secret and a moving factor, however the moving factor works a bit differently. In case of TOTP, the moving factor constantly changes based on the time passed since an epoch. The HmacSHA1 is calculated in the same way as with HOTP.

Which one is better?

The main difference between HOTP and TOTP is that the HOTP passwords can be valid for an unknown amount of time, while the TOTP passwords keep on changing and are only valid for a short window in time. Because of this difference generally speaking the TOTP is considered as a more secure One-Time Password solution.

So how does OpenAM implement OTP?

In OpenAM currently there is two authentication module offering One-Time Password capabilities: HOTP and OATH. So let’s see what is the difference between them and how to use them in practice.

HOTP authentication module

The HOTP module – as you can figure – tries to implement the Hmac-based One-Time Password algorithm, but it does so by circumventing some portions of the specification. Let me try to summarize what’s different exactly:

  • The shared secret isn’t really shared between the user and OpenAM, actually it is just a freshly generated random number, each HOTP code will be based on a different shared secret.
  • The moving factor is statically held in OpenAM, and it just keeps on incrementing by each user performing HOTP based authentications.
  • A given HOTP code is only valid for a limited amount of time (so it’s a bit similar to TOTP in this sense).

These differences also mean that it does not work with a hardware/software token since the OTP code generation depends on OpenAM’s internal state and not on shared information. So in order to be able to use the generated OTP code, OpenAM has to share it somehow with the user: this can be via SMS or E-mail or both.

So let’s create an example HOTP module using ssoadm:

openam/bin/ssoadm create-auth-instance --realm / --name HOTP --authtype HOTP --adminid amadmin --password-file .pass

Now we have an HOTP module in our root realm, let’s configure it:

openam/bin/ssoadm update-auth-instance --realm / --name HOTP --adminid amadmin --password-file .pass -D

Where contains:


NOTE: The names of the service attributes can be found in the OPENAM_HOME/config/xml/amAuthHOTP.xml file.

At this stage I’ve modified the built-in demo user’s e-mail address, so I actually receive the OTP codes for my tests.

Last step is to create an authentication chain with the new HOTP module:

openam/bin/ssoadm create-auth-cfg --realm / --name hotptest --adminid amadmin --password-file .pass
openam/bin/ssoadm add-auth-cfg-entr --realm / --name hotptest --modulename DataStore --criteria REQUISITE --adminid amadmin --password-file .pass
openam/bin/ssoadm add-auth-cfg-entr --realm / --name hotptest --modulename HOTP --criteria REQUIRED --adminid amadmin --password-file .pass

Here the first command created the chain itself, the other two commands just added the necessary modules to the chain.

We can test this now by visiting /openam/UI/Login?service=hotptest . Since I don’t like to take screenshots you just have to believe me that the authentication was successful and I’ve received my HOTP code in e-mail, which was in turn accepted by the HOTP module. :)

OATH authentication module

The OATH module is a more recent addition to OpenAM which implements both HOTP and TOTP as they are defined in the corresponding RFCs. This is how they work under the hood:

  • Both OTP mode retrieves the shared secret from the user profile (e.g. it is defined in an LDAP attribute of the user’s entry).
  • HOTP retrieves the moving factor from the user profile.
  • TOTP does not let a user to authenticate within the same TOTP window (since a given TOTP may be valid for several time windows), hence it stores the last login date in the user profile.

For the following tests I’ve been using the Google Authenticator Android app to generate my OTP codes.

Testing OATH + HOTP

First set up the authentication module instance:

openam/bin/ssoadm create-auth-instance --realm / --name OATH --authtype OATH --adminid amadmin --password-file .pass
openam/bin/ssoadm update-auth-instance --realm / --name OATH --adminid amadmin --password-file .pass -D

Where contains:


NOTE: here I’m using the givenName and the sn attributes for my personal tests but in a real environment I would use dedicated attributes for these of course.

Again let’s create a test authentication chain:

openam/bin/ssoadm create-auth-cfg --realm / --name oathtest --adminid amadmin --password-file .pass
openam/bin/ssoadm add-auth-cfg-entr --realm / --name oathtest --modulename DataStore --criteria REQUISITE --adminid amadmin --password-file .pass
openam/bin/ssoadm add-auth-cfg-entr --realm / --name oathtest --modulename OATH --criteria REQUIRED --adminid amadmin --password-file .pass

In order to actually test this setup I’m using a QR code generator to generate a scannable QR code for the Google Authenticator with the following value:


NOTE: The Google Authenticator needs the secret key in Base32 encoded format, but the module needs the key to be in HEX encoded format (“48656c6c6f576f726c644f664f415448″) in the user profile.

After all these changes bring up /openam/UI/Login?service=oathservice and just simply ask for a new HOTP code on your phone, you should see something like this:

Google Authenticator - HOTP

Enter the same code on the login screen and you are in, yay. :)

Testing OATH + TOTP

For testing TOTP I’ll be reusing the authentication modules and chains from the OATH HOTP test:

openam/bin/ssoadm update-auth-instance --realm / --name OATH --adminid amadmin --password-file .pass -D

Where contains:


We need to generate a new QR code now with the following content:


Again, let’s test it at /openam/UI/Login?service=oathtest and this time we should have a slightly different UI on the Google Authenticator:

Google Authenticator - TOTP

As you can see there is a nice indicator now showing us how long this TOTP code will remain valid.

I think now we know about OTP codes more than enough, hope you’ve found this article useful. ;)