Conceptually, a DirXML entitlement is a named flag that causes an Identity Manager 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.
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 Identity Manager 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 Identity Manager 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 an Identity Manager 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>.
See DirXML Entitlements DTD Elements for a list of all of the elements in the DirXML Elements DTD.