PLEASE NOTE (update August 2020): For customers running IBM Security Verify Access v10 and later, branching AAC policy is now a built-in feature. For more information see: https://learn.ibm.com/course/view.php?id=15027. The information in the rest of this article is still relevant for older version of IBM Security Access Manager that do not support out-of-the-box branching AAC policy.

ISAM’s advanced access control authentication policies and mechanisms provide a very flexible way to manage the user authentication experience. There are a large number of out-of-the box authentication mechanisms such as delivered OTP (sms/email), TOTP, HOTP, IBM Verify (mobile push), knowledge questions, FIDO U2F and more. Additionally you can roll-your-own with the javascript+html based InfoMap authentication mechanism type – a topic I have written about extensively in past articles. What I find I am being asked more and more though is how to build “branching” authentication policies, particularly given that an authentication policy in ISAM AAC is defined as a simple ordered list of mechanisms.

Well, you can certainly branch policies, even if the way to do this is not completely obivous. Let’s work through an example to show you how it’s done.

Solutions Overview

Consider an authentication sequence for second-factor authentication. A user may have some number of registered authentication mechanisms, but you want to give the user a choice of which one to use. The logical flow is as shown in this diagram:

This type of branching workflow cannot be coded into a single AAC authentication policy, but can easily be realised with AAC by creating multiple simple policies. When reaching the end of the first policy, it redirects the user to the specific next policy in the branch without actually completing authentication with a success status. In effect you “abandon” the first policy and begin the next. The following diagram depicts the approach as configured in AAC authentication policies:

As shown in the diagram, one challenge to overcome with this approach is managing state information between the different AAC policies, since starting a new policy will not preseve the “context” object that was being populated from the first policy. This can easily be done with the help of a Javascript InfoMap to programmatically store the context you want to share using either:


IDMappingExtUtils.setSPSSessionData(key,value)

or

IDMappingExtUtils.getIDMappingExtCache().put(key,value,timeout)


Of the two approaches, for state management between AAC policies I would recommend the first. It will be faster and more efficient as it is in memory (not the HVDB), and we only need to share the state whilst in AAC policies that stay within the same HTTP session. I would only tend to use the IDMappingExtCache approach if there was a need to share state between AAC and an STS chain, or some other context where the HTTP session was not available, or if the state information needed to persist across sessions for some reason.

You can implement this scenario in your own ISAM, and I have written and provided all the supporting InfoMap AAC mechanism rules to show you how to do it. You can find all the resources in my public github here:

https://github.com/sbweeden/blog_assets/tree/master/branching_aac_policies

Configuring the Solution

Load all the InfoMap mapping rules and page templates, then create the InfoMap authentication mechanisms.

This screenshot shows the template pages that I have loaded onto my ISAM from the github project – re-create the same directory structure:

This screenshow shows all the loaded mapping rules – use the names I have suggested as some of the mapping rules include others and this is done by mapping rule name:

Note that this implies that SCIM is configured on the appliance. This is needed for finding out of the user has either IBM Verify or FIDO U2F mechanisms configured. If you are not using either of those, you don’t need the MMFASCIMHelper mapping rule, and you will have to modify the Select2FA mapping rule (file infomap_select_2fa.js) to remove the included MMFASCIMHelper mapping rule and references to function calls that it contains.

The table here shows the two new InfoMap mechanism configurations. For each mechanism there is a mechanism name, uri, description and mapping rule to use. You don’t need to set a page template for any of these InfoMaps – they all contain explicit code that manually selects which pages to use.

Finally, create the AAC policies that leverage these mechanisms, plus the built-in authentication mechanisms the user will engage with. In my case there are 6 policies – one for the user selection process, and five different policies the user may branch to. Each policy contains the mechanisms as shown in the sections below.

Pay special attention to how the Email and SMS OTP policies have the Pre2FA InfoMap mechanism up front. This is used to retrieve session state (specifically the delivery attribute – email address or phone number) that was established and stored as session state as part of the Select2FA policy. This shows you how to easily use the APIs to share session state between AAC authentication policies as you branch from one to another.

Select2FA Policy

This is the first policy the user will access when directed for 2FA. It will perform discovery of the mechanisms a user can complete, and then have the user select a mechanism. Finally it will abandon this policy by redirecting to another policy based on the user’s selection to complete 2FA.

Email OTP Policy

Note that the MAC OTP mechanism has the following properties within this policy:

Notice that the deliveryType is set to Email, and the email address will come from a context attribute. It is the job of the Pre2FA InfoMap mechanism to populate this attribute, and it will do so from SPS session state that is saved at the end of the Select2FA policy if the user chooses Email OTP. I also set the reauthenticate property to true to force Email OTP every time the policy is invoked rather than once-per-session.

SMS OTP Policy

Note that the MAC OTP mechanism has the following properties within this policy:

Notice that the deliveryType is set to SMS, and the phone number will come from a context attribute. It is the job of the Pre2FA InfoMap mechanism to populate this attribute, and it will do so from SPS session state that is saved at the end of the Select2FA policy if the user chooses SMS OTP. I also set the reauthenticate property to true to force Email OTP every time the policy is invoked rather than once-per-session.

TOTP Policy

This policy is almost unchanged from the built-in default. I did create a new one because the built-in is read-only, and I decided to modify the properties of the TOTP One-time Password mechanism and set the reauthenticate property to true. This will force TOTP every time the policy is invoked rather than once-per-session.

IBM Verify Policy

For this policy, I created a simple MMFA initiate with user-presence response. Here is both the policy and all the properties I set for the MMFA Authenticator module. Note that the policyURI is for a mobile-channel response policy for user-presence. For more details on how this all works, see the IBM Verify Cookbook.

FIDO U2F

For FIDO U2F I first had to set the mechanisms initialisation property for Application ID:

In my case my webseal is www.apimfa.ibm.com. Change this to be the URL that your browser uses to connect to your webseal.

After that I was able to use the out-of-the-box policies for U2F registration and authentication.

Testing the Scenario

Provided you have the registrations for 1 or more of the available authentication mechanisms, start in a logged-in state then navigate to the selection policy using a URL like:

https://www.webseal.com/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:select_2fa

This policy will discover what mechanisms you are able to complete (note that it hard-codes an email address – for testing, checks credential attributes for a phone number, uses SCIM for IBM Verify and FIDO U2F registrations, and uses a special API to determine if the user is registered for TOTP), and then presents the user with a list:

Note that in my case I do not have TOTP or IBM Verify registered, but all the other mechanisms show up.

After choosing a particular mechanism, any required shared state information will be saved using IDMappingExtUtils.setSPSSessionData, then the browser will be redirected to the new policy. The new policy will be invoked. For email and SMS OTP an infomap will retrieve the delivery attribute from the SPS session and set as a context attribute to be read in by the next OTP mechanism. The 2FA mechanism the user chose should complete as normal.

Conclusion

In this article I have demonstrated a simple and effective way to author branching SSO authentication policies in the context of a real world example – selecting from one of several mechanisms to complete a 2FA authentication. I hope this shows you how to effectively use ISAM AAC to achieve your own rich authentication workflows. If you have any questions, feel free to comment on the blog, or post them in the Discussion Forum on the IAM Security Community.

Update July 2019

Due to secure-by-default updates made to ISAM 9.0.6.0 and later, if you are using that or a newer version of ISAM with the techniques described in this article you will also need to update the sps.page.notEscapedMacros advanced configuration property (Secure Access Control -> Advanced Configuration) to include these macros used in the page templates so that they are not HTML-encoded by default:

• @POLICY_URI@
• @LABELS@