You can create valued and valueless entitlements. Valued entitlements can get their values from an external query, from an administrator-defined list, or free form. The following sections contain examples of four entitlements you can create.
<?xml version="1.0" encoding="UTF-8"?>
<entitlement conflict-resolution="priority"
description="This is an Account Entitlement"
display-name="Account Entitlement"/>
In this example, the valueless entitlement’s name is Account. This is followed by the conflict-resolution line with the default setting of Priority, which in most cases means that if the entitlement is used by Role-Based Entitlements, the RBE with priority sets the value. (However, because this is an example of a valueless entitlement, valued settings don’t apply.) The Entitlement description is , and the display name is Account Entitlement. This information is all you need to create an Account Entitlement, which you can then use to grant an account in an application.
The Active Directory driver with entitlements enabled has a UserAccount entitlement that Active Directory uses to grant or revoke a user account.
<?xml version="1.0" encoding="UTF-8"?> <entitlement conflict-resolution="union" description="The User Account entitlement grants or denies an account in Active Directory for the user. When granted, the user is given an enabled logon account. When revoked, the logon account is either disabled or deleted depending on how the drive is configured." display-name="User Account Entitlement" name="UserAccount"> </entitlement>
In this example, the conflict resolution is Union, which allows the entitlement to merge the values that are assigned. (Again, valued settings don’t apply to valueless entitlements.) The field explains what this entitlement is used for and why it was created. This is useful information for those who perform future modifications to the entitlement. The actual name of the entitlement is UserAccount, while the <display-name> displays in a managing agent as User Account Entitlement.
The Group and Exchange Mailbox entitlements that come with an entitlement-enabled Active Directory driver offer examples of application queries. Use this entitlement type when you need external information from a connected system to perform an event.
<?xml version="1.0" encoding="UTF-8"?>
<entitlement conflict-resolution="union"
description="The Group Entitlement grants or denies membership in
a group in Active Directory. The group must be associated with a
group in the Identity Vault. When revoked, the user is removed from
the group. The group membership entitlement is not enforced on the
publisher channel: If a user is added to a controlled group in
Active Directory by some external tool, the user is not removed by
the driver. Further, if the entitlement is removed from the user
object instead of being simply revoked, the driver takes no action."
display-name="Group Membership Entitlement" name="Group">
<values>
<query-app>
<query-xml>
<nds dtd-version="2.0">
<input>
<query class-name="Group"
scope="subtree">
<search-class class-name="Group"/>
<read-attr attr-name="Description"/>
</query>
</input>
</nds>
</query-xml>
<result-set>
<display-name>
<token-src-dn/>
</display-name>
<description>
<token-attr attr-name="Description"/>
</description>
<ent-value>
<token-association/>
</ent-value>
</result-set>
</query-app>
</values>
</entitlement>
In this example, the Group entitlement uses Union to settle conflicts if the entitlement is applied more than once to the same object. The Union attribute merges the entitlements of all involved Role-Based Entitlement policies, so if one policy revokes an entitlement but another policy grants an entitlement, the entitlement is eventually granted.
The Group description is useful because of its detail, which explains what was set up through rules in the driver’s policies. This description is a good example of the detail you need go into when defining entitlements in the first place.
The <display-name> is Group Membership Entitlement, which appears in the managing agents, such as iManager for Role-Based Entitlements. The name is the Relative Distinguished Name (RDN) of the entitlement. If you don’t define a display name, the entitlement’s name is its RDN.
The initial query values look for the class name of Group at the top of the tree and continues through its subtrees. These values come from the connected Active Directory server and the application query starts at the <nds> tag. Under the <query-xml> tag, this query receives information similar to the following:
<instance class-name="Group" src-dn="o=Blanston,cn=group1"> <association>o=Blanston,cn=group1</association> <attr attr-name="Description"> the description for group1</attr> </instance> <instance class-name="Group" src-dn="o=Blanston,cn=group2"> <association>o=Blanston,cn=group2</association> <attr attr-name="Description"> the description for group2</attr> </instance> <instance class-name="Group" src-dn="o=Blanston,cn=group3"> <association>o=Blanston, cn=group3</association> <attr attr-name="Description"> the description for group3</attr> </instance> <!-- ... ->
Then, under the <result-set> tag, the information received from the query fills in the various fields. For instance, the <display-name> field receives o=Blanston,cn=group1. The <description> field receives the description for group1, and the <ent-value> field receives o=Blanston,cn=group1. Because more than one group existed and met the query criteria, this information was also collected and shown as other instances.
NOTE:The association format value is unique for every external system, so the format and syntax are different for each external system queried.
Another example is the Exchange Mailbox entitlement:
<?xml version="1.0" encoding="UTF-8"?>
<entitlement conflict-resolution="union"
description="The Exchange Mailbox Entitlement grants or denies an
Exchange mailbox for the user in Microsoft Exchange."
display-name="Exchange Mailbox Entitlement" name="ExchangeMailbox">
<values>
<query-app>
<query-xml>
<nds dtd-version="2.0">
<input>
<query class-name="msExchPrivateMDB"
dest-dn="CN=Configuration," scope="subtree">
<search-class class-name="msExchPrivateMDB"/>
<read-attr attr-name="Description"/>
<read-attr attr-name="CN"/>
</query>
</input>
</nds>
</query-xml>
<result-set>
<display-name>
<token-attr attr-name="CN"/>
</display-name>
<description>
<token-attr attr-name="Description"/>
</description>
<ent-value>
<token-src-dn/>
</ent-value>
</result-set>
</query-app>
</values>
</entitlement>
In this example, the Exchange Mailbox entitlement uses Union to settle conflicts if the entitlement is applied more than once to the same object. The Union attribute merges the entitlements of all involved Role-Based Entitlement policies, so if one policy revokes an entitlement but another policy grants an entitlement, the entitlement is eventually granted.
The description states that the entitlement grants or revokes an Exchange mailbox for the user in Microsoft Exchange, which is enough detail for what the entitlement does. The display name is Exchange Mailbox Entitlement, which appears in the managing agents, such as iManager for Role-Based Entitlements. The name is the Relative Distinguished Name (RDN) of the entitlement. If you don’t define a display name, the entitlement’s name is its RDN.
The initial query values look for the class name of msExchPrivateMDB, which is a Microsoft Exchange function call that begins looking in container Configuration and continues through its subtrees. These values come from the connected Active Directory database and the application query starts at the <nds> tag. The class msExchPrivateMDB has no equivalent in eDirectory, so you need to be conversant in Microsoft Exchange function calls to make such a query. But the query is completed because of the rules and policies that are found in the Active Directory driver.
Entitlement consumers use the information that is retrieved by the query. For example, the entitlement value (ent-value) is passed to Identity Manager policies through the DirXML-EntitlementRef attribute. The display name and description information are displayed by iManager or the User Application and are stored in the DirXML-SPCachedQuery attribute.
The third example is an admin-defined entitlement that creates a grant or revoke event after you select a list entry.
<?xml version="1.0" encoding="UTF-8"?>
<entitlement conflict-resolution="union"
description="This will show Administrator-defined Values">
<display-name="Admin-defined Entitlement"/>
<values multi-valued="true">
<value>Building A</value>
<value>Building B</value>
<value>Building C</value>
<value>Building D</value>
<value>Building E</value>
<value>Building F</value>
</values>
</entitlement>
In this example, the entitlement name is Admin-defined, with a defined display name of Admin-defined Entitlement. (You only need to put in a display name if you want the display name to be different from the entitlement’s RDN.) The conflict resolution line shows the setting of Union, which allows the entitlement to merge the values that are assigned.
The Entitlement description is This will show Administrator-defined Values. The multi-valued attribute is set to true, which allows the entitlement to assign a value more than once. In this example, the values are corporate building letters: Building A through Building F. Then, through an entitlement client such as an iManager Roles-Based Entitlement task or through the User Application, users or defined-task managers can specify the building information, which is then included in an external application, such as Novell eDirectory.
The fourth example is an admin-defined entitlement that forces the administrator to type a value before the entitlement can grant or revoke an event. You can use this kind of entitlement if you do not have all of the information to create a task list at the initial setup.
<?xml version="1.0" encoding="UTF-8"?>
<entitlement conflict-resolution="priority"
description="There will be no pre-defined list">
<values multi-valued="false"/>
</entitlement>
In this example, the entitlement name is Admin-defined (no list), and it uses the entitlement name as the displayed name because there is no display name entry. The conflict resolution is again set to the default of Priority, which means that if the entitlement is used by Role-Based Entitlements, the RBE with priority sets the value. Through an entitlement client, such as an iManager RBE task or through the User Application, you specify the building information, which is then included in an external application, such as eDirectory.