ISAM

An Introduction to the InfoMap Authentication Mechanism in ISAM 9.0.2

Share this post:

For some time now the IBM Security Access Manager (ISAM) appliance has offered a pluggable authentication service in it’s Advanced Access Control (AAC) module. This authentication service is really just an advanced form (or framework) of External Authentication Interface (EAI) application for the ISAM WebSEAL reverse proxy, allowing you to programmatically interact with a user-agent (browser or API client) until a user login is achieved.

The authentication service has authentication “mechanisms”, which are the building blocks for an authentication “policy”. In a similar way to how the ISAM Security Token Service (STS) works with modules and chains, the authentication service allows you to combine mechanisms into policies that affect how a user logs in or steps up their authentication context.

Until ISAM 9.0.2, customizing the AAC authentication service meant writing a special Java OSGi plug-in, and loading it onto the appliance. In ISAM 9.0.2 we have introduced the InfoMap authentication mechanism which allows you to use a combination of a page template (typically HTML), and server-side javascript to achieve the majority of authentication requirements without ever writing custom Java code.

In this short article I will show you how to write a HTML page and server-side Javascript to perform “Username-only login” – i.e. just enter a username and you are logged in as that user. Whilst this trivial mechanism has no place in a production environment (since it’s probably not a good idea to be able to login as anyone by only providing their username), it is actually very useful when designing and testing solutions for ISAM deployments. You can also use this implementation as a starting template for your own InfoMap authentication mechanism configurations.

Scenario Description

To login, the end-user will be presented with a form that asks for just a username. On submitting the form, a browser session is established as that user.

Technical Pre-requisites

It is assumed you have an ISAM appliance configured with a reverse proxy instance, and the Advanced Access Control module enabled. You should also have used the command line to run “isam aac config” to establish the WebSEAL junction and configuration file settings required for working with AAC. For more information see: Getting started with Advanced Access Control.

Configuring the Solution

To configure this solution, the following steps are required:

  • Load the HTML page template onto the appliance
  • Load the server-side Javascript rule that will process the page
  • Configure an instance of the InfoMap authentication mechanism that refers to your page template and javascript rule
  • Configure an authentication policy that uses your authentication mechanism
  • Test the solution

Creating and uploading the page template

The page template is very simple – a HTML page which includes a form that prompts for a username.

<html>
<form method="POST" action="@ACTION@">
<input type="hidden" name="operation" value="verify">
Username: <input type="text" name="username">
<br><input type="submit" value="Login">
</form>
</html>

A couple of things to note about the page template:

  • @ACTION@ is a special macro that will be automatically populated by the authentication service. You can include your own custom macros if you wish.
  • The operation=verify hidden parameter is important. This instructs the authentication service to call your Javascript to verify the posted form.

Save this HTML content into a file called usernamelogin.html and use the admin console to upload it to the appliance.

Navigate to Secure Access Control -> Template Files. Create a new directory under /C/authsvc/authenticator called “usernamelogin” and place the file in that directory, as shown:

infomap_templatefile

Loading the InfoMap Javascript Mapping Rule File

Here’s the server-side Javascript mapping rule for processing the above form:

importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);
// Get username from request parameters
 var username = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "username");
 IDMappingExtUtils.traceString("username from request: " + username);
if (username != null) {
    // username found, set this as the user to login
    context.set(Scope.SESSION, "urn:ibm:security:asf:response:token:attributes", "username", username);
    success.setValue(true);
 }

Create a file called usernamelogin.js with the above content, then upload as a mapping rule called UsernameLogin using the admin console Secure Access Control -> Mapping Rules, as shown:

infomap_import_rule

Note: You can actually skip this step altogether if you like, since ISAM 9.0.2 ships with a mapping rule called InfoMapUsername which is essentially the same content as above. You can use InfoMapUsername instead of this mapping rule if you wish.

 

Configure an instance of the InfoMap authentication mechanism that refers to your page template and javascript rule

Navigate to Secure Access Control -> Authentication. Select the Mechanisms category, and add a new InfoMap mechanism with properties pointing to your rule and page template.

Name: UsernameLoginMechanism

Identifier: urn:ibm:security:authentication:asf:mechanism:username_login

Description: Test login with just a username

Properties:

  • Mapping Rule – UsernameLogin
  • Template Page – /authsvc/authenticator/usernamelogin/usernamelogin.html

 

infomap_mech_1

infomap_mech_2

 

Configure an authentication policy that uses your authentication mechanism

Navigate to Secure Access Control -> Authentication. Select the Policies category, and add a new Authentication Policy with just the UsernameLoginMechanism as it’s only step:

Name: UsernameLoginPolicy

Identifier: urn:ibm:security:authentication:asf:username_login

Description: Permits login with only a username

infomap_policy

Test the solution

You can use a browser (from an unauthenticated state), to access your WebSEAL server and login as follows (my WebSEAL is at 192.168.42.102):

https://192.168.42.102/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:username_login

Note: If you are using ISAM 9.0.6.0 or later, and have the sps.authService.policyKickoffMethod advanced configuration property set to path, then the kick-off URL will look like:

https://192.168.42.102/mga/sps/authsvc/policy/username_login

For more information on the sps.authService.policyKickoffMethod advanced configuration property, and why I recommend it, see this article on Protecting entire ISAM WebSEAL site with multi-factor authentication using stepup login where I discuss the topic in more detail.

Type in any username that exists in your access manager user registry and press login.

login_1

 

Provided you have entered a valid username, you should see the login success page:

login_2

 

If you have been working with ISAM for any length of time, you will already have a way of using the on-board demonstration application to view your ISAM credential, or you may have previously used my epac viewer. In any case, I suggest you use something like this to go look at your current ISAM credential, as I have done here:

login_3

This demonstrates I have logged in as testuser, providing only the username to login!

Conclusion

This article only scratches the surface of what you can do in an InfoMap authentication mechanism. The InfoMap is like the swiss army knife of the authentication service, and actually forms the basis of how much of our new user self-care functions are implemented. InfoMap mechanisms provide immense flexibility in handling request/response HTML processing as part of an authentication process with ISAM. I would encourage you to take a look at some of the supplied InfoMap mechanisms that exist on the ISAM 9.0.2 appliance today and how they are used in policies. A quick read will give you lots of ideas of how you can use this mechanism either standalone or in policies with other mechanisms to compose rich authentication scenarios. Here’s an example of some of the other things you can do with InfoMap authentication mechanisms:

  • Return one of several different pages. You are not restricted to just the one page configured for this mechanism – that is just a default page.
  • Pass data to, or read data from other mechanisms in a policy.
  • Have both html and json page templates based on whether or not your policy is access via /sps/authsvc or /sps/apiauthsvc
  • Build Facebook authentication into ISAM without any custom java code.

 

 

More stories

Protecting entire ISAM WebSEAL site with multi-factor authentication using stepup login

Today I’m going a bit old-school with information on a basic ISAM scenario that has been available for years. This has come up in field questions several times recently, I think mostly with people who are relatively new to ISAM but understand the need for multi-factor security as a standard part of the authentication workflow. […]

Continue reading

Cross-origin session detection

Consider a federated single sign-on environment where an Identity Provider (IDP) for applications may in turn be acting as a gateway – and be configured as a Service Provider (SP) to many different other IDPs. The role of this IDP is to provide a common federated SSO service to applications. It may also need to […]

Continue reading

The fido2viewer – a free FIDO2 debugging utility

Those of you who have been reading my recent series of blog posts will realize that I’ve been spending a great deal of time working on FIDO2 and WebAuthn related technologies. As part of this effort which has been in progress on and off for more than 12 months now, I put together a debugging […]

Continue reading