This AppNote describes how to create an Entitlement for the eDirectory driver, and to leverage it with the Workflow/Provisioning Module in order to create two simple workflows for granting or revoking access. I'm assuming that you are familiar with iManager 2.6 and Designer M2, which are the two current versions at the time I wrote this document.
While support is being added to Designer for most of the tasks related to Identity Manager and the Workflow/Provisioning Module, some tasks still require iManager, so we will use both. I mainly use iManager for looking at Policies in this document, but Designer would be equivalent for that. When it comes to creating Entitlements, Designer provides a wizard that makes the process very easy, while doing it through iManager would require writing some XML code. You can learn more about Designer and Workflow/Provisioning or User Applications through the online documentation at http://www.novell.com/documentation.
The first step would be to create an Entitlement for the eDirectory driver. If you install the Active Directory driver with Entitlement support, you will obtain a few Entitlements that you can use right away for Workflow and Provisioning Requests. One of them is called UserAccount, so we will use a similar name for our eDirectory driver Entitlement: eDirUserAccount.
Note that we will create the Entitlement under a LoopBack driver (you can create a blank LoopBack driver using this XML export). I will explain later why we use a LoopBack driver versus working directly with the eDirectory driver
1. To create a LoopBack driver, select it in the Outline view, right-click it, and select Add Entitlement.
Figure 1: Identity Vault in Designer
2. You can call it "eDirUserAccount" if you want to follow the naming used for other drivers such as Active Directory.
Figure 2: The Add Entitlement wizard in Designer M2
3. You don't need values for this Entitlement, so select no; then click Finish.
Figure 3: Setting Entitlement values
4. Go to iManager and create a Provisioning Request. Designer will eventually be the tool of choice for that, but with M2, iManager allows more options.
Figure 4: Creating a Provisioning Request
5. Select a simple workflow template for Single Approval.
6. Click "Create from ..."
Figure 5: Selecting a workflow template
7. Give it a name, such as eDirAccount for the Provisioning Request.
8. Enter a Display name and a Description.
9. Click Next.
Figure 6: Editing the Provisioning Request
10. On page 2 of 6, select an Available Provisioned Resource, or create a new one. If this is the first time you create a Provisioning Request for this driver, you will need to click the " " sign to create a new one.
Figure 7: Defining the Resource and Category
11. Give a name to the Provisioned Resource, such as "eDir-Account."
12. Select the Category(Accounts) and provide the DN for the Entitlement we created earlier with Designer.
Figure 8: Defining the Resource and Category
13. No data is required for this Entitlement, so click Next.
14. Click Finish on the next page.
Figure 9: Configuring the Provisioned Resource
15. Accept the defaults for this page and click Next.
Figure 10: Accepting the defaults
16. Add a trustee assignment for the Provisioning Request. On my system, I selected the OU where my identities(Users) are, which is Identities.ACME.
Figure 11: Adding a trustee assignment for the Provisioning Request
17. Select Active to make the Provisioning Request available to users.
18. Select Grant for this Request to be used for granting access to eDirectory. You can repeat the same steps and select Revoke to create a second Request for revoking access.
Figure 12: Making the Provisioning Request available to users
19. Now that we have our Provisioning Requests, one for Granting access and one for Revoking access, we need some Policies in the driver in order to make the connection. You can look at a driver like the Active Directory driver for example Policies.
Figure 13: LoopBack Driver viewed in iManager
We will create some Policies on the Subscriber Channel. The LoopBack driver writes back to the Source, which is eDirectory itself. There is no connected system.
20. Create an Auxiliary Class called IdM that we will use to communicate Entitlement Events to the other eDirectory tree for which we want to provision accounts. The Class needs no inheritance, no mandatory or naming attributes - just two optional attributes for now.
Figure 14: IdM auxilliary class
21. Create the first attribute to provide the current Account Status; call it IdM-eDirAccountStatus. The status can be Active or Inactive, but other values can be thought of for different situations or needs.
Figure 15: Account Status attribute
22. Create the other attribute as IdM-eDirAccountAction; it is meant to communicate the Action that is required in response to the Workflow or Provisioning Request. Actions can be Create, Disable, ReEnable, Delete, etc.
Figure 16: IdM-eDirAccountAction
These two attributes should be sufficient to cover most circumstances. For example, a new user creation would go like this:
IdM-eDirAccountStatus = Active
IdM-eDirAccountAction = Create
Revoking access would result in:
IdM-eDirAccountStatus = Inactive
IdM-eDirAccountAction = Disable or Delete
Re-Enabling access for a user that has been created then disabled would result in:
IdM-eDirAccountStatus = Active
IdM-eDirAccountAction = ReEnable
We need to modify the filter for both eDirectory drivers in both trees for the 2 attributes IdM-eDirAccountStatus and IdM-eDirAccountAction for User.
Figure 17: Modifying the filter for both eDirectory drivers
Here is the Subscriber Event Transform Rule that reacts when an Entitlement is available for a user, when a Provisioned Resource is Granted through a Provisioning Request or Workflow. Here, we set the two attributes to Active and Create. We write back to the source, which is eDirectory(Identity Vault).
Figure 18: Subscriber Event Transform Rule
The eDirectory Driver is a special driver. It's in fact two drivers, one in each tree: the Identity Vault and the Connected System (with respect to the Vault) in our example. With other drivers, we could write to the Destination (Connected System) on the Subscriber Channel and pass the Active/Create values directly. Or, we completely do without these two attributes and the IdM Class, and instead set up actions directly based on an Entitlement becoming available or being revoked. The LoopBack driver would not be needed, either. The eDirectory driver does not use the Subscriber Channel; it consists of two drivers (one in each tree) with the Publisher Channel only. The Publisher Channel in each tree points to the local tree, and the Connected System which Publishes events is the other tree.
The driver in the provisioned tree cannot consume Entitlements coming from the Identity Vault tree; entitlements belong to one tree only. So that explains why we need the IdM Class with its two attributes to communicate an Entitlement event associated to our specific Entitlement, eDirUserAccount. Additional attributes would be required to communicate events associated to other Entitlements.
Now, why are we setting the Active/Create value pair using the LoopBack driver versus the eDirectory driver itself? The reason is that a driver cannot detect events that it generates itself. Letting a driver react on itself would result in loops (LoopBack) that could consume resources for nothing, and it can also corrupt the data. In almost every architecture effort I am involved with, I leverage a LoopBack driver that I sometimes refer to as the eDirectory Agent. The Loopback Driver is a very versatile driver that monitors data in eDirectory, identifies events, and triggers actions which result in modification of the eDirectory data. Other drivers can then pick up events and trigger actions of their own. The Loopback driver turns eDirectory into a true active directory in certain ways.
The LoopBack driver we are using is very similar to the Entitlement driver used for Role Based Provisioning (refer to the documentation for more on this).
1. Only the filter and Subscriber Event Transform are used. You can create it from Designer or iManager.
Figure 19: Loopback driver view in iManager.
2. The filter for the Loopback driver must allow GUID on the Subscriber Channel in order to detect events on User. The DirXML-EntitlementRef was set to "notify" by Designer when we added the Entitlement (see above). That's all we need for our examples.
Figure 20: Filter settings on Loopback Driver
The Loopback driver can be used for many different needs associated to different drivers and Connected Systems, or it can even be used alone in order to automate some processes in eDirectory. The sooner we include it in our architecture, the faster it can start to solve business logic challenges.
This driver will receive the Active/Create event generated by the Loopback driver in the Identity Vault tree.
Figure 21: The eDirectory driver in the provisioned tree
3. We need to veto the creation action unless we get the Active/Create combination for a new user. This Create Rule will stop being evaluated as soon as the user gets created in the first place and has an association. This is the first step a new user has to go through in order to be created in the provisioned tree.
Figure 22: Publisher Create Rules for the eDirectory driver in the provisioned tree
I did not configure a Matching Rule for my example, because I assume the users do not already exist in the provisioned tree, but depending on your environment, Matching Policies/Rules may need to be implemented.
4. We need to set the value pair to Inactive/Disable or Inactive/Delete depending on if we want to disable accounts in the provisioned tree or simply delete them.
Figure 23: Event Subscriber Rule for managing a revoke event, which means the Entitlement is not available any more for the user
The Inactive/Disable value pair results in the account being disabled.
Figure 24: The Publisher Event Transform Rule that disables an account for the eDirectory driver in the provisioned tree
If the attribute IdM-eDirAccountStatus exists and is set to Inactive, this means the user is not a new user. The value pair set by the Loopback driver is Active/ReEnable.
Figure 25: The Subscriber Event Rule for the LoopBack driver in the Identity Vault that detects when a user previously created and disabled needs to be re-enabled
Figure 26: The Publisher Event Transform Rule for re-enabling a previously created user that has been disabled
5. We can now create a new user and test our logic.
Figure 27: The iManager form for creating a new user
We absolutely need to configure the Manager attribute for our new user, because the Provisioning Request will search for this value in order to figure where to send the Request.
Figure 28: Configuring the Manager attribute for the new user
6. Log in to the User Application portal with the newly created user.
Figure 29: User Application Portal
Figure 30: Login page for the new user
7. Select Requests and Approvals.
Figure 31: Welcome page for the new user
8. Select Request Resource.
9. Select All in the Resource Category.
10. Click Continue.
Figure 32: Setting the Resource category
11. Select the eDirectory Accounts Resource.
Figure 33: Selecting the Resource
Note that you also see a Resource called eDirectory Accounts Disable. The user, once Entitled, can select this Resource is order to be de-Entitled for eDirectory, if you created the second provisioning request for a Revoke(see above). We have the logic to support that event, which will result in the user being Disabled in the provisioned tree. You can re-enable the account later if the user requests the eDirectory Accounts again and the manager approves it.
The eDirectory Accounts Disable Resource would be connected to a business process in which users request for their access to be removed in the provisioned tree. This does not sound like a likely event, unless we are in an situation where we invoice users for access to Resources, in which case they would be encouraged to terminate their access to Resources and the accompanying monetary hit. But even if a Provisioning Request based on this business process does not sound likely, it is sufficient to demonstrate that our underlying business logic can cope with Revoke Entitlement event.
In practice, Provisioning Requests would be aligned to Business Processes, and you can probably think of better example for Workflows that result in a Revoke Entitlement event. But whatever the Workflow or Provisioning Request that you design, the underlying business logic for our connectors should be able to cope with the events, or you should be able to adapt it to deal with other types of events.
12. Provide a reason for the Request, and then click Submit.
Figure 34: Request reason
13. Go to My Requests to see the pending Request.
Figure 35: Pending Request
14. Log out and log in as the user's manager.
Figure 36: Manager login
15. The manager can see the Task for the pending Request. Let's select it.
Figure 37: Task for the pending Request
16. The manager can claim the Request, provide an optional comment, and click Approve.
Figure 38: Approving the request
The result will be an available Entitlement for the user and the Active-/Create-value pair generated by the eDirectory driver in the Identity Vault. The Loopback driver will change the value pair to Active/Create, and the eDirectory driver in the provisioned tree will then create the user.
Hopefully, this document will assist you in taking full advantage of the Workflow/Provisioning Module, even for drivers that do not come with Entitlement out-of-the-box. Once you understand the basic principles, you can look at drivers with Entitlements and implement other Entitlements on the same drivers or on different drivers.
While the Aux Class/Loopback driver approach is not the only one that would work for enabling Entitlements for the eDirectory driver, I have used similar approches in many projects over the past few years, including projects that have reached the production stage. So I am confident that this approach is solid and flexible. The Loopback driver is a good buddy of mine.
Please, do not hesitate to send me some feedback, comments, or questions at firstname.lastname@example.org