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:
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:
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
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
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.
Provided you have entered a valid username, you should see the login success page:
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:
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.