4.2 Creating Entitlements in Designer

Designer is the recommended tool for creating entitlements.

Designer provides an Entitlement Wizard that steps you through the creation of entitlements. The wizard creates the entitlement XML from the information you provide. In iManager, you must manually create the entitlement XML (see Creating Entitlements in iManager)

  1. In the Modeler view for your Designer project, right-click the driver icon Select Notify under the Subscribe heading, then click New > Entitlement to launch the Entitlement Wizard.

  2. Fill in the following fields:

    Name: Specify the name you want used for the entitlement. This is the name used for the entitlement object in the Identity Vault, and the name that is seen in both Designer and iManager.

    Display Name: By default, the entitlement agents that consume the entitlements use the name specified in the Name field. If you want to specify a different name for the entitlement agent to use, deselect the Use this name for the display name box, then enter a name in the Display Name field.

    For example, the GroupWise driver’s default configuration file includes a predefined GroupWise account entitlement. The entitlement’s name is gwAccount and its display name is GroupWise User Account.

    Description: Specify any information you want to use to describe the entitlement. This field is optional.

  3. Click Next to display the Set Entitlement Values dialog box.

    There are two types of entitlements that you can create. Valued entitlements contain values that are passed to the driver policy that enforces the entitlement. Valueless entitlements do not contain any values to pass.

  4. Select No if the entitlement does not need to include values, then click Finish. If the Add to Filter dialog box is displayed, select Yes, then click OK to enable the entitlement for the driver. Skip the remaining steps in this section.

    or

    Select Yes if the entitlement needs to include values, click Next, then continue with the next step.

    There are two types of values that you can use with valued entitlements.

    Administrator-defined values are defined by you or another administrator. You can define a specific list of values from which the entitlement consumer must select, or you can designate a free-form value that the entitlement consumer defines.

    Application Query values are supplied by the application to which the driver is connected. For example, the GroupWise driver’s default configuration includes a predefined GroupWise Distribution List entitlement that enables users to be added to GroupWise distribution lists. The available distribution lists are discovered through a query of the GroupWise system.

  5. Select Administrator-defined values if the valued entitlement requires values that you will define, click Next, then skip to Administrator-Defined Entitlements with Value Lists or Administrator-Defined Entitlements without Value Lists.

    or

    Select Values from an application query if the valued entitlement requires values that must be discovered by querying the connected application, click Next, the skip to Valued Entitlement that Queries an External Application.

4.2.1 Administrator-Defined Entitlements with Value Lists

The example in the following procedure is an administrator-defined entitlement that allows you to select a listed entry. This type of entitlement is best used through Workflow entitlements rather than Role-Based Entitlements.

  1. Make sure you’ve completed Step 1 through Step 5. The following steps start where those steps ended.

  2. In the Define Values dialog box, make sure that Yes is selected.

  3. In the Entitlement Value field, type the value you want to add to the list, then click Add. Repeat this step for each value you want to add to the list, then click Next.

    Defining a list of values

    In this example, the values are corporate buildings: Building A through Building D. Through an entitlement client, such as an iManager Role-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.

  4. In the Assign Multiple Values dialog box, select Yes if you want the entitlements to be able to be granted to a user more than once and with different values, then click Next.

    or

    Select No if the entitlement can only be granted once, then click Next.

    For example, you might only want to use an entitlement one time to assign a building location to a user. However, because a user could belong to multiple groups, you might want an entitlement that assigns a user to a group to be able to be used multiple times to assign the user to multiple groups.

  5. You are asked if this entitlement is intended to be used by Role-Based Entitlement policies through iManager. If you want this entitlement to be granted or revoked automatically, select Yes to the Role-Based Entitlements question, click Next, then continue with Step 6.

    or

    If you want the granting or revoking of this entitlement to be a manual process (approved by someone), select No to use the User Application, then skip to Step 7.

  6. (Conditional) If you selected Yes to the Role-Based Entitlements question, you are asked if you want to use the Role-Based Entitlements priority to resolve any conflicts that might happen when this entitlement is assigned by different Role-Based Entitlement Policies with different values. You can resolve the conflict by either using the Role-Based Entitlements priority, or by merging the values.

    Merging the values 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. Solving conflicts by priority works if you need to ensure that only one policy is applied to this entitlement at any time.

  7. Click Finish.

  8. If you see the Add To Filter dialog box, answer Yes if you want the driver to listen for this entitlement. This enables entitlements for the driver. The DirXML-EntitlementRef attribute allows the driver filter to listen for entitlement activities, which is necessary in order to use the entitlements you are creating.

    or

    If you don’t want to see the Add To Filter window on entitlements you are creating for any driver in Designer, select Remember Selection - Don’t Prompt Again, then click OK. However, after the attribute is added to this driver filter, you won’t see the Add To Filter window again.

Before you can edit this entitlement, you are asked to save the editor’s changes before continuing. Once the editor is saved, the entitlement displays in the Modeler view.

4.2.2 Administrator-Defined Entitlements without Value Lists

The example in the following procedure is an administrator-defined entitlement that forces the administrator to type a value. You can use this kind of entitlement if you do not have all of the information at the initial setup, so you cannot create a value list.

  1. Make sure you’ve completed Step 1 through Step 5. The following steps start where those steps ended.

  2. In the Define Values dialog box, select No to the question “Do you want to define a list of values?” on the Define Values page, then click Next.

    Selecting this option allows the administrator or users to type in a value. Using this option can be risky however since wrong or misspelled information can cause the value to be incorrect and the action in the entitlement to fail.

  3. In the Assign Multiple Values dialog box, select Yes if you want the entitlements to be able to be granted to a user more than once and with different values, then click Next.

    or

    Select No if the entitlement can only be granted once, then click Next.

    For example, you might only want to use an entitlement one time to assign a building location to a user. However, because a user could belong to multiple groups, you might want an entitlement that assigns a user to a group to be able to be used multiple times to assign the user to multiple groups.

  4. You are asked if this entitlement is intended to be used by Role-Based Entitlement policies through iManager. If you want this entitlement to be granted or revoked automatically, select Yes to the Role-Based Entitlements question, click Next, then continue with Step 5.

    or

    If you want the granting or revoking of this entitlement to be a manual process (approved by someone), select No to use the User Application, then skip to Step 6.

  5. (Conditional) If you select Yes to the Role-Based Entitlements question, you are asked if you want to use the Role-Based Entitlements priority to resolve any conflicts that might happen when this entitlement is assigned by different Role-Based Entitlement Policies with different values. You can resolve the conflict by either using the Role-Based Entitlements priority, or by merging the values. This example uses priority.

    Merging the values 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. Solving conflicts by priority works if you need to ensure that only one policy is applied to this entitlement at any time.

  6. Click Finish.

  7. If you see the Add To Filter window, answer Yes if you want the driver to listen for this entitlement. This enables entitlements for the driver. The DirXML-EntitlementRef attribute allows the driver filter to listen for entitlement activities, which is necessary in order to use the entitlements you are creating.

    or

    If you don’t want to see the Add To Filter window on entitlements you are creating for any driver in Designer, select Remember Selection - Don’t Prompt Again, then click OK. However, after the attribute is added to this driver filter, you won’t see the Add To Filter window again.

Before you can edit this entitlement, you are asked to save the editor’s changes before continuing. Once the editor is saved, the entitlement displays in the Modeler view.

4.2.3 Valued Entitlement that Queries an External Application

  1. Make sure you’ve completed Step 1 through Step 5. The following steps start where those steps ended.

  2. On the Define Application Query page, fill in the fields to define the query and map the query results.

    Defining the application query

    Enter a class to query: Click the Schema Browser button on the right side of the Class entry. The Schema Browser shows you the Classes in the eDirectory namespace that are available. If you know the name of the Class type you want to query, click to select a selection in the Classes tab, then start typing the Class name. The browser jumps to the alphabetical order of what you type. Select the Class name, then click OK.

    Enter a base DN and select a scope to search from: Type the distinguished name (DN) of the directory base where you want to start the search. Select the scope (subtree, entry, or subordinates).

    Map query results to the values used by entitlement consumers: Map the query results from the connected system to values that entitlement consumers can use.

    • Display Name: Defines the attribute that displays in the list of values. Click the drop-down button on the Display Name shown to entitlement consumers list to see a list of Attributes associated with the class you selected through the Schema Browser. The list includes both the Attributes and the Inherited Attributes for the selected class.

    • Description: Defines the attribute that displays as a description for that value. For the description, select Description from the Value drop-down list to map the query results from the connected system to the entitlement.

    • Value: Defines the attribute or token that is the actual value. The Value entry is not seen in the entitlement consumer, but it is the value that is assigned when the entitlement is granted or revoked. In this case, choose Association.

    If you do not use the Schema Browser button when selecting the class, you see only two selections in the Value From Query lists: Association and Source Distinguished Name. If these attributes suit your needs, use them. You can also type the attribute name into the text field. However, if you want to select the attributes from the lists, use the Schema Browser button when selecting a class for the query. You see the attributes and inherited attributes for the selected class.

  3. When you’ve finished defining the query, select Next.

  4. In the Assign Multiple Values dialog box, select Yes if you want the entitlements to be able to be granted to a user more than once and with different values, then click Next.

    or

    Select No if the entitlement can only be granted once, then click Next.

    For example, you might only want to use an entitlement one time to assign a building location to a user. However, because a user could belong to multiple groups, you might want an entitlement that assigns a user to a group to be able to be used multiple times to assign the user to multiple groups.

  5. You are asked if this entitlement is intended to be used by Role-Based Entitlement policies through iManager. If you want this entitlement to be granted or revoked automatically, select Yes to the Role-Based Entitlements question, click Next, then continue with Step 6.

    or

    If you want the granting or revoking of this entitlement to be a manual process (approved by someone), select No to use the User Application, then skip to Step 7.

  6. (Conditional) If you select Yes to the Role-Based Entitlements question, you are asked if you want to use the Role-Based Entitlements priority to resolve any conflicts that might happen when this entitlement is assigned more than once with different values. You can resolve the conflict by either using Role-Based Entitlements priority, or by merging the values.

    Merging the values 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. Solving conflicts by priority works if you need to ensure that only one policy is applied to this entitlement at any time. This example uses priority.

  7. Click Finish.

    In the example shown in Step 2, the query values look for the Source Distinguished Name attribute of the Class name of Group, starting from the Base DN (Blanston) and checking through the subtree from that beginning point. The values that come back from the query are 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>
    <!-- ... ->

    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 exists and meets the query criteria, this information is also collected and shown as other instances of the query.

    The association format value is unique for every external system, so the format and syntax are different for each external system queried.

  8. If you see the Add To Filter window, answer Yes if you want the driver to listen for this entitlement. This enables entitlements for the driver. The DirXML-EntitlementRef attribute allows the driver filter to listen for entitlement activities, which is necessary in order to use the entitlements you are creating.

    or

    If you don’t want to see the Add To Filter window on entitlements you are creating for any driver in Designer, select Remember Selection - Don’t Prompt Again, then click OK. However, after the attribute is added to this driver filter, you won’t see the Add To Filter window again.