IBM Security Global Forum

Over the past several releases of IBM Security Access Manager we have supported a javascript-and-html-based pluggable authentication framework called Infomap. Several previous articles that other colleagues and I have written have already provided an introduction and some examples of using this capability for different forms of advanced authentication.

In this article I’m going to demonstrate how to use Infomap with another new feature introduced in ISAM 9.0.5 called the LocalSTSClient. This is an alternative to the STSClientHelper, which I’ve demonstrated use of in the past. The major difference is one of performance, and the requirement that the Security Token Service in ISAM is run on the same machine as the Javascript code that is calling the LocalSTSClient. The LocalSTSClient uses pure-Java interfaces to the STS and makes no HTTP callout (even on the loopback interface this adds overhead).

You can find Javadoc for the LocalSTSClient in the File Downloads section of the management console for your ISAM installation (appliance or container). You will need ISAM 9.0.5 or later for the LocalSTSClient.

Let’s take a look at the solution diagram…

Scenario Overview

An incoming request to the ISAM authentication service made by an authenticated user will result in the down-streaming of the iv-creds identity header from WebSEAL to the WhoAmI Infomap authentication mechanism. The Javascript code in this mechanism will extract the iv-creds header, and use the Security Token Service to exchange it for an STSUniversalUser (simple user object with accessor methods). We will use the returned STSUU to render a HTML page with all the user’s identity attributes.

If you haven’t already guessed, this is a variation of a capability that I’ve talked about a lot in the past – being able to introspect the iv-creds header and understand all the attribute in a user’s session credential. I have written several articles on this topic – most have relied on using Java APIs from the PD.jar to achieve this in a Java servlet or similar. This article shows you a much simpler completely-within-ISAM way of doing the same thing.

Configuration of the scenario

The solution requires that both the advanced access control and federation capabilities of the ISAM product are enabled. It also assumes you have run the isam aac config utility to configure the ISAM environment for use with the ISAM AAC authentication service. That detail will not be covered in this article. It’s well covered in other material, including the Verify Cookbook.

We will then configure:

* An STS chain template and chain to convert IVCred to STSUU
* The Infomap authentication mechanism and policy that will use the STS chain to unpack the iv-creds header from a request

Configuring the STS chain template and chain

Using the Security Token Service interface in the ISAM console, create a chain template which has two modules, Default IVCred (validate) followed by STSUU (issue). This article won’t go into the details of how to do that – there are plenty of examples around, including in the Federation Cookbook.

Next create a module chain which uses this template, and sets chain lookup criteria (such as RequestType, Issuer Address and Applies-To Address). I recommend the following settings as these are what the example Infomap will later use to call the chain:

It really doesn’t matter what the AppliesTo and Issuer addresses are, only that that are a URN, and that they match what the client sets in their WS-Trust request. By way of personal convention, I typically set the issuer address to indicate the type of base token that will be coming in from the caller for exchange, and the applies-to address to indicate the type of token the chain will issue. There are no rules, just use something that makes sense to you.

Be sure to deploy any changes after the chain template and chain are created.

Configuring the WhoAmI Infomap mechanism and policy

Upload the WhoAmI.js mapping rule to the ISAM system, indicating it’s type as Infomap. You should inspect this file, and look at the source code for it. The purpose of the file is to read the iv-creds header from the incoming request, and exchange it for an STSUU using the LocalSTSClient. Then it will create a JSON representation of the STSUU attributes, and include that as a macro in the returned whoami.html page template. Note that the Javascript mapping rule always ends with:

success.setValue(false);

This means that the “mechanism” never “succeeds”. In fact this is precisely what we want. We are not using this mechanism to perform authentication, we are using it to only return a page template – all the time. You can think of this as using the AAC mechanism as a lightweight servlet, with access to the ISAM credential and all the ISAM java helpers and capabilities available to any other Infomap mechanism.

Upload the whoami.html and whoami.json files to the template pages directory under C/authsvc/authenticator/whoami directory, which you will have to create, as shown below:

I’ll talk more about the whoami.json file later. You should inspect these files and see precisely what they do. Specifically the whoami.html file renders a table of all credential attributes, as received in the JSON version of the attributes that the mapping rule extracted from the STSUU.

Now create a new AAC Authentication Mechanism and Policy. The mechanism uses the Infomap mapping rule and page template we have just uploaded:

The policy includes only the new Infomap mechanism:

Saved and deployed all changes.

Updating advanced configuration property for HTML encoding

If you are using ISAM 9.0.6 or later, navigate to Secure Access Control -> Advanced Configuration, edit the configuration property sps.page.notEscapedMacros and add @USER_CRED_JSON@ to the list. From 9.0.6 onward all page template macros are HTML encoded by default. The logic in this application requires this macro to be not HTML encoded in the page template.

Save and deploy this change, and the scenario is now ready for testing.

Testing the WhoAmI authentication policy

Using my browser, I first ensured I had an authenticated session with WebSEAL by first accessing any protected resource. Then I accessed the new AAC authentication policy with:

https://www.myidp.ibm.com:30443/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:whoami

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://www.myidp.ibm.com:30443/mga/sps/authsvc/policy/whoami

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.

The credential attributes should be shown in the page template:

If you access the policy unauthenticated, you will like get an error stack trace, and somewhere in there it will say:

FBTSTS015E The IV-Cred binary token is invalid or not present

If this happens to you, this means that you sent an unauthenticated cred to the STS, and the IV-Cred module doesn’t like validating that. You can actually modify the STS to allow it to validate unauthenticated credentials – this is done by setting some non-empty values for these advanced configuration properties:

If you do that, then re-access the policy as an unauthenticated user, you will get a result, similar to:

Really you can declare complete success at this stage, but I’d like to share some advanced information about the “apiauthsvc”, which is an API-focused way to invoke authentication service policies and how that can be useful in single-page applications, or simple HTML pages using AJAX.

Example usage with the apiauthsvc

One of the lesser-known uses of the AAC authentication service is to have programmatic clients invoke it via the URL path /<jct>/sps/apiauthsvc using the application/json Accept and Content-type headers. This is used extensively by the IBM Verify mobile application, but can also be used by your own clients, including AJAX-based requests in simple HTML pages, or more elaborate single-page applications (SPA’s).

To demonstrate this, I have included a whoami.json template page, which you should already have loaded earlier. This will automatically be used instead of the .html page when the apiauthsvc URL is used instead of the authsvc. All this page really does is put all the macros into a JSON object that client-side AJAX can interpret.

I have also provided a simple HTML page that uses ajax to invoke this service. This is called whoami_ajax.html.

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 a small change is needed to the whoami_ajax.html page. I have included a version of the changed file as whoami_ajax_path.html, so use that file content instead. Diff the two files to understand the changes in more detail.

You can upload this directly to the WebSEAL junction root, as shown:

If you now access the new WebSEAL-hosted page directly, it will in turn use ajax to call the apiauthsvc, and then render a dynamically populated table after the ajax response is received.

https://www.myidp.ibm.com:30443/whoami_ajax.html

It is useful to watch the XHR requests with the browser’s network debugger when loading this page. You can see the ajax request taking place, and any issues that might occur during that transaction.

Conclusion

In this article I have demonstrated another novel use of the very powerful Infomap authentication mechanism. This time it had nothing to do with authentication per se, but everything to do with using platform features to introspect the authenticated user’s credential, and return a view of that to the user.

We also introduced use of the LocalSTSClient, which is simply a more efficient way to invoke the STS from any ISAM Javascript integration point (Infomap, STS mapping rules, etc).

If you are an ISAM practitioner, I hope you’ve found this information useful and if you have any questions feel free to reach out and ask!