Walking through the Bidirectional eDirectory Driver - Part 1

With Identity Manager 4, SP2 there is a new eDirectory driver, that many of us have wanted for a long time.

As it stands right now, the eDirectory driver is probably one of the more complicated drivers out there. In fact, it is somewhat paradoxical that when getting started with IDM, it is much easier to learn from an Active Directory driver, which is pretty straightforward than from an eDirectory driver.

The main issue is that with the current eDirectory driver, you need two drivers, one in each tree, and really only the Publisher channel in each driver is in use. This makes understanding where to put code to do stuff hard to grasp, and most people new to the driver get confused, as is to be expected. Even experienced people still get confused by it!

With IDM 4 Novell (now NetIQ) committed to a number of new features, but not all would be in the first release. We saw with SP1 the release of a Standard vs Advanced version, and three new drivers (Blackboard, Google Apps, and RSA ACE server).

With SP2, at least one new feature will be the one piece, bidirectional eDirectory driver. Functionally this appears to basically be an LDAP driver, specific to eDirectory, and in fact requires an installation in the target eDirectory still. There is an RPM package to add Changelog functionality to eDirectory. Then the driver uses the new eDirectory change log to get events out.

This means you still have a minor install on the eDirectory side, but better than a full IDM engine, and second half of the driver.

Once you do this it becomes a basic LDAP driver, which is a dead giveaway from the nature of all the DN's required for the Application user DN, and the base DN's all of which are in LDAP format.

This driver comes packaged, and I think it is somewhat instructive to look at the packages that are included for each driver. I started writing this series with an early build of the driver and it progressed as I was writing it, such that I had to go back and revise it to match the new policies. Previously with driver walk throughs it sufficed to say, using the IDM 3.61 configuration but now I need to specify specific package versions for it to make sense.

Basic packages:

eDir2eDir Base 0.0.14
eDir2eDir Managed System Info 0.0.1
eDir2eDir Entitlements 0.0.4
eDir2eDir Default Configuration 0.0.17
Password Synchronization Common 1.0.3
eDir2eDir Password Synchronization 0.0.10
Account Tracking Commmon 1.0.3
eDir2eDir Audit Entitlements 0.0.1
eDir2eDir Account Tracking 0.0.6

You can see that Entitlements, Audit, Account Tracking, and Password Synchronization seem to be the basic add on types, shared by most other shims.

The eDir2eDir Base package basically sets up the shim, and its configuration settings (DirXML-ShimConfigInfo stuff).

The eDir2eDir Default Configuration package basically adds the rules in the Subscriber and Publisher channel as well as the filter and schema map that define basic user synchronization. This is actually the package you will most likely want to consume and build into your own package with your specific customizations. The default does Mirrored and flat placement, but if you want to make changes, you should make a new package, copy from the eDir2eDir Default Configuration packages and when done, use your package instead.

There is a cost to this, since alas, when NetIQ offers an updated Default Configuration package, it is now your responsibility to figure out if any of the changes are useful to your environment. This is actually easier than it seems. On the one hand they should have documented all the changes. (Ok stop laughing). Or at least reference the bug numbers that document all the changes. (I said stop laughing! It could happen! And to be fair, it has happened in some bugs that a bug number is inserted in the Readme, alas the bug rarely has sufficient detail about the solution). Anyway, when this new release occurs, in your test lab, deploy a driver with the default configuration, say at version 1.0.1 and then just upgrade your Designer project to the new version, and then do a compare. Designer itself will find all the differences for you, at least in objects synchronized to the tree, and you can evaluate for yourself if they are relevant or if you even care about the changes made. As it turns out with Packages, there is an entire different class of such items that might be upgraded but are not directly pushed to eDirectory. For example, Package Prompts can make a big difference in show a driver looks after an upgrade of a Package but they do not directly get sent to eDirectory, thus a Compare would be unlikely to pick them up.

This comes to mind since I recently found a reasonably painful bug in all the base packages with Remote Loader package prompts that use SSL. It has been fixed, but it is entirely within the Package Prompt object and my above approach would not detect this change.

I have no great solution, other than to be vigilant. I am hoping I can convince people to write articles like this figuring out what has changed between package versions as they are released. I personally do not think I have enough time to do them all, so I need the help of the rest of you out there to do some as well.

You will notice in that list of Packages that there are two Password Sync packages. One comes from Common and the other is specific to this driver. It turns out NetIQ did something very clever here that it took me a while to figure out and understand.

The Password Synchronization Common package looks a bit funny. It delivers 11 policy objects, and a filter extension (Basically containing nspmDistributionPassword set to subscriber notify, which is the correct setting).

But what is so odd when you first start looking at the package, is that the 11 policies do not have linkage information. That is, they just get written to the appropriate place in the driver, (root of the driver for Input and Output transform rules, and Subscriber or Publisher channel containers for the rest). It is in fact the eDir2eDir Password Synchronization package that delivers the linkage, and in fact two more policies plus the GCV's for which direction passwords should flow.

This actually is quite clever because it allows for one package to deliver the content, (the policies from the Common group) and be shared, then a second package per driver, which you could also copy and modify for your situation that handles how your specific use case needs it.

For example, the default package will set password sync to be bidirectional. If you want to change that for your driver, you actually dirty the package in making the change. Thus you could easily make your own Package, copied from the Novell provided one, and just make the changes in your package to match what you want it to look like. (You can right click on the Novell package in the catalog and select Copy, or you can make your own Package as V0.0.1 and then right click on it, New Package and then there is a Copy from section at the bottom so that 0.0.2 would contain the Novell provided content copied in.

In a similar fashion there are two packages for Account Tracking, a common one and a eDir driver version. I have not looked through those yet at the level I have for the Password synchronization packages but I imagine it is pretty much the same.

The eDir2eDir Managed System Info package is one of those somewhat silly things, I think, that is done all to support a 2 or 4 character string. That is, the Managed System Info package is meant to be used in Reporting to provide the basic information about this connected system. There is one GCV where the four letter code is used to say EDIR instead of AD or GOOG or whatever.

Thus the exact same package in maintained, one per driver, basically just varying the connected system type identifier. Interestingly enough in the initial IDM 4 release they doubled up a couple of them and did not remember to change that code. They have since been new Packages released with the corrected values. I was curious, so I went and looked at all the packages to see what the possible values could be.

I figured there must be a better way to do this, maybe in the Base driver configuration store a GCV value, and have the Managed System Info package just read it, but they decided to go this way. The GCV is called msysinfo.drv.ms.type and you can find it being set in the NOVLEDIR2MSI-ipt-InitManagedSystemInfo policy object, in this line:

<do-append-xml-text expression="$xml//definition[@name='msysinfo.drv.ms.type']/value">
<token-text xml:space="preserve">EDIR</token-text>

Other than that, the packages involved look pretty ordinary, and I am sure there will be interesting subtleties ahead. For one thing, I am sure the twists in the eDir2eDir Password Synchronization will be interesting since as we will see in the configuration steps, syncing the Public and Private Keys instead of Universal Password is supported, so probably have some custom rules to handle that case.

The configuration options have some interesting bits in them and it is worth looking at them.

The main options are just whether to use SSL and if so, what keystore, keystore password, and perhaps which alias within the keystore you would like to use. What is nice is an option to always trust the certificate, which obviates the need for getting the keystore set up right, which means fast setup. If your servers are in a secure network, and not publically exposed, you can provide be use this setting without too much worry.

Next up is which version of Password Sync to use, 1.0 or 2.0. That is use Private Key/Public Key synchronization (1.0) or else use Universal Password (2.0). I look forward to looking at the Password sync package to see how they handle this step differently than a usual driver.

I like looking at the XML view these days and searching for hide="true" since they have been hiding some options on me, (Those monsters!) and in fact there is only one, just under the Password Sync version option.

<definition display-name="Driver GUID:" hide="true" name="driverGUID" type="string">
<description>Specify the Driver GUID.</description>

The reason this is hidden is that there is no need to show it. I am not sure why they need the driver GUID, but since there is a GCV that provides it, and it would be a very ugly long string to ask someone to type, why bother even showing it? They use one of the driver automatic GCV's, dirxml.auto.driverguid which I have seen but never really had a use for before. There is also an auto GCV for the current driver DN, the tree name, and with IDM 4, the LDAP DN of the server the driver is currently running on.

The Publisher settings are interesting as well. We the base container in the target eDirectory which is a <gcv-ref> which means this config value, takes its value from a GCV value. Thus we can set it once, and use it in the base driver config and in a GCV which we can then call in Policy.

Next up are change log settings. The primary technology step that was needed for this one piece eDirectory driver to work was a changelog plugin for eDirectory. On the target eDirectory you need to install a simple RPM (On Linux, I have only seen it demoed on Linux, I assume Windows and other platforms will be supported, though I do not know about Netware) or the like and this allows much of the LDAP drivers functionality to work against eDirectory.

We have a max days without reconnect before the cache is deleted, so as not to crush the disk of the connected system if the driver is down long term. Ignore processing errors, which means if an event comes out of the Pub channel, and errors, do not retry (Ignore) and move on to the next event. There is a control over the size of the changelog in KB. A setting to control whether passwords are allowed to be sent over clear text, and a trace level for the changelog itself.

Well that is a good start into the driver, next up I will start working through policies and see what there is to see of interest in this driver.


How To-Best Practice
Comment List