Walking through the IDM 4 Google Apps Driver - Part 5


With the release of NetIQ Identity Manager 4.0 Support Pack 1 (aka IDM 4.01) some bug fixes, and a few new features were added.

Specifically three partner provided drivers were included, an RSA Driver, a Blackboard driver, and a Google Apps driver.

I discussed some of the new features and bugs fixed in IDM 4.01 in this series of articles:

I have been working on a series of articles walking through driver configurations, policy by policy to try and understand what the driver is doing, under the covers.

You can see more of these walk throughs on a Wiki page I maintain to keep them all together: Detailed driver walk through collection.

For this series of articles I would like to start looking at the Google Apps driver in IDM 4.01, that is provided by Consensus Consulting.

In the first article in the series I worked my way through the Subscriber Event transform and half way through the Matching Policy set.

In the second article in the series I worked my way through the rest of the Matching Policy set.

In the third article in the series I worked my way through the Creation policy set.

In the fourth article in the series I started working through the Placement policy set.

In the previous article I did not quite finish the Subscriber Command Transform, so let's continue from there.

In the policy object, NOVLGGLEORGU-sub-ctp we were up to the rule:

Move User Based on Entitlement Changes

First up there is a check if the GCV for Org Unit placement is set to entitlement, in which case, if the Org Unit Placement entitlement on the object is changing and this is a from-merge event then the rule is evaluated.

Now it is worth noting that a changing entitlement, like a changing operation attribute really means, there a modify (or add if this were an add event) of the attribute in the event document. Remember however that a change could be a remove value, remove all values, or add value. You can read more about this concept in regards to the Operation Attribute token in this article: The various Attribute tokens in IDM Policy

Thus inside the rule, after testing if the Entitlement of interest is changing, which could be adding, removing, or both, the next check is if the Entitlement is available. In the operation attribute that would usually mean there is at least one add-value 1node, In the context of an Entitlement, the if Entitlement test is actually more analogous to the if Attribute token, since it checks the current document to see if it is available, and will query back to the source to see if the source object has it as well. You can read more about Entitlements in this series of articles if you are interested:

If the Entitlement is available then the driver loops over the various values of entitlements in case there is more than one, but also in case there is some error and there are none, in which case nothing much happens, and it moves the organizational unit using the ECMA getEntParamField() function to get the target OU from the payload of the entitlement.

Now if there is only a changing entitlement (the main rule condition block was true to get this far) then the else condition here, (where there is no entitlement available, and thus only a remove or revoke, not an add) then the Org Unit is moved to \ (backslash). Now I do not know what that means in the context of Google Apps, I assume the root of the Organizational space, but I am not certain. I will inquire and report back.

I do know that there is a way to set an Org Unit to be a no mail unit, and therefore, disable in Google apps can mean move the user to that container to disallow email for them. I wonder if this is a similar construct for Org Units.


Break if not an appropriate event

This rule is meant to handle entitlement changes on users that already exist and are associated. So it scopes it out of the gate to only user objects, but with a minor twist, only the attribute DirXML-EntitlementRef is changing, which is the carrier attribute for an Entitlement. This attribute is a Path syntax attribute and thus has several components that can mean all sorts of different things. The nameSpace component usually is 0 for revoked and 1 for granted. The volume component is a DN reference to the DirXML-Entitlement object which is per driver, and stored under each driver and contains the configuration for this entitlements behavior. Finally the path.xml component holds some XML that carries information and the payload. This is where the ECMA getEntParamField() function has been reading its field information from.

Handle users entitlement to Google changes

If the specific Entitlement this driver uses, NOVLGGLEUSER-Account is changing, which like in the Organizational Unit case can mean either being removed, added, or revoked, then rule is processed. This scopes it to the Entitlement of interest, since you could develop your own Entitlement object to use in this driver, and that would get past the scoping rule, since all entitlement grants are stored in the same attribute, DirXML-EntitlementRef on an object.

Then loop over the Entitlement values, thus zero times if being removed, and as many times as being added.

Inside the loop Login Disabled is set to false.

Then using the Removed Entitlements token, we can see all the Remove or revoke events in the event document.

Trace out a message to the log about revoking the users entitlement, and then if the GCV that specifies what to do when the entitlement is removed (gcv.NOVLGGLEUSER.AccountEntitlementLossHandler) is set to DISABLE, then set the login disabled to true, and remove the association in eDirectory.

The way this token works is a bit odd. You use the Remove Association action token. But you need to specify a value in Argument Builder, so you select the Association() noun which means the current objects association. You could calculate a value if you wanted to do it that way, or you could use XPATH of just association to get it as well. But it reads kind of funny in DirXML-Script, but does make sense, once you think about it. You are removing an association, which one? This one.

Next up, if the GCV for Entitlement Loss is set to DELETE then the destination object is deleted and the association is removed from the current object. It is good to remember to do this when deleting a destination object, since the association value is how the audit group tries to figure out how many licenses you should be paying for.

If it a delete case, then we veto the event that got us into here, the modify of DirXML-EntitlementRef that is carrying the entitlement information.

Handle users entitlement to group changes

If the Group Membership entitlement for Users (NOVLGGLEUSER-GroupMembership) is changing then this rule will fire.

Two loops, one through the entitlements being added, and one through the entitlements being removed.

First loop, traces a message of which group is being added via the entitlement to the user, and then adds a destination attribute of Member to the Group object.

I am not sure, but I think that Google like many other systems does not have a reciprocal attribute pairing for group membership. eDirectory stores an attribute on the User object (Group Membership) listing all the groups this user is a member of. It also stores an attribute on the group (Member) of all the users who are member of that group.

Looking at the schema map, I see that the User object has Group Membership mapped to Groups in Google, so maybe it does have the reciprocal pairing. What I would be curious about is whether they are relying on the default engine behavior of reciprocal attribute mapping, except I am pretty sure that only works on the Publisher channel.

It is likely that Google maintains that attribute pairing for you, so long as one is updated. An interesting question, I will see if the developers will answer.

Next up we have four policy objects, the standard password management ones, in fact they come from the default Novell package, Novell Password Sync that most drivers rely on. You can read more about how these policies transform a modify event for the attribute nspmDistributionPassword into a modify-password event to send to the shim, in my series on these policies in both channels:


Basically these four policies enforce the special GCV's called the Password Synchronization in Designer, and Server Variables in iManager. Basically this is where the things like using Distribution Password versus NDS password are set. The distinction is important to know, since the results are very different. A <modify-password> event is a change of the NDS password, and counts as an administrative reset, so the password is expired after being set. But if you enable Distribution Password the policies convert it into a modify attribute of nspmDistributionPassword.

You can read more in the two articles on Password transformation policies, but also in this article on how the drivers all support password tunneling mode, which is even more interesting. Password Tunneling Model in Identity Manager

That completes much of the Subscriber channel (Technically the Output transform is not part of the Subscriber channel, which is sort of a distinction without a difference, since it always comes at the end of the subscriber channel anyway.) Though there is still the Schema Mapping policy set.

Now this is a little sneaky and uses the schema mapping in ways you do not commonly see. That is, there is a traditional schema map object, but there is also a Policy object. This is legal, and you can see this done in a couple of drivers. In the GroupWise driver there is a policy object in the schema map policy set that changes some attribute values depending on which version of GroupWise you are talking too. It seems like some attributes in GroupWise 5.5 vs 6 vs 7 vs 8 changed values (they are odd 5 digit numbers in the GW system under the covers), and there is a GCV about which version of GW you are running. I can say that with GroupWise 2012, (formerly code named Ascot) I hear it will be version 1200 in the GCV.

This in fact is where the Rename Operational Attribute token is meant to be used (for the most part, of course there are other reasonable ways to use it elsewhere). Also with the addition of Reporting in IDM 4, there is a Package needed to be added to the various drivers to properly support some queries the Reporting system might do. As a consequence they do something very cute and clever and have a policy object that is linked in twice, once before the main schema map object and once after that slightly changes an operation attribute, in certain cases so the query can get through the schema map and not be mapped. It took me a while to figure out how they did that in a Package, go try it, and see if you can figure out how to do it. It is annoying, since they did not implement the ability to link content into a Policy set from both locations you would expect it, and its in the unexpected (to me at least) location.


As you might imagine the actual schema map is pretty simple. Users, Groups, Org Units, and the DirXML-GAContact object classes are mapped along with appropriate attributes. I did find out an interesting tidbit related to users and contacts. There are apparently two different API's for setting information on User objects in Google. The first is to provision the basic user, password, and stuff needed to login. There is a second API for profile information which would include stuff that would appear in the Global Address book. Interestingly enough, there is a strange limitation in Google that updates you make to profile data, which includes pretty much all of the Contact objects attributes will be accepted and processed, but will not be visible for up to 24 hours. This is probably to keep churn to a manageable level from Google's perspective but is very annoying from an IDM perspective.

You provision someone and their info is delayed by 24 hours. Alas this is part of how Google works, and you just have to accept it.

Other than that the schema map is pretty standard. What is interesting is the next policy object, in which rules are used to transform schema events, rather than doing it in the Output Transform or in the Schema Map itself.

Stay tuned for the next few articles in the series where I will finish the Schema Mapping rules, work through the Output transform which turns out to be quite interesting. Lots more fun stuff to come.


How To-Best Practice
Comment List