Novell IDENTITY MANAGER ENTITLEMENTS SERVICE DRIVER 3.6.1 -... User manual

Novell®
www.novell.com
novdocx (en) 17 September 2009
AUTHORIZED DOCUMENTATION
Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
Identity Manager Entitlements Service Driver
3.6.1
June 05, 2009
Implementation Guide

novdocx (en) 17 September 2009
Legal Notices
Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time,
without obligation to notify any person or entity of such revisions or changes.
Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims
any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc.
reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to
notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the
trade laws of other countries. You agree to comply with all export control regulations and to obtain any required
licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities
on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export
laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. For
more information on exporting Novell software, see the Novell International Trade Services Web page (http://
www.novell.com/info/exports/). Novell assumes no responsibility for your failure to obtain any necessary export
approvals.
Copyright © 2008-2009 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied,
stored on a retrieval system, or transmitted without the express written consent of the publisher.
Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this
document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S.
patents listed at Novell Legal Patents (http://www.novell.com/company/legal/patents/) and one or more additional
patents or pending patent applications in the U.S. and in other countries.
Novell, Inc.
404 Wyman Street, Suite 500
Waltham, MA 02451
U.S.A.
www.novell.com
Online Documentation: To access the online documentation for this and other Novell products, and to get
updates, see Novell Documentation (http://www.novell.com/documentation/).

novdocx (en) 17 September 2009
Novell Trademarks
For a list of Novell trademarks, see Trademarks (http://www.novell.com/company/legal/trademarks/tmlist.html).
Third-Party Materials
All third-party trademarks are the property of their respective owners.

4Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009

Contents 5
Contents
novdocx (en) 17 September 2009
About This Guide 7
1Overview 9
1.1 How the Entitlements Service Driver Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2 Role-Based Entitlements Versus Other Entitlements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3 Multiple Entitlements Service Drivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2 Implementation Checklist 13
3 Creating a New Driver 15
3.1 Creating the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.1 Importing the Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.2 Configuring the Driver Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.3 Deploying the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.4 Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Creating the Driver in iManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.1 Importing the Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.2 Configuring the Driver Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.3 Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3 Activating the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4 Upgrading an Existing Driver 21
4.1 Supported Upgrade Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.2 What’s New in Version 3.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3 Upgrade Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5 Creating Entitlement Policies 23
6 Controlling the Meaning of Granting or Revoking Entitlements 27
7 Managing the Driver 29
8 Troubleshooting Role-Based Entitlements 31
8.1 General Troubleshooting Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.2 Conflict Resolution between Entitlement Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.2.1 Conflict Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
8.2.2 Changing the Conflict Resolution Method for an Individual Entitlement . . . . . . . . . . 33
8.2.3 Prioritizing Entitlement Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A Driver Properties 37
A.1 Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
A.1.1 Driver Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
A.1.2 Driver Object Password (iManager Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009
A.1.3 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
A.1.4 Startup Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
A.1.5 Driver Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
A.1.6 ECMAScript (Designer Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
A.2 Global Configuration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

About This Guide 7
novdocx (en) 17 September 2009
About This Guide
This guide explains how to install and configure the Identity Manager Entitlements Service Driver.
Chapter 1, “Overview,” on page 9
Chapter 2, “Implementation Checklist,” on page 13
Chapter 3, “Creating a New Driver,” on page 15
Chapter 4, “Upgrading an Existing Driver,” on page 21
Chapter 5, “Creating Entitlement Policies,” on page 23
Chapter 6, “Controlling the Meaning of Granting or Revoking Entitlements,” on page 27
Chapter 7, “Managing the Driver,” on page 29
Chapter 8, “Troubleshooting Role-Based Entitlements,” on page 31
Appendix A, “Driver Properties,” on page 37
Audience
This guide is for Novell®eDirectoryTM and Identity Manager administrators who are using the
Entitlements Service driver to implement role-based entitlements.
Feedback
We want to hear your comments and suggestions about this manual and the other documentation
included with this product. Use the User Comment feature at the bottom of each page of the online
documentation, or go to www.novell.com/documentation/feedback.html and enter your comments
there.
Documentation Updates
For the most recent version of this document, see the Novell Identity Manager Drivers
Documentation Web site (http://www.novell.com/documentation/idm36drivers/index.html).
Additional Documentation
For information on Identity Manager and other Identity Manager drivers, see the Identity Manager
Documentation Web site (http://www.novell.com/documentation/idm36/index.html).
Documentation Conventions
In this documentation, a greater-than symbol (>) is used to separate actions within a step and items
within a cross-reference path.
A trademark symbol (®, TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party
trademark.

8Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009

Overview
1
9
novdocx (en) 17 September 2009
1
Overview
The following overview assumes that you understand entitlements (as explained in the Entitlement
Overview (http://www.novell.com/documentation/idm36/idm_entitlements/?page=/documentation/
idm36/idm_entitlements/data/be4rlrn.html#be4rlrn) in the Identity Manager 3.6.1 Entitlements
Guide (http://www.novell.com/documentation/idm36/idm_entitlements/data/bookinfo.html)) and
have created the entitlements you want managed by the Entitlements Service driver.
The Entitlements Service driver is one of three entitlement agents that you can use to grant
entitlements, or permission slips, to users. The other two entitlement agents are the role-based
provisioning component and workflow-based provisioning component in the User Application.
The following sections provide information to help you understand the Entitlements Service driver:
Section 1.1, “How the Entitlements Service Driver Works,” on page 9
Section 1.2, “Role-Based Entitlements Versus Other Entitlements,” on page 11
Section 1.3, “Multiple Entitlements Service Drivers,” on page 11
1.1 How the Entitlements Service Driver Works
The Entitlements Service driver grants entitlements to and revokes entitlements from users, as
shown in the following diagram.

10 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009
Figure 1-1 Entitlements Service Driver Process
The driver implements entitlements through the use of entitlement policies. An entitlement policy
contains the following:
Membership: The list of users assigned to a policy. A user can be dynamically assigned to a
policy when he or she meets the criteria for the policy, or the user can be statically (manually)
assigned to the policy. In the above example, User A, User B, and User C are all members of
Entitlement Policy 1. User D and User E are members of Entitlement Policy 2.
Entitlements: The list of entitlements associated with the policy. Users assigned to the policy
receive all of the entitlements associated with the policy. If the user is removed from the policy,
he or she loses all entitlements associated with the policy. In the above example, the
Entitlements Service driver has granted the AD User Account entitlement and GroupWise®
Mailbox entitlement to User A, User B, and User C. Likewise, the driver has granted the AD
User Account entitlement and Exchange Mailbox entitlement to User D and User E.
The Entitlements Service driver uses the following basic process to grant entitlements to and revoke
entitlements from users:
1. The driver evaluates the users within its defined scope to see if they meet the criteria
established for membership in a policy. This occurs whenever:
Any criteria attribute used for determining membership in an entitlement policy is
modified.
A user is moved.

Overview 11
novdocx (en) 17 September 2009
A user is renamed.
You manually initiate a reevaluation of a policy’s membership.
2. The driver updates the DirXML-EntitlementRef attribute of any user whose entitlements have
changed. This includes granting entitlements if the user was added to an entitlement policy or
revoking entitlements if the user was removed from a policy.
3. After the DirXML-EntitlementRef attribute for a user is updated, the Entitlements Service
driver’s job is finished. For the entitlement to be implemented, the entitlement must be defined
on the appropriate driver and the driver’s policies must include the actions required to enforce
the entitlement. For information about creating entitlements and the policies to support them,
see the Identity Manager 3.6.1 Entitlements Guide (http://www.novell.com/documentation/
idm36/idm_entitlements/data/bookinfo.html).
1.2 Role-Based Entitlements Versus Other
Entitlements
Entitlements managed through the Entitlements Service driver are called Role-Based Entitlements,
or RBEs, because they are granted to users who are members of, or have a role in, an entitlement
policy. Only the Entitlements Service driver uses Role-Based Entitlements and entitlement policies.
The two other entitlement agents (roles-based provisioning and workflow-based provisioning
through the User Application) use their own methods for assigning entitlements to users.
The Role-Based Entitlement functionality in iManager lets you manage the entitlement policies used
by the Entitlements Service driver.
1.3 Multiple Entitlements Service Drivers
If your Identity Manager system includes multiple driver sets and you want to use Role-Based
Entitlements with each driver set, you must create an Entitlements Service driver in each driver set.
In addition, the Entitlements Service driver can manage only those User objects that are in a master
or read/write replica on the Metadirectory server (where the Entitlements Service driver is located).
If necessary, you can run multiple Entitlements Service drivers in the same driver set. However, you
must make sure that the scope of users managed by each of the drivers does not overlap. For
example, entitlements for User A should not be managed by two different Entitlement Service
drivers.

12 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009

Implementation Checklist
2
13
novdocx (en) 17 September 2009
2
Implementation Checklist
Use the following checklist to ensure that you complete all of the tasks required to set up and use the
Entitlements Service driver.
Table 2-1 Entitlements Service Driver Implementation Checklist
Task Details
Create the
entitlements you want
managed by the
Entitlements Service
driver
The entitlements, and the policies required to implement them, must be
created for the appropriate drivers. For example, if you want an Active
Directory* User Account entitlement, the entitlement must be created on
the Active Directory driver and the driver’s policies must include the
actions required to grant and revoke the user account.
For instructions, see the Identity Manager 3.6.1 Entitlements Guide (http://
www.novell.com/documentation/idm36/idm_entitlements/data/
bookinfo.html).
Create a new
Entitlements Service
driver
or
Upgrade an existing
Entitlements Service
driver to the new
version
By default, the Entitlements Service driver files (driver shim and
configuration file) are copied to the Metadirectory server when the
Metadirectory engine is installed. You need to use the configuration file to
create a driver in each driver set where you want to use Role-Based
Entitlements. For instructions, see the Identity Manager 3.6.1 Entitlements
Guide (http://www.novell.com/documentation/idm36/idm_entitlements/
data/bookinfo.html)
If you have an existing driver to upgrade, see Chapter 4, “Upgrading an
Existing Driver,” on page 21.
Create entitlement
policies
The Entitlements Service driver uses entitlement policies to grant
entitlements to and revoke entitlements from users.
For instructions, see Chapter 5, “Creating Entitlement Policies,” on
page 23.

14 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009

Creating a New Driver
3
15
novdocx (en) 17 September 2009
3
Creating a New Driver
The Entitlements Service driver files are installed on the Metadirectory server at the same time as
the Metadirectory engine. No other installation configurations are supported; you cannot use the
Remote Loader to run the Entitlements Service driver.
The installation program extends the Identity Vault’s schema and installs both the driver shim and
the driver configuration file. It does not create the driver in the Identity Vault. You create the driver
by importing the driver configuration file and then modifying the driver configuration to suit your
environment. The following sections provide instructions:
Section 3.1, “Creating the Driver in Designer,” on page 15
Section 3.2, “Creating the Driver in iManager,” on page 17
Section 3.3, “Activating the Driver,” on page 19
3.1 Creating the Driver in Designer
You create the Entitlements Service driver by importing the driver’s basic configuration file and
then modifying the configuration to suit your environment. After you’ve created and configured the
driver, you need to deploy it to the Identity Vault and start it.
Section 3.1.1, “Importing the Driver Configuration File,” on page 15
Section 3.1.2, “Configuring the Driver Settings,” on page 16
Section 3.1.3, “Deploying the Driver,” on page 16
Section 3.1.4, “Starting the Driver,” on page 17
3.1.1 Importing the Driver Configuration File
1In Designer, open your project.
2In the Modeler, right-click the driver set where you want to create the driver, then select New >
Driver to display the Driver Configuration Wizard.
3In the Driver Configuration list, select Role-Based Entitlements Service Driver, then click Run.
At this point, the driver is created from the basic configuration file and will run. As with all
Identity Manager drivers, the Entitlements Service driver includes configuration settings you
can use to customize and optimize the driver for you environment.
4To review or modify the default configuration settings, click Configure, then continue with the
next section, Configuring the Driver Settings.
or
To skip the configuration settings at this time, click Close. When you are ready to configure the
settings, continue with the next section, Configuring the Driver Settings.

16 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009
3.1.2 Configuring the Driver Settings
After you import the driver configuration file, the Entitlements Service driver will run. However,
there are many configuration settings that you can use to customize and optimize the driver. The
settings are divided into categories such as Driver Configuration, Engine Control Values, and
Global Configuration Values (GCVs). The settings are described in Appendix A, “Driver
Properties,” on page 37.
If you do not have the Driver Properties page displayed in Designer:
1Open your project.
2In the Modeler, right-click the driver icon or the driver line, then select Properties.
3.1.3 Deploying the Driver
After a driver is created in Designer, it must be deployed into the Identity Vault.
1In Designer, open your project.
2In the Modeler, right-click the driver icon or the driver line, then select Live > Deploy.
3If you are authenticated to the Identity Vault, skip to Step 5; otherwise, specify the follow
information:
Host: Specify the IP address or DNS name of the server hosting the Identity Vault.
Username: Specify the DN of the user object used to authenticate to the Identity Vault.
Password: Specify the user’s password.
4Click OK.
5Read the deployment summary, then click Deploy.
6Read the successful message, then click OK.
7Click Define Security Equivalence to assign rights to the driver.
The driver requires rights to objects within the Identity Vault and to the input and output
directories on the server. The Admin user object is most often used to supply these rights.
However, you might want to create a DriversUser (for example) and assign security
equivalence to that user. Whatever rights that the driver needs to have on the server, the
DriversUser object must have the same security rights.
7a Click Add, then browse to and select the object with the correct rights.
7b Click OK twice.
8Click Exclude Administrative Roles to exclude users that should not be synchronized.
You should exclude any administrative User objects (for example, Admin and DriversUser)
from synchronization.
8a Click Add, then browse to and select the user object you want to exclude.
8b Click OK.
8c Repeat Step 8a and Step 8b for each object you want to exclude.
8d Click OK.
9Click OK.

Creating a New Driver 17
novdocx (en) 17 September 2009
3.1.4 Starting the Driver
When a driver is created, it is stopped by default. To make the driver work, you must start the driver
and cause events to occur. Identity Manager is an event-driven system, so after the driver is started,
it won’t do anything until an event occurs.
To start the driver:
1In Designer, open your project.
2In the Modeler, right-click the driver icon or the driver line, then select Live > Start Driver.
For information about management tasks for the driver, see Chapter 7, “Managing the Driver,” on
page 29.
3.2 Creating the Driver in iManager
You create the Entitlements Service driver by importing the driver’s basic configuration file and
then modifying the configuration to suit your environment. After you’ve created and configured the
driver, you need to start it.
Section 3.2.1, “Importing the Driver Configuration File,” on page 17
Section 3.2.2, “Configuring the Driver Settings,” on page 19
Section 3.2.3, “Starting the Driver,” on page 19
3.2.1 Importing the Driver Configuration File
1In iManager, click to display the Identity Manager Administration page.
2In the Administration list, click Import Configuration to launch the Import Configuration
Wizard.
3Follow the wizard prompts, filling in the requested information (described below) until you
reach the Summary page.
Prompt Description
Where do you want to place the
new driver?
You can add the driver to an existing driver set, or you can
create a new driver set and add the driver to the new set. If you
choose to create a new driver set, you are prompted to specify
the name, context, and server for the driver set.
Import a configuration into this
driver set
Use the default option, Import a configuration from the server
(.XML file).
In the Show field, select Identity Manager 3.6 configurations.
In the Configurations field, select the Entitlement file.
Driver name Type a name for the driver. The name must be unique within the
driver set.

18 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009
When you finish providing the information required by the wizard, a Summary page similar to
the following is displayed.
At this point, the driver is created from the basic configuration file and will run. As with all
Identity Manager drivers, the Entitlements Service driver includes configuration settings you
can use to customize and optimize the driver for you environment.
4To modify the default configuration settings, click the linked driver name, then continue with
the next section, Configuring the Driver Settings.
or
To skip the configuration settings at this time, click Finish. When you are ready to configure
the settings, continue with the next section, Configuring the Driver Settings.
Define Security Equivalences The driver requires rights to User objects within the Identity
Vault. The Admin user object is most often used to supply these
rights. However, you might want to create a DriversUser (for
example) and assign security equivalence to that user. Whatever
rights that the driver needs to have on the server, the
DriversUser object must have the same security rights.
Exclude Administrative Roles You should exclude any administrative User objects (for
example, Admin and DriversUser) from synchronization.
Prompt Description

Creating a New Driver 19
novdocx (en) 17 September 2009
3.2.2 Configuring the Driver Settings
After you import the driver configuration file, the Entitlements Service driver will run. However,
there are many configuration settings that you can use to customize and optimize the driver. The
settings are divided into categories such as Driver Configuration, Engine Control Values, and
Global Configuration Values (GCVs).
To configure the settings:
1Make sure the Modify Object page for the Entitlements Service driver is displayed in iManager.
If it is not:
1a In iManager, click to display the Identity Manager Administration page.
1b Click Identity Manager Overview.
1c Browse to and select the driver set object that contains the new driver.
1d Click the driver set name to access the Driver Set Overview page.
1e Click the upper right corner of the driver, then click Edit properties.
2Review the settings on the various pages and modify them as needed for your environment.
The configuration settings are explained in Appendix A, “Driver Properties,” on page 37.
3After modifying the settings, click OK to save the settings and close the Modify Object page.
4(Conditional) If the Entitlement driver’s Summary page for the Import Configuration wizard is
still displayed, click Finish.
WARNING: Do not click Cancel on the Summary page. This removes the driver from the
Identity Vault and results in the loss of your work.
3.2.3 Starting the Driver
When a driver is created, it is stopped by default. To make the driver work, you must start the driver
and cause events to occur. Identity Manager is an event-driven system, so after the driver is started,
it won’t do anything until an event occurs.
To start the driver:
1In iManager, click to display the Identity Manager Administration page.
2Click Identity Manager Overview.
3Browse to and select the driver set object that contains the driver you want to start.
4Click the driver set name to access the Driver Set Overview page.
5Click the upper right corner of the driver to display the Actions menu, then click Start driver.
For information about management tasks with the driver, see Chapter 7, “Managing the Driver,” on
page 29.
3.3 Activating the Driver
If you created the driver in a driver set where you’ve already activated the Metadirectory engine and
service drivers, the driver inherits the activation. If you created the driver in a driver set that has not
been activated, you must activate the driver within 90 days. Otherwise, the driver stops working.

20 Identity Manager 3.6.1 Driver for Role-Based Entitlements: Implementation Guide
novdocx (en) 17 September 2009
For information on activation, refer to Activating Novell Identity Manager Products (http://
www.novell.com/documentation/idm36/idm_install/data/afbx4oc.html) in the Identity Manager
3.6.1 Installation Guide (http://www.novell.com/documentation/idm36/idm_install/data/
be1l0t1.html).