I’ve been writing technical content on IBM developerworks and my own IBM developerworks blog for some time now, primarily with a focus on specific how-to’s or best practices for our access management and federation products. These articles are largely driven by customer requests for assistance with a problem they are trying to solve. When I see a common thread that can be generalized and shared, I typically put together an article and any example code I’ve prepared in helping address the problem.

Having worked with IBM Security Access Manager since it was called Intraverse and owned by Dascom, and having been a founding developer on our Federated Identity Manager product, I have about as much experience and exposure to both products as anyone else. That said, I am always intrigued and surprised by some of the innovative ways in which customers, business partners and services teams put together solutions using our security products.

In this article I thought I’d take the time to summarize five of the most useful and frequently used tools of my trade. These are often references to content or advice that I’ve prepared in the past, but specifically content that I am finding re-use for all the time. Hopefully these tools and ideas are useful to both experienced and novice users of our access management and federation products, and if nothing else this article can serve to remind you they exist, and help you find them again.

I’d also like to remind customers, business partners, and anyone else working with our security products that I enjoy hearing from you, working with you on solutions to your security integration issues, and providing a point of view on issues where you may be looking for another opinion. Please keep those emails coming and feel free to leave a comment below.

1. The EPAC Application

Without question, when working with access manager and federated identity manager, the number one tool I need is the ability to understand what is in a user’s credential when authenticated to WebSEAL. Historically it’s called the EPAC (extended privileged attribute certificate) and that comes from way back when DCE was the middleware security of choice in the mid-to late ’90’s.

This is used in so many different ways – whether it’s manipulating attributes in an STS module in FIM, or writing a context-based access policy, or even the humble authorization rule in access manager (which I still use) – you pretty much have to be aware of the attributes available in a credential.

The credential is visible to applications via a variable supplied by WebSEAL. On WebSEAL itself this is made available as a cgi-bin environment variable called HTTP_IV_CREDS, and for junctioned applications it can be downstreamed as a HTTP header (iv-creds) by use of the -c junction switch.

WebSEAL itself ships with a cgi-bin version of the EPAC program (it’s part of the PDWebADK package) however I more commonly recommend people use the JSP version of an application I wrote to unpack and display a credential. The true format of an EPAC is not documented, and not important. It’s a custom ASN-1 encoded data structure, and not designed for you to unpack natively. You should use the API’s supplied with access manager to decode a credential and that’s precisely what is documented in my article: Pracical TAM Authorization API

2. FIM Tracing for the Security Token Service

A lot of my more recent work has been on federated identity manager, particularly the development of STS modules for integrating into federations, OAuth and more. There are articles on Writing FIM plugins, and many articles on specific examples of STS modules for different purposes (browse my blog).

That said, probably the most useful companion to me in development of these modules is introspection of the STSUniversalUser object for understanding what data structure I am manipulating, and what attributes are available to me.

One of the easiest ways to see what is in the STSUniversalUser, whether you are authoring a mapping rule in Java, or simply in Javascript or XSLT is to turn on FIM tracing and search for STSUniversalUser. Tracing is enabled in the WebSphere administration console under the troubleshooting section, and specifically the trace string I like to use (to minimize trace noise) is:

com.tivoli.am.fim.trustserver.sts.modules.*=all

This will tell you everything you need about the STSUniversalUser you are manipulating in a mapping rule, and when combined with the EPAC application described above you are well-equipped to configure and author FIM mapping rules.

3. EAI Development and pdweb.snoop Tracing

<rant> One of the best things we ever did to WebSEAL was deprecate and eliminate the CDAS (cross domain authentication service) interface, and replace it with a HTTP-header based authentication interface called EAI (external authentication interface). CDAS plugins are written and compiled in C/C++, and I cannot recall the number of times I was asked to look at WebSEAL core files only to eventually find out that a customer was using their own CDAS and had not written or compiled it in a thread-safe manner. </rant>

Now that I’ve got that off my chest, the EAI method of authenticating to WebSEAL is great, and is actually the same interface used by federated identity manager when acting as a service provider authenticating to WebSEAL. There is lots of documentation on the EAI in the InfoCenter (start here).

It’s also quite trivial to write an EAI application in whatever web development environment you like. I often write them as JSP’s to perform step-up authentication or just for testing a multi-factor concept. The main things to remember when writing an EAI are:

• Unless your EAI is performing step-up, it will need an unauthenticated-allowed ACL attached to it in access manager.
• You EAI needs to return HTTP headers for the user to authenticate, OR it can return an entire EPAC if built by FIM’s STS. I have articles on how to do this, such as this one which is particularly popular: Using access manager without a user registry
• You must remember to enable EAI authentication in WebSEAL’s config file
• You must remember to configure your application URL as a trigger-url in WebSEAL’s config file

Sometimes, despite the best of planning and intentions, your EAI may still not be performing as you expect it to. Perhaps you’ve forgotten a piece of configuration, or perhaps the EAI itself isn’t returning the credential or username + attributes in the manner you expect. How do you debug that?

There are several ways – junctioning your EAI via a sniffer proxy like TCPMON is one, however what I find myself using most often, because it is always available, is pdweb.snoop tracing. To enable pdweb.snoop tracing, use pdadmin command line, with something like:

padmin> server task webseald-your_webseal trace set pdweb.snoop 9 file path=/tmp/pdwebsnoop.log

Perform your attempt at EAI authentication, give WebSEAL a minute or so to flush the trace to file, and then carefully inspect the requests and responses to ensure you are returning the headers needed for EAI and that they match the headers configured in WebSEAL.

Sometimes I even use pdweb.snoop tracing to debug federated identity manager behaviour!

4. Using CURL

Any web developer or deployment engineer worth their salt knows about and regularly uses Curl or a similar utility. It is absolutely invaluable in scripting tests, debugging and general web poking around. Learn it, use it, and don’t look back! It is available out-of-the-box on almost all linux distros, and also on cygwin for Windows.

There are a large number of switches to curl, but the ones I use most regularly when testing and developing are:

This article is quite useful for showing you how to use Curl to interact with the FIM security token service: Using CURL to send requests to the TFIM STS

You can also web search numerous examples on using Curl for different purposes. I’m also a fairly regular user of netcat for testing as well, but it’s not quite as common as curl for web development.

5. Learning to Prepare Well, Then Divide and Conquer

This tip is not specific to access management or federated identity management, but is just general advice on how to prepare well, and figure out what’s wrong when things don’t go the way you’ve planned. When I run into customers with a problem, solving it is almost always done by simply breaking the problem down into smaller and smaller problems until you isolate the root cause. This seems to glaringly obvious, yet continues to be a challenge. You’ve probably heard of the Five Why’s, and it is never more applicable than in complex distributed computing systems.

Here are some common things you can do before, and when trying to isolate unexpected behaviour in solutions using access management or federated identity management solutions:

• Have a production-quality test environment with the same software versions of software, same topology, and same change control. Being able to replicate an issue offline from your production systems is incredibly useful.
• Monitor and have unit tests at all points in the infrastructure. You should have scripts and/or monitoring software that tests databases, LDAP servers, authentication to WebSEAL, session stickiness, synthetic transactions, etc at all levels of your security infrastructure and across all nodes in a multi-server deployment. This will often help you quickly isolate a problem.
• If using a HA deployment with multiple nodes, load balancers, backend servers and databases, try to eliminate state management as an issue by using a single instance of each and testing that path of execution. I know this is not always possible, but at the very least keep in mind that a lot of access management functionality is based on session state and maintaining consistent connections to server instances throughout the course of a user’s browser session.
• Change one thing at a time, then re-assess.
• Build, maintain and share with your colleagues a set of tools of your own. Of course experience is something you get just after you need it, but nothing beats it. Keep your hands dirty – it’s definitely the best way to learn.