What do the various IDM driver object attributes represent – Part 4

geoffc

By: geoffc

July 8, 2011 12:23 pm

Reads: 249

Comments:0

Rating:5.0

In part 1 of this series What do the various IDM driver object attributes represent – Part 1 I discussed some of the attributes that are found on the DirXML-Driver object when you look at it raw in the directory. In the first article I covered the following attributes:

DirXML-Policies
DirXML-NextTransformation
DirXML-ACT2
DirXML-ApplicationSchema
DirXML-ConfigManifest
DirXML-ConfigValues
DirXML-Filter

In part 2 of this series What do the various IDM driver object attributes represent – Part 2 I covered the following attributes:

DirXML-DriverImage
DirXML-DriverStartOption
DirXML-DriverStorage
DirXML-DriverTraceLevel
     DirXML-LogEvents
     DirXML-LogLimit
     DirXML-TraceFile
     DirXML-TraceFileEncoding
     DirXML-TraceLevel
     DirXML-TraceName
     DirXML-TraceSizeLimit

The Trace related attributes all sort of fell out as part of the discussion around the first one, since they pretty much work together as a set of values.

In part 3 of this series What do the various IDM driver object attributes represent – Part 3 I covered the following attributes:

DirXML-DriverID
DirXML-DriverVersion
DirXML-EngineControlValues
DirXML-InputTransform
     DirXML-OutputTransform
     DirXML-MappingRule
DirXML-JavaModule
DirXML-NamedPasswords

In this article I would like to cover the following attributes:

DirXML-NativeModule
DirXML-ReciprocalAttrMap
DirXML-ShimAuthID
DirXML-ShimAuthPassword
DirXML-ShimAuthServer
DirXML-ShimConfigInfo
DirXML-SPCachedExternalEntity
DirXML-State
Security Equals

DirXML-NativeModule

Like the DirXML-JavaModule attribute in part 3 of this series, this attribute lists the name of the module to be loaded. There is a distinction made between a Java module and a native module, since the Java one obviously is executed in the Java environment and the native module is executed in whatever is considered ‘native’ where it is loaded.

The Active Directory driver is an example of a Native driver, which uses adddriver.dll for its work.

This brings up an interesting question, as to what value would be set for the new Sharepoint driver that uses the .NET Remote loader, and of course that answers it, the Java Module for the Remote Loader, and then on the Remote Loader configuration the .NET shim is specified in the appropriate format.

DirXML-ReciprocalAttrMap

Reciprocal Attributes are pretty common in eDirectory, and the engine used to process a pair of them by default. That is, when a user had the Group Membership attribute modified, then the same value was set on the Group object in the Member attribute, its reciprocal pair. The same is true for Equivalent To Me and Security Equals. With the release of Identity Manager 3.5 I believe, this was extended to allow any arbitrary such pairing, all you have to do is specify the values.

There is a user interface in iManager and in Designer to set it, and I personally found it a little confusing at first. What is critical is that you have to define both ends of the mapping. That is you would have to define the User gets Group Membership and is paired with Member on the Group object, but you would also then have to add an entry for Group, and map the Member attribute to User and Group Membership.

There was a bug for a while, that if you touched this attribute in Designer, and did basically no changes, it would save an empty set of values, which overrides the default shipping mappings. Thus you could easily make the default ones stop working. This is long since fixed now, and works fine. Of course, if you manually blank the values as opposed to deleting the attribute, then you will break the default mappings.

DirXML-ShimAuthID

When the driver starts up, depending if it makes sense, it will try to connect as a specific user to the connected system. As I say, if it makes sense. In the case of the Active Directory driver, it makes sense as you need an account with sufficient permissions in Active Directory to do its magic. However, in the case of a Loopback or Null driver, they are not really connecting to anything and thus it does not make a lot of sense.

This can hold pretty much any string value, and the actual value depends on the driver. In the case of the Active Directory driver, in fact two different values are common. The most common is domain\sAMAccountName is you are using the Negotiate connection type. If you have chosen to use Simple as the authentication method, then the format would be a full LDAP DN.

DirXML-ShimAuthPassword

In conjunction with the above attribute, and predating Named Passwords, there is a separate encrypted attribute for the authentication password value. It was having this value available, but not many others that sparked the need for Named Passwords. As I mentioned in Part 3, in the case of the Domino (Lotus Notes) driver, you could potentially need a separate password for the Certifier file for each OU in the hierarchy. (Gotta love Notes! What an interesting system!)

DirXML-ShimAuthServer

This is the third part of a set of connection parameters. This tells the engine what to try and connect too. If this is a driver running local, usually you specify the DNS name or IP address of the server you are connecting too. That could be an Active Directory Domain Controller. A server running your database for JDBC, or your Domino server.

When you are running remote and thus using a Remote Loader, this is where the Remote Loader connection string is stored. When you look in iManager, you pretty much have to type it all on one line. In Designer you get separate fields for the bits and pieces required and Designer puts them all together correctly for you. I do prefer Designer to iManager! This is where the infamous kmo= issue came up before Designer. How do you enable SSL on a Remote Loader to engine connection? Well in Designer, you specify a KMO object name in the field left open for it. In iManager, you have to append the string kmo=’SSL CertificateDNS’ (Or whatever your certificates name is, minus the space dash space ServerName part).

DirXML-ShimConfigInfo

This attribute is an XML blob of all the configuration information. The good news is that the XML uses the same DTD as the Global Configuration Values (GCV), even if there is no user interface for adding one. You could just go to the GCV tab in Designer or iManager and use the GCV editor interface to add what you need, then edit the XML and paste it into the XML of the DirXML-ShimConfigInfo attribute. (The UI lets you ‘Edit XML’ on the Configuration options tab so you can paste the appropriate XML in as needed).

You can read more about the GCV options in these articles:

There is a minor twist, in that there are some additional nodes that are not seen in a GCV XML like <subscriber> and <publisher> which is how Designer and iManager know to break the values up into the various groups of settings. If you look at the Designer page, you will see there are three tabs. Anything under the parent goes on the first tab. Then the Subscriber and Publisher tabs are populated by items under the appropriate tags in the XML. But for the most part the XML looks just like a GCV’s XML.

Every driver is different in the data it has in here. Of particular interest is that there is an XML attribute you can set in a <definition> node that hide = “true’ in which case, the value will be there in the XML, but not shown.

As it happens, in the Active Directory driver (I keep going to this example since it is the most common) has two such configuration options that are hidden in the shipping configurations, and even in the IDM 4 Package versions.

They are the switch to support Incremental Dir Sync which is critically important for managing large group memberships in Active Directory and Enable Deletion of Hidden Objects. Both of these are newer features of the driver, and it is not clear entirely why they remain hidden.

The first option Incremental Dir Sync is important as previous to this, when a group’s membership was modified in Active Directory, a <remove-all-values> and then a large nodeset adding all the values back would come through. When you have several thousand members of a group, which is pretty common in Active Directory since the groups are one of the main security principals, this really can bog down the driver.

When your forest is at a Windows 2003 functional level, then Incremental Dir Sync is available, and the driver can support it. Thus when two users are added, and three removed from a group with twenty thousand members, the driver sees one event with 5 values changing instead of sending the entire group membership.

Enable Deletion of Protected objects is new with the Active Directory in Windows 2008, and actually primarily with the Active Directory Users and Computers in Windows 2008. With the new MMC when you create a container, there is a tick box that asks if you want to protect this object from accidental deletion. It defaults to selected as well. Thus any object that has this, will get an ACE (Access Control Entry) added to the ACL (Access Control List) that blocks deletes. To fix this with Windows 2008 MMC, you need to enable Advanced Options then you can untick it later. With earlier versions you need to dig down into the actual ACE list and remove the ACE.

However, a driver normally has neither of these options available. Thus with the last two releases of the Active Directory driver this was added to allow the driver to continue working as designed, and being able to delete these protected containers.

Again, I am not sure why this one is hidden, nor why it defaults to off. In the case of the older driver configurations, I can understand that they might not be applied to the latest shims, but in the case of the IDM 4 Package version it is unclear, as the shipping Active Directory driver shim with IDM 4 supports this functionality.

One annoying thing about this attribute is that while a GCV can be referenced in policy quite easily with any of the GCV tokens, using the tilde notation (~GCV-Name~), the double dollar sign notation ($GCV-Name$) or in XPATH just a single dollar sign ($GCV-Name) there is no equivalent to get the information out of the Configuration values. There are occasions where it would be useful to be able to read back some of this information to use to configure policy, based on how the driver is configured. In cases like that, it turns out that you would need to read the DirXMl-ShimConfigInfo attribute into a nodeset variable and then use XPATH to select the setting you are interested in. The good news is, with the use of a double slash (//) to search, you can find it pretty easy in XPATH.

Thus the XPATH of $CONFIG-INFO//definition[@name="SettingYouWantName"]/value should work. (If it is a more complex type than just a simple string you may need to modify the XPATH to handle it).

DirXML-SPCachedExternalEntity

This attribute seems to be used in Entitlement policies, but I have no real idea what it is intended for. It is Typed Name syntax, which is sort of interesting, as it has a DN reference component, and then two 32 bit integer components. This comes in handy when you need to store two timestamps about an object.

DirXML-State

This holds the current running state of the driver. It could be Stopped, Running, Starting, Stopping, disabled. There are values stored as integers instead of strings. I probably would not manipulate this one by hand.

Security Equals

While technically not a DirXML-Driver specific attribute, this is of key importance. The Publisher channel gets the rights to write back (and the Subscriber channel to read and see events through DXEvent) to eDirectory via the security equivalence that this attribute establishes.

Often people just make the driver Security Equal to the Admin user which works fine. But a smarter approach is a more limited security role. Consider what it is your driver needs rights to do, and to what objects. Then create an object to grant those rights too, the minimum needed, so that if anything goes wrong, and the driver starts doing silly things, say due to a typo in a Policy, then the damage it can wreak is limited by the rights it has. I heard a story of a driver that started trying to delete hundreds of thousands of objects due to such an error but could not since it did not have sufficient rights.

Well that about completes the walk through of the various attributes available, in use, and deprecated on the DirXML-Driver object. I hope this is helpful when one day you find yourself wondering, what does THIS attribute do!

VN:F [1.9.22_1171]
Rating: 5.0/5 (1 vote cast)
What do the various IDM driver object attributes represent - Part 4, 5.0 out of 5 based on 1 rating

Categories: Uncategorized

Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment.  It just worked for at least one person, and perhaps it will be useful for you too.  Be sure to test in a non-production environment.

Comment