The Active Directory driver in all versions of Identity Manager from 2.0 and up, when we started using DirXML Script instead of XSLT for policies have had a pair of attributes in common. DirXML-ADContext and DirXML-ADAliasName.

These are used to handle the strange circumstance of a rename or move event in Active Directory. The shim cannot tell the difference between a rename or move event. Both cases are actually a modify of the distinguishedName (DN) attribute.

For example: cn=geoffc, ou=Users, dc=acme, dc=com

If this were to change, it would depend where the change occurred to know if this was a move or rename event. If the cn=geoffc part changed, then that is a rename event. If any of the ou=Users, dc=acme, dc=com part changed, then this was a move event, since the parent container for the object is now different, in other words a move event.

You can find the policies that manage this in the Publisher Event Transformation rule set. There have been a number of different shipping default configurations for Identity Manager, so the name of the rule and its exact workings have changed over time. With the advent of IDM 4 and Packages, we should see this stabilize and become more manageable.

The problem with using single valued, simple string attributes for this task is how do you handle a second AD driver in a different domain? Well if the user is only ever in a single domain, that is fine, but if you have worked with IDM then you know that one of the cool things about IDM is how easy it would be to manage users in multiple AD domains, eDirectory, and many other connected services.

If you add a second Active Directory domain to your IDM world, then the values of DirXML-ADAliasName and DirXML-ADContext will be incompatible between drivers and domains.

In the first article in this series Managing multiple Active Directory domains in one IDM system - Part 1 I discussed an approach in general of a plural version of the attributes, using Path syntax.

In the second article in this series Managing multiple Active Directory domains in one IDM system - Part 2 I discussed more of the specific implementation details of making this work. I provided some sample code for making sure you update the attributes correctly.

In the third article in this series Managing multiple Active Directory domains in one IDM system - Part 3 I worked through a good chunk of the Publisher channel rules that need to changed for the DirXML-ADContexts attribute. Still need to do the same for the DirXML-ADAliasNames attribute.

In the fourth article in this series Managing multiple Active Directory domains in one IDM system - Part 4 I worked through the rest of the Publisher channel and started in on the plural DirXML-ADAliasNames that are needed, starting with the Output transform.

In the fifth article in this series Managing multiple Active Directory domains in one IDM system - Part 5 I worked through the Input Transformation rule, and most of the Publisher channel.

In the sixth article in this series Managing multiple Active Directory domains in one IDM system - Part 6 I worked through the rest of the Publisher channel and all but the last rule in the Subscriber channel.

As a quick recap, we will use DirXML-ADContexts and DirXML-ADAliasNames (note the plural) as multi valued, path syntax attributes instead of the single valued string equivalents that IDM ships with. In the previous article I showed some sample code on how you might update that attribute. The key is to remember to find the current value associated with this driver, remove it, then add a new value in.

Next up, is to decide WHERE do we need to make these changes? Well the easy way to manage this is to export the driver configuration as an iManager configuration file, open it in a text editor and then search for the various attribute names.

I wanted to use the latest configuration, since the IDM 3.6.1 has several possible configurations. (V4, V5, V6, and with one of the patches V7). However I happen to know that there are a number of bugs fixed in the IDM 4 Package version of the driver. I was starting a new project that needed an Active Directory driver but could not yet use IDM 4 for this project, instead had to use IDM 3.6.1. So I decided to try something funny.

I started a scratchpad Designer project, set up an IDM 4 Identity vault, added the Active Directory packaged driver, with all the options, and then I configured it for the most part.

Next I exported the driver to an iManager configuration file, and edited that, making it work with IDM 3.6.1. I have to find the time to write up that exercise as that was quite interesting to see how Packages have changed some things in the config files.

Then I searched through to find all the locations these attributes are in use. Here are my results, shown for the two different attributes, in case you want to identify them independently.

DirXML-ADContexts plural:

Input Transform:

     NOVLADDCFG-itp-SubscriberUserAdd 1 rule



Publisher Channel:

     Event Transformation:

          NOVLADDCFG-pub-etp-HandleMovesAndRenames 3 rules



     Create Policy Set:

          NOVLADDCFG-pub-cp 1 rule



     Command Transform:

          NOVLADDCFG-pub-ctp 2 rules



Subscriber Channel:

     Command Transform:

          NOVLADENTEX-sub-ctp-EntitlementsImpl 2 rules

          NOVLADDCFG-sub-ctp-UserNameMap 1 rule.

DirXML-ADAliasNames:

Filter (done)

Schema Map (done)



Subscriber Channel:

     Create Policy Set:

          NOVLADDCFG-sub-cp-Users, 1 rule

          NOVLADDCFG-sub-cp-Groups 1 rule



     Command Transform:

          NOVLADENTEX-sub-ctp-EntitlementsImpl 2 or more rules)



Publisher Channel:

     Command Transform:

          NOVLADDCFG-pub-ctp-UserNameMap 2 rules

          NOVLADDCFG-pub-ctp 2 rules

New rules needed:

     Input Transform

          itp-Convert Plural Attribute



     Output Transform

          otp-Convert Plural Attribute

The last rule in the Subscriber channel that we need to look at is the sub-ctp-EntitlementsImpl which is part of the NOVLADENTEX package.

This policy handles cases where Entitlements are being used to assign access to resources. Entitlements can be granted right now, by three different agents. There is the Roles Based Entitlement driver, which is an interesting beast, which basically uses a dynamic group, whose membership is described by an LDAP query. For example, you might have some flag attribute like acmeAllowADAccess and set it to true when you want to grant access, in which case an LDAP search filter like:

(&(objectClass=User)(acmeAllowADAccess=true))

This has to be edited in the iManager plugin (though I see that Designer as of version 3.5 and 4 imports them, but I have never actually tried managing the, there), and the driver does something very strange when you edit the RBE policies in iManger! In order to edit them you have to click on the Stop driver button. Ok, that looks harmless, just go stop the driver the same way you might via the IDM plugins for iManager on any other driver right?

Well if you then try and start it the usual way, after stopping it via the RBE iManager plugin, you get the following error in trace:

DirXML Log Event -------------------
     Driver:   \ACME-LAB-LDAP\acme\Drivers\IDM\RBE-Entitlements Service
     Status:   Fatal
     Message:  Code(-9005) The driver returned a "fatal" status indicating that the driver should be shut down. Detail from driver: <description>Entitlement Policy editor is currently locked by 'acme\admins\admin@127.0.0.1'.</description>
<document xml:space="preserve"><nds dtdversion="3.5" ndsversion="8.x">
        <source>
                <product version="3.6.1.4427">DirXML</product>
                <contact>Novell, Inc.</contact>
        </source>
        <input>
                <init-params src-dn="\ACME-LAB-LDAP\acme\Drivers\IDM\RBE-Entitlements Service"/>
        </input>
</nds></document>
<application>DirXML</application>
<module>RBE-Entitlements Service</module>
<object-dn></object-dn>
<component>DirXML Engine</component> 

Yep, it turns out that the iManager RBE plugin locks out the RBE driver, and the official way to actually restart it, is to go back into iManager and click Start driver. This IS different than the usual IDM iManager approach, since clicking stop in the RBE plugin writes the attribute Dirxml-SPUIEditorLock on the entitlement policy container. It is only by clicking the Start driver button from the RBE plugin that clears this attribute.

Of course, once you know this, you can go fix it by hand if needed, but until you know this, it can be astonishingly annoying and frustrating.

When an object (almost always a User, but nothing really requires that, you could be using other object classes I suppose) joins the Dynamic group, the RBE driver sees the membership list change on the dynamic group, and adds the Entitlement attributes to the object.

This is the DirXML-EntitlementRef as well as the DirXML-EntitlementResult. The first is a Path syntax attribute, much like our plural DirXML-ADContexts and DirXML-ADAliasNames attributes, and also like DirXML-Associations. The nameSpace component is the state of the entitlement, usually 0 for off, and 1 for entitled. Then the DN syntax attribute, with the component name of volume is set to the DN of the Entitlement being referenced, and finally the component named path is interesting, as in fact it comes across as path.xml instead of the usual path, and it contains an XML result string. Usually with some extra information in it about which entitlement granting agent granted it.

DirXML-EntitlementResult looks like it is a text string that tries to track the history of the various entitlement operations upon this object. This way, each time an entitlement is added or removed an entry is added to this attribute.

Recently I discovered that Designer 3.5 and 4 look like they try to evaluate the dynamic group memberships, every time you do a Compare operation that includes the policies. That is, if you do a Driver set compare, since the Entitlement Policies container is subordinate to the Driver Set container, it is included in the Compare operation, and for reasons that escape me, Designer will ask for all members of these entitlements.

Usually this will not matter, but I was recently at a client that had about 1 million plus users in the development system, (since production is closer to 1.5 million users) and they had 20 plus entitlement policies that includes hundreds of thousands of members.

Once you do the compare, it was taking 20-30 minutes for the compare to complete, and once it does, Designer is crippled, since it looks like it stores the results in memory, and as you can imagine, holding probably a million result nodes in memory eats up tons of Java heap. Then at some point they get marked as unused memory and garbage collection kills the JVM's performance, and Designer is utterly unusable. (I have reported this as a bug, and would love to see a Preference to turn this functionality off if you want, since in most cases it just won't matter. But once you get into large trees, it will kill Designer). My workaround was to make a different admin account to use for Driver compares that had no rights to the Entitlement Policies container. When I compare now, it is nice and snappy as it should be (well with 60 drivers, as snappy as it can be) and I actually find the Entitlement Policies container, since [Public] in this tree has Browse rights, but it cannot read the dynamic group query attribute, so it cannot evaluate the membership. Woo Hoo. This limitation in terms of performance is one of the reasons the RBE approach is being deprecated in favour of the RBPM and Workflow approach as described below.

Another entitlement granting agent is Workflow in the User Application, as part of the Roles Based Provisioning Module (RBPM). That is, there is an operation you can drop onto the Workflow page of the Provisioning Request Definition (PRD), which will grant an entitlement when you want too.

You can read more about where the basic bits and pieces of the PRD's can be found in Designer, since it is alas, quite unintuitive, in these articles:

• Introduction to Workflows and PRDs in Identity Manager - Part1

• Introduction to Workflows and PRDs in Identity Manager - Part2

Hopefully they are a good intro to concept of PRD's and helping you find where all the various things are located. (In short, here there and everywhere in the Designer UI!)

Finally, the third possible entitlement agent currently available is the Roles Based Provisioning Module, which differs from the previous example, as in RBPM, you build up Roles, that consist of a bunch of Resources (and also potentially also other Roles). A Resource, basically maps one to one to Entitlements. As my friend Mike W is wont to say, Entitlements are for computers, Resources are for people. A Resource gets a pretty name, whereas an Entitlement (say a Group entitlement) is usually named by a GUID in the target system, or perhaps some internal goofy name no one will either recognize nor understand.

Thus you can both have a Workflow grant a Role (just like it might grant an Entitlement) or else add a user to a Role via the Roles Administration tab, and the RBPM agent will make a Request object in the Requests container in the RolesDef container in the AppConfig container, under the User Application driver object for your driver set. The Roles and Services driver will process this event,

Now there is an unclear statement I have heard from someone at Novell, that suggests you might be able to make your own Entitlement Granting agent. That is, add it yourself somehow, whether that is by a driver, by an LDIF, or by some additional web service making the changes in eDirectory.

If you are looking for more information on the structure and content of the DirXML-EntitlementRef you can read what Jim Willeke (author of the truly awesome Universal Password diagnostic tool http://www.novell.com/communities/node/1290/password-information-tool, http://www.novell.com/communities/node/8445/examples-jim-willekes-dump-tool) has to say about it in this link:
http://ldapwiki.willeke.com/wiki/Description of Attribute Usage For 2.16.840.1.113719.1.14.4.1.2087

Jim recently informed me that he moved it around on his web site, so if you had been looking for it and could not find it recently it is now back at the above link.

I would love to get that statement clarified to find out if there really is a supported way to add Entitlements yourself or not.

Regardless, this policy in the driver reacts when an Entitlement is revoked or granted, regardless of who did the Revoking or Granting.

This uses the Removed Entitlement and Added Entitlement tokens that are available, and loops through them. There are two parallel rules, one handles the case where in the configuration where the Global Configuration Variable (GCV) named drv.entitlement.remove is selected to Delete the destination account when the Entitlement is revoked, and the case where it is set to disable the account.

In both cases you want to clean up the two attributes, both DirXML-ADContexts and DirXML-ADAliasNames, since once the user is deleted or disabled in the target system, you probably want to get rid of them. Though as I review this, I start to wonder if maybe it would be good to leave the attributes available in the case of the a disabled user since it would be good to be able to track where the matching object in Active Directory lives.

I had wondered as well, where do the extra attributes get set in the case of an add event, when an Entitlement is used. So looking back through the driver, basically, if the GCV that controls using an Entitlement for account creation is enabled, then in the Subscriber Create rule, there is a rule that Vetos creates without the Entitlement being granted.

When the user is successfully created, the Input Transformation rule (itp-SubscriberUserAdd which is part of the NOVLADDCFG package) will add the DirXML-ADContext (or the plural version in this version of the driver) attribute when the event comes through.

The DirXML-ADAliasName (or the plural version in this approach to the driver) attribute is mapped to userPrincipalName, so it will get set in the Subscriber create policy in the policy object sub-cp-Users which is part of the NOVLADDCFG package.

Thus these rules just need to handle removing them under either of the two use cases where the account is being removed (either deleted or disabled).

As usual, each instance of a clear source attribute gets replaced with the typical loop through the Source Attribute of each of the two plural attributes, then as usual, if the current-node's component named volume matches the current driver DN, then this is our drivers and we remove that specific source attribute.

Nothing new or sublime in this case, and that last rule, wraps up this series, with all the instances of the DirXML-ADContext being replaced with the plural multivalued Path syntax attribute, DirXML-ADContexts, and the same for the singular DirXML-ADAliasName and the plural DirXML-ADAliasNames attributes.

This way you can reuse this driver approach for multiple Active Directory drivers, and not have them stomp all over each other.

I have submitted this notion to Novell, and will pass them a driver config, and this series of articles to explain all the changes needed to make it happen. I will attach a driver export to this article and all the other six articles in this series, so you can import it and see all the changes I made or else to use it when you need too.

What I need to do next is to figure out how to bundle this all into a standalone package to distribute as a Identity Manager 4.0 package to make this even easier.

The problem is that the rules are included in two different packages, NOVLADDCFG and NOVLADENTEX and since they are shipped Novell packages it is awkward in the current model to replace them. I need to work through the details to do that. I think I will copy the exiting packages, include my new code changes, bundle them all into a pair of packages, leaving them open and submit it to Novell, so they can add it as an option to the shipping packages. Lets see if they take me up on it.

Here we see a short coming of the current Package model. You can read more about Packages in IDM 4 and Designer 4 in the series I wrote at:

• Let's talk some more about Packages in Designer 4 - Part 1

• Let's talk some more about Packages in Designer 4 - Part 2

• Let's talk some more about Packages in Designer 4 - Part 3

• Let's talk some more about Packages in Designer 4 - Part 4

• Let's talk some more about Packages in Designer 4 - Part 5

• Let's talk some more about Packages in Designer 4 - Part 6

• Let's talk some more about Packages in Designer 4 - Part 7

• Let's talk some more about Packages in Designer 4 - Part 8

• Let's talk some more about Packages in Designer 4 - Part 9

As you can tell from the number of articles it took to describe Packages, there is a ton of complexity to them. For a 1.0 release of a concept it looks pretty good. But here we see that there is no great way to fork a Package, and offer two different path values for it. That is, it would be nice to be able offer two totally different version paths for the two Packages of interest here, and keep both of them updated over time. I think we could do it sort of by incrementing the major version numbers, with say V2.0.x being the plural version, and then just using the second and third version string to manage updates, but it is not entirely clear that this delineates two different versions.

I guess the other way is to make a totally different package, perhaps NOVLADDCFG2 or the like. Would be nice to be able to fork for options a little better. Of course I could have totally missed an approach to doing that. As I find out more, I will let you know.