Tivoli Directory Integrator Web Services Revisited

I really wanted to talk about two issues that have presented themselves to me recently when hacking my way around Tivoli Directory Integrator's implementation of web services functionality using the Apache Axis framework.

It has struck me, however, that the issues weren't really TDI issues at all. They were pure Axis issues that have been documented elsewhere on the web. That said, it can be difficult to find the information, and even more difficult to use the information in a TDI context. So, despite repeating what others have already found, I thought I'd share the solutions with you.

Integrated Windows Authentication
I like the idea that the WWW is fairly platform agnostic and encourages the use of open standards. But things don't always work out that way. Finding that a WSDL is being served by some Microsoft technology isn't necessarily a bad thing but when the server providing the service insists on the client using Integrated Windows Authentication to authenticate, then I start to scratch my head in a "why would someone do that" manner.

They do, though. And the Axis implementation within TDI won't perform Integrated Windows Authentication without some "tweakage".

That "tweakage" requires Axis to make use of the CommonsHTTPSender method as an HTTP transport rather than the default HTTPSender method. How did I find this out? I Googled it! Great news. Hurrah. But how do we tell Axis to make use of the CommonsHTTPSender method?

Axis 1.4 will search for a file called client-config.wsdd in the current working directory and this file contains the necessary parameters which tell Axis how to behave and more importantly, what transport to use. I figured that placing such a file somewhere in the Classpath would suffice, but I only managed to get Axis to load up the contents of my client-config.wsdd by placing it in the TDI home directory. In my case, that was:

c:\Program Files\IBM\TDI\V7.1\client-config.wsdd

And what were the contents of this file you might ask? Thankfully, I found one already on my system hidden in the bowels of the WebSphere file structure. A change of HTTPSender to CommonsHTTPSender resulted in this:

<?xml version=”1.0” encoding=”UTF-8”?>
<deployment
    name=”defaultClientConfig”
    xmlns=”http::://xml.apache.org/axis/wsdd/”
    xmlns:java=”http://xml.apache.org/axis/wsdd/providers/java”>
  <globalConfiguration>
    <parameter name=”disablePrettyXML” value=”true”/>
    <parameter name=”enableNamespacePrefixOptimization” value=”false”/>
  </globalConfiguration>
  <handler name=”WSSResponseConsumerHandler” type=”java:org.eclipse.higgins.sts.binding.axis1x.security.WSSResponseConsumerHandler”/>
  <service name=”Trust” provider=”java:RPC” style=”document user=”literal”>
    <responseFlow>
      <handler type=”WSSResponseConsumerHandler”/>
    </responseFlow>
  </service>
  <transport name=”http” pivot=”java:org.apache.axis.transpotr.http.CommonsHTTPSender”/>
  <transport name=”local” pivot=”java:org.apache.axis.transpotr.http.LocalSender”/>
  <transport name=”java” pivot=”java:org.apache.axis.transpotr.http.JavaSender”/>
</deployment>

A restart of TDI, and hey-presto! Without any further code changes, I was able to connect to my target web-service and authenticate using Integrated Windows Authentication.

Java Object Clashes
Another problem I had, however, was an issue with Complex Types. I've already spoken at length on this blog on Complex Types and how easy they are to handle and I staill maintain that this is true despite the issue I faced.

The target namespace listed in the WSDL I was pointing at had a URL style construction like such:

https://LARGECOMPANY.APPLICATION.SecurityManager/WSDL

Now, generating complex types was throwing an error within my TDI console and the root cause was the namespace above and the fact that it was attempting to create a package called LARGECOMPANY.APPLICATION.SecurityManager.

Some head-scratching and a tweak of the WSDL so that SecurityManager read securitymanager instead resulted in my complex type jar file being created successfully? Why would this be the case, you might ask? I think it may have something to do with java.lang.SecurityManager and a clash of names!

Tweaking the WSDL is fine for solving the problem, but it didn't seem like a sensible approach to me. Asking the owner of the WSDL if they would mind changing the namespace resulted in a "Computer Says No" response. (Actually this is unfair - it resulted in a perfectly valid response explaining that many other clients were using the web-services in this state!)

Looking at the TDI console and the Complex Type Generator function reveals the WSDL2Java Options attribute and a blank value! Using the -p option here got me around the problem quite nicely as such:

-p bigcorpsecurity

The -p option overrides the namespace to package mappings and ensures that Axis will use the value assigned to this option as the package name. Details on all the WSDL2Java Options can be found on the Apache Axis website and it's worth a read if you ever come unstuck attempting to use the Complex Types Generator.

Tivoli Security for Dummies

I've had the pleasure to work with a very entertaining IT consultant from the Land of Dracula recently. He's as self-deprecating as anyone I think I've ever met and constantly refers to himself as a Dummy. To be fair, he refers to himself as a Dummy when he is working with technology that is new to him - I don't for one minute believe that he is actually a Dummy!

When discussing the Tivoli security products, he would constantly over-state his Dummy credentials and ask me questions such as "How do dummies find out how to set up replication on these LDAPs?"

The standard response of reading the manual would be met by "I can't find the manual, or the manual isn't written for dummies like me. Why can't it be written in a format that dummies can understand."

On this particular issue - he's probably right. There are manuals, there are presentations, there are all sorts of documents scattered across the web but very few of them show a simple step-by-step approach to enabling replication for dummies.

"How does the dummy enable Single Sign On from WebSEAL to ITIM?" he would ask.

Again, there are plenty of documents around, but they haven't really been written for dummies and they are rarely complete!

It got me thinking... Maybe I should write a series of Dummies Guides covering some of the basics of the Tivoli Security suite of software. Of course, I'm sure the publishers of that well known series of guide books would take exception to my use of the word Dummies, so I'd need something else. Maybe "Tivoli Security for Newbies"?

Regardless of the title for the series, it seems like a worthwhile thing to-do as I'm conscious that my blog has become ever more technical as time passes with an assumption that my readers grow up alongside me. Refreshers for those readers would be useful and it may encourage the newbies to as well.

So, with that in mind, I'd like to call upon my readers to suggest topics that could be covered (taking the above two as givens for the start of the series). All topics will be considered!

Tivoli Directory Integrator Delta Processing

Tivoli Directory Integrator seems to be a favourite of mine when it comes to writing snippets of information on this blog. I can only assume that the reason for this is that it is so powerful and so capable in a wide variety of situations and that it never ceases to surprise.

It certainly surprised me last week when playing around with the Delta engine. Delta processing wasn't necessarily a new experience for me but requiring delta processing within a single Assembly Line for multiple data sources did present a challenge.

It is straightforward to write an Assembly Line and have the connection details for a connector be programmatically assigned at runtime. Take, for example, the following code:

LDAPConnector.connector.terminate();
LDAPConnector.connector.setParam("ldapSearchFilter", work.SearchFilter);
LDAPConnector.connector.setParam("ldapSearchBase", work.SearchBase);
LDAPConnector.connector.initialize(null);

This code will re-initialize my LDAPConnector using new connection parameters that I retrieve from my work entry.

However, I cannot use the same mechanism when attempting to set the Delta details! The reason was explained to me by Eddie Hartman who writes the excellent TDIing Out Loud. The Delta engine is initialised when the Assembly Line starts, not when the connector is initialised. So any attempts to programmatically set a DeltaDB parameter and re-initialise the connector is doomed to failure. (At least, this is true up to and including TDI v7.1 Fix Pack 4 though Eddie hinted that this "gap" may be "plugged" in the near future.)

So... what to do? The simple answer is to write two Assembly Lines! One of the Assembly Lines will determine the Delta DB table to be assigned (and presumably the target data source for your delta enabled connector). The other will be your main Assembly Line with the delta enabled connector.

The first Assembly Line - which I like to call the driver - would contain code like this:

java.lang.System.setProperty("deltastore", work.DeltaStore);

This would be followed by a call to the second Assembly Line which would have the Delta Store on the connector set as Advanced (Javascript) as such:

return java.lang.System.getProperty("deltastore");

Now, when my delta enabled connector starts up, a properly assigned Delta Store appropriate for the data source is assigned.

One word of warning though. The work.DeltaStore attribute used in the assignment of the Java property should NOT contain any funny characters of any shape or form. For example, if you wanted to assigned a Delta Store name which matched your data source name (which sounds like a mighty fine plan), you may find you have to translate one to the other as such:

Domino Address Book Name >>> Delta Store Name

Scotland.nsf >>> scotland

Northern-Ireland.nsf >>> northernireland

The End Is Nigh

The end may be nigh for all I know and I'm quite sure that will please the rapturists. But my posting title doesn't actually refer to that "end".

The end I refer to is the end of official support for some IBM Tivoli security products. In some cases, nigh isn't very far away at all.

If you are running Tivoli Access Manager for e-Business v5.1, nigh is the end of September. In other words, you have a little over 2 months to upgrade! Trying to get support for v5.1 after September may result in a "Computer Says No" response!

If you are running Tivoli Identity Manager v4.6, you are in the exact same boat as our TAMeb friends above. In fact, I would wager that there are still a number of customers out there running TAM v5.1 and TIM v4.6!

Knowing what I know, I'd rather be in a position where I had to upgrade TAMeb than having to upgrade TIM. You TIM guys better get your skates on!

If you are running Tivoli Directory Server v6.0 - you're beat already. Support ended last year. For those on v6.1, you have a stay of execution until next April (2012).

This may sound crazy, but a programme of work to upgrade your TAMeb and underlying TDS infrastructure (and TIM if you have it) sounds like a good idea if you aren't on the latest versions. And by the way, check out the state of your DB2 while you are at it.

For more information on Tivoli Software Lifecycle Dates, keep an eye on the IBM Software Support site.

WebSEAL Virtual Host

Tivoli Access Manager for e-business' WebSEAL supports the concept of virtual hosting but the documentation surrounding the setup of virtual hosting can sometimes be a little unclear. The diagrams available on Infocenter only help to muddy the waters from what I can tell.

Yet it doesn't have to be so. The concept is actually very simple indeed and can be encapsulated quite easily within a single diagram.

So without over-using words... here's a pretty picture:

All explained I hope? Of course it is!

What Fix Pack Are You On

In the world of commercial software, patches and fix packs can come thick and fast and it is often difficult to stay "current" despite the protestations of customer support.

How often have you had the following conversation?

User: "I'd like to report a problem with this software you sold me."

Customer Support: "What version and fix pack are you running?"

User: "Version 5.1, Fix Pack 1"

Customer Support: "Oh. I don't like the sound of that. You should really be on Fix Pack 6 you know. Why don't you apply Fix Pack 6 and see if the problem goes away. If it doesn't, ring me back."

User: "Does Fix Pack 6 address the issue I described?"

Customer Support: "No. But it might be fixed as a result of some other fix."

Familiar?

It's not necessarily possible to constantly apply fix packs that are released every quarter.The thought of regression testing a fundamental component in your architecture may send shivers down your spine. So maybe applying fix packs once every six months or once a year would suffice?

In my TIM and TAM world, I have a view on what is and isn't acceptable as far as fix packs are concerned. I prefer the latest and greatest but am happy to accept certain fix packs and being relatively fit for purpose.

IBM Tivoli Identity Manager
If you aren't on v5.1, what are you waiting for. Life in the world of v5.1 is a much happier experience and is further enhanced once you are on at least Fix Pack 1 (though preferable Fix Pack 5 or later).

IBM Tivoli Directory Integrator
If you aren't on v7.1, what are you waiting for. At last, TDI gets the interface it deserves and the functionality it promised. Apply Fix Pack 3 at least, though, as most of the niggles had been ironed out by then.

RMI Dispatcher
If you are using agentless adapters, you need to ensure you are running v5.1.3 of the RMI Dispatcher at least. The v5.1.2 had a memory leak! Feel free to deploy v5.1.7 though!

ITIM Adapters
Ah - keep a close eye on these bad boys. Try to keep up with them because they tend to only get an update if there are performance problems. It pays to stay current!

IBM Tivoli Access Manager
If you aren't on v6.1.1, what are you waiting for? Upgrades aren't that complicated! Of course, apply Fix Pack 1 but you will find a life of stability and tranquility with the veteran piece of software.

IBM Tivoli Directory Server
It's got to be at least v6.2 but there's not a lot wrong with v6.3 either. If you have a five in your version, you need to sort out your life!

DB2
Like TDS, your life will need sorting out if your version is antiquated. Anything pre v9.x needs replacing. Honestly. Now. Just do it. Give v9.7 your blessing. It will be good to you for a while.

Take the time to stay up-to-date as much as possible. You may find that the customer support conversation doesn't happen in the first place!

ITIM Custom Participants Explained

One of IBM Tivoli Identity Manager's strengths is in its workflow engine. Visually defining workflows by adding actions, scripts and approval "nodes" can actually be fun and the visual results can often be a thing of beauty.

That said, the visual beauty can often be regarded as ugly compared to the elegance and simplicity within our scripting!

An approval node, for example, allows a workflow designer to select an approver as a particular ITIM user; a group of users associated with an ITIM role; or users with a specific relationship to the entity being operated on (such as a supervisor or service owner). But this can be extended using "Custom Participants".

CUSTOM PARTICIPANTS

Custom participants allows us to make use of the power of scripting. Instead of defining the participant for an approval (for example), we could use scripting to find an approver based on more obscure relationships.

All we need to do within our scripting is return an array of DNs representing each user who will act as an approver for the activity.

USE CASE & SOLUTION

Why would we want to do this? Let's walk through an example scenario:

Big Corp has lots of departments filled with lots of people who are very busy indeed. Supervisors have been identified but are too busy to deal with approval requests coming from ITIM because they operate in a highly volatile world when it comes to access rights. Big Corp has therefore decided that a role called "Departmental Approver" will be created and each department can assign multiple people to the role.

Big Corp, however, has insisted that users' access requests will only be approved by those Departmental Approver who exist within the same department as the requestor.

Native ITIM wizards allow you to select the "Departmental Approver" role as the participant of an approval activity but the link to the department that the approver is in won't exist! Using this mechanism, ALL departmental approver across the entire organisation would be used as an approver. This is where our Custom Participant script can come into play and provide us with a means of selecting Departmental Approver who exist in the same department as the requestor.

The solution to the problem would look a little like this:

// Let's search for the role first - we need its DN
var roleSearch = new RoleSearch();
var roleResult = roleSearch.searchByName("Departmental Approver");

if (roleResult.length < 1) {
    // This is a disaster - the role doesn't exist
    // You should handle this by whatever means suits you
} else {
    supervisordn = roleResult[0].dn;

    // Let's search for Departmental Approvers within our department
    var myFilter = "(&(erparent=" + container.get().dn + ")(erroles=" + supervisordn + "))";
    var personSearch = new PersonSearch();
    var personResult = personSearch.searchByFilter("person", myFilter, 2);

    // For each user found, let's add them to an array
    var myParticipants = new Array();
    for (i=0; i < personResult.length; i++) {
        myParicipants[i] = new Participant(ParticipantType.USER, personResult[i].dn);
    }
    return myParticipants;
}

Of course, we should handle the situation whereby no approvers were found! Hopefully, however, there is enough information above to help you build a robust custom participant solution.