In this article I will describe a technique with Tivoli Federated Identity Manager for including attributes in an single sign-on (SSO) assertion that come from a business application at runtime. This example will be in the context of IDP-initiated SAML 1.1 SSO using WebSEAL as the point of contact but the pattern is not restricted to that protocol. Typically when performing SSO from an identity provider to a service provider the attributes included in the assertion come from the user’s credential (identity attributes) or are looked up from a user registry or database in an identity mapping rule written in Javascript or Java at the IDP. On more than one occasion now I’ve been asked how to include attributes in an SSO assertion that may only be know to, generated by or discovered by a business app at runtime within the context of the current user session. A trivial example that we will use in this demonstration is to include the session id of the application server that the business app is running on. I know this is fairly useless data, but it is a piece of data known only at runtime to the business app itself.

One way that this could be approached is to create a database and from the business app store the data to be included in the SAML assertion in the database, keyed on the userid. Then the mapping rule used at TFIM during SSO operations can lookup the database based on the userid (which is available during SSO). There are two issues with this approach. First, the database management is an overhead that requires lifecycle management, but more importantly the user id is not unique to the business application session – if the web access system permits a user to have more than one active session then the userid is not unique enough to use as a key.

To solve the database issue we will instead make use of a TFIM trust chain, and in that chain use an API available to TFIM mapping rules to store data in a distributed cache available to the TFIM WebSphere cluster. To solve the cache key problem we will use the WebSEAL session id which is contained within an attribute of the user’s TAM credential and can be made available to both the business application and the TFIM mapping module used in SSO operations. Pictorially the solution looks like this:

The sequence is:

• 1. The application decides SSO is to be initiated and the SAML assertion must include business attributes that the application knows.
• 2. The application calls a custom chain at the TFIM STS sending an STSUniversalUser (a simple XML token) which contains the user’s current WebSEAL session ID and the attributes to remember.
• 3. The mapping rule in the custom chain calls the TFIM utility function IDMappingExtUtils.getIDMappingExtCache().put(key, data, lifetime) to store the attributes for a short period (say 20 seconds). The cache entry lifetime need only be short since the business app is now going to redirect directly to TFIM where the entry will be read again and after that it is no longer needed.
• 4. The business application redirects the user’s browser to the standard TFIM IDP-initiated SSO URL for the federation and partner in use.
• 5. TFIM is invoked to perform SSO which in turns calls the TFIM STS to build the SAML assertion.
• 6. A TFIM mapping rule configured for the federation or partner has access to the WebSEAL session ID from the STSUU generated as part of the SSO operation and retrieves the attributes from the cache using IDMappingExtUtils.getIDMappingExtCache().get(key). These attributes are used to populate the SAML assertion’s AttributeList.
• 7. SSO is triggered to the partner in the normal fashion (e.g. browser-POST or browser-artifact).

Solution Components

To help you implement this scenario I have provided a few downloadable source code examples including:

• An example business application SAMLBusinessAppEAR.ear written as a J2EE/jsp application which includes source and a WS-Trust client that calls the TFIM STS. This example app uses a simple JAX-RPC bsaed WS-Trust client that has appeared in some of my previous articles, however you could use any WS-Trust client including those referenced in my WS-Trust clients article. In the application as it is currently written the WS-Trust client assumes TFIM is running on the same host without transport security (it uses http://localhost:9080/TrustServer/SecurityTokenService as the WS-Trust endpoint).
• An example javascript mapping module that can be used in the custom STS chain to store attribute information in the WebSphere distributed map.
• An example javascript mapping module that can be used in the TFIM SAML 1.1 IDP configuration to retrieve attribute information from the WebSphere distributed map. If you want to use a different federation type, just base your mapping module on the default shipped with TFIM and use the extra code found in this one to populate the AttributeList.

Configuring and Testing the Scenario

You should create a custom STS chain in TFIM with structure:

• STSUU(validate)
• Map(use the first mapping rule listed above)
• STSUU(issue)

• Other properties of the custom chain should look like those shown in this picture (they must match the configuration for the STS client built into the demo business app):

  

  Your SAML partner configuration should use the second javascript mapping rule shown in the example above.

  The way I tested this scenario was to install the example business app on the same WebSphere server as TFIM – but this is absolutely not a requirement. Be sure to modify the configuration properties at the top of the index.jsp file contained in the application to match your environment including the connection properties to your TFIM server, and the SSO URL for triggering SSO to your SAML partner.

  You also to ensure that the business application (index.jsp in the sample ear) received the tagvalue_user_session_id attribute from the TAM credential as a HTTP header. To do this I used the following TAM administration command:

  pdadmin> object modify /WebSEAL/your_webseal_object/your_junction set attribute HTTP-Tag-Value user_session_id=user_session_id
  

  Note that in the above command your_webseal_object should be for the WebSEAL server in your environment. Do “object list /WebSEAL” if you don’t know what it is. Also your_junction should be the junction to the WebSphere running the business application (this could be the /FIM junction for example if the EAR is running on the TFIM server like it was when I tested the scenario).

  The result of running the scenario is that the SAML assertion generated as part of the SSO to the partner included the business attributes that the index.jsp puts into the STSUU before calling the TFIM STS.

  And, as I wrap up this article, I just thought of some other techniques if your business app is not behind WebSEAL and doesn’t have access to the user_session_id. You could easily generate your own “lookup key” in the business app instead of using the WebSEAL session id, then include that key in the TARGET parameter of the redirect to the TFIM SSO URL. This will be available to your TFIM IDP mapping rule in the STSUU as well, and you could unmarshall the query string and extract the lookup key from there. There are lots of options – you just have to keep thinking!