August 7, 2018 | Written by: shane.weeden
Share this post:
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
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
Let’s take a look at the solution diagram…
An incoming request to the ISAM authentication service made by an authenticated user will result in the down-streaming of 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
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:
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
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. 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.
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.
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.
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!