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>,
tokens are used to get a list of the granted or revoked entitlements.
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>.
Top Elements || All Elements || Tree