Buildup of DirXML-EntitlementResult values causing -625 and -626 errors in sync

  • 7024816
  • 15-Sep-2020
  • 19-Oct-2020

Environment

eDirectory
Identity Manager 4.7.x and 4.8.x
Identity Manager Roles Based Provisioning Module for above versions

Situation

After an entitlement action (grant or revocation) has been completed by the DirXML driver, a result is written to the eDirectory object by adding a value to its DirXML-EntitlementResult attribute.  This is irregardless of whether the operation was successfully or not.  DirXML-EntitlementResult is a multi-valued SYN_OCTET_STRING containing an XML document whose root element is <result>.

Over time, in current versions of IDM, this attribute can build up thousands of values on many of the objects.  When attempting to sync these thousands of values eDirectory can timeout sending them which results in -625 and -626 errors in sync.  This, in turn, prevents the purger from completing.

Resolution

There is a way to change the way this attribute's purging behavior to prevent this buildup.  The following will change the purging behavior from only purging the last value to purging all the values except the last one seen by the agent.

1. Edit and change the GCV in the UserApp driver's dirxml.engine.entitl-rs-purge-type from “current” to “previous”.
2. Ensure the DirXML-EntitlementResult is in the driver filter so it can act on the attribute.
3: Restart the driver and monitor for any buildup on users.

This has been reported to Engineering.  A request has been made to change the default in a future release.

Additional Information

The information below is from an IDM 3.5.1 document.  IDM 4.8 documents should be updated in the future to reflect this as well.

Also found here: https://www.novell.com/documentation/developer/dirxml/dirxmlbk/ref/dirxmlentitlements/

_________________________________________________________________________________________
DirXMLEntitlements DTD

Conceptually, a DirXML entitlement is a named flag that causes a DirXML driver configuration to perform some arbitrary action that is usually related to granting access to some resource in a connected system. Entitlements (as embodied in Role-based Entitlements) have thus far been used for three basic actions: Creating and deleting or disabling a connected-system account, adding/removing connected-system accounts group memberships, and adding/setting attribute values to connected-system accounts.

An entitlement is embodied in an eDirectory DirXML-Entitlement object, which is contained by a DirXML-Driver object. The containment of the DirXML-Entitlement object establishes the correspondence between the entitlement and the implementing DirXML driver configuration. The DirXML-Entitlement object's name is the name of the entitlement. The XmlData attribute of the DirXML-Entitlement object contains an XML document  whose root element is <entitlement>.

An entitlement is granted to and revoked from an eDirectory object via the addition of the auxiliary class DirXML-EntitlementRecipient and the associated DirXML-EntitlementRef attribute to the eDirectory object. The DirXML-EntitlementRef attribute is of SYN_PATH syntax and is “write-managed”. The "volume" (or DN) portion of the path syntax value refers to the DirXML-Entitlement object. Because the attribute is write-managed, the agent setting the DirXML-EntitlementRef attribute value on an eDirectory object must have write access to the DirXML-EntitlementRef attribute on the object that is being written to and must also have write access to the ACL attribute on the DirXML-Entitlement object that is referred to by the DN portion of the DirXML-EntitlementRef value. The “path” (or string) portion of the DirXML-EntitlementRef attribute contains an XML document whose root element is <ref>. The "namespace" (or integer) portion of the DirXML-EntitlementRef attribute is used as a bitmask to hold a set of flags. Bit 0 of the 32-bit integer is used for this flag value and is known as the state bit. 0 means revoked, 1 means granted. Bit 1 is used to flag a granted entitlement that is the result of the upgrade process and is known as the upgrade bit. 1 means that the entitlement was previously granted in the legacy format and is therefore not a change in the entitlement state. Bits 2-31 are reserved for future use.

After the entitlement action (grant or revocation) has been completed (successfully or not) by the DirXML driver configuration, a result is written to the eDirectory object using the DirXML-EntitlementResult attribute. DirXML-EntitlementResult is a multi-valued SYN_OCTET_STRING containing an XML document whose root element is <result>.

Since an entitlement is only a flag that signals a DirXML driver to grant some arbitrary resource, in order for the grant or revoke of an entitlement to actual have any effect, there must be policies on the driver that handle the actual granting or revoking of access to the resource in the connected application. DirXML Script contains explicit support for implementing entitlement policies. The <if-entitlement> condition is used to determine if a given entitlement has been granted or is changing. The <token-entitlement>, <token-added-entitlement>, and <token-removed-entitlement> tokens are used to get a list of the granted or revoked entitlements. The <do-implement-entitlement> action is used to mark policy actions that implement entitlements so that the results of the entitlement can be automatically logged to DirXML-EntitlementResult. The entitlement tokens return a nodeset containing 0 or more <entitlement-impl> elements that can be used to get information about the entitlements and can be passed as an arguments to <do-implement-entitlement>.