Permission Collection Reconciliation Service Walkthrough - Part 2

In the first article in this series I introduced the concept of the PCRS project and looked at a very clever Package Prompt used to populate a mapping table.

Normally I would not have spent so much effort on the Package Prompts, they usually just ask you for settings and apply them, but this one was quite clever. It also reveals a number of clever tricks so was worth the effort.

As usual my next stop are the GCVs that come with this Package. On a full driver walk through there would be many GCV objects to look at the settings, but for this package there is but one object, which shows up in the tabs as Entitlements.

There are three major sections.

  • Entitlements and Exchange Configuration

  • Permission Collection Reconciliation

  • Advanced Settings

Entitlements and Exchange Configuration

These are the fairly common options that allow you to decide how much entitlement support you intend to use. Specifically in the Active Directory case, there is a minor catch that the Exchange provisioning settings are managed here, even if you do not wish to use the Exchange entitlement.

There are really two main things this entire set of GCVs is trying to control. First actual use of the various entitlements. Will you require a UserAccount entitlement to create a user? It is nice being able to turn it off in configuration instead of finding all the places it is tested for and disabling them.

The second is to build the EntitlementConfiguration object, which resides under the driver. This is needed so User Application, when doing a CODE MAP refresh can read all about the entitlements the driver supports. The GCV's here specify the data that will go into the EntitlementConfiguration object.

You can read about the first iteration of this, when User Application 3.7 came out and started requiring Resources to be mapped to Entitlements, and John Dasilva wrote a nice article about how you would add such support to another driver. The fundamentals were to add all these GCVs and a policy we will see later that ran every driver startup. The PCRS project heavily updates that policy. Convert Driver Entitlements to New RBPM 3.7 Resource Model

If you have read any of my other writings you will know that being told how to do something will not satisfy me, rather I want to know why I am doing this, so I took a shot at dissecting and understanding what was going on there: Converting Entitlements to Resources, more details

I have some fundamental problems with this approach, but conversely I do not have a better one in hand to replace it with. I have a half way idea, but this one works even as I am not happy with its approach. Personally when I need to add a custom entitlement I try to get away with building the EntitlementConfiguration object by hand. The XML is not that hard, and I prefer to have firmer control. But there are drawbacks to that, some pretty severe and not user friendly. So I grit my teeth and accept it as the lesser of two evils. With the advent of the PCRS approach, this gets way more complex.

Each driver will have a different set of GCVs here, since each driver will support a different set of Entitlements. UserAccount and Group are pretty common but any representation of a permission could potentially be represented as an Entitlement.

As an example for an Active Directory driver I have made a Placement entitlement. You would get UserAccount and be placed in a holding container. If a Placement entitlement with a DN as the parameter was granted you would get moved there. Revoked, move back to base. Or perhaps a PassowordExpiration entitlement where you would allow different length of Expiration lengths based on your Entitlement. Licenses in Office 365, or Responsibilities in Oracle EBS are other examples.

This is the fundamental flaw I have with this entire thing is that to support a new entitlement type in your driver you need to make complex modifications of the policy that generates the EntitlementConfiguration object. If I need to add new Entitlements I would generally let the driver generate the current out of the box ones, disable that policy from running again, edit the XML by hand and add in references to my Entitlement.

The original approach I looked at for the 3.7 release did have a fall back, that any other entitlements would be added, but with no configuration data. So you had to go create a set of specific GCVs for you new entitlement as well as updating the policy to use them. Seems like so much work.

I think I would have preferred a structured GCV where for each new entitlement you would just add a new instance of it, allowing for simpler definition and handling, but that is just me.

This driver being Active Directory, supports three entitlements out of the box. UserAccount, Group, and ExchangeMailbox. For each of these three you get the basic question, are you even going to use this at all? If yes, now for some specifics.


Here we have a couple of choices. Enable Login Disabled attribute sync is interesting. If an Entitlement is controlling the account then it should be controlling the flow of Login Disabled, because at some level disabling a user is like removing the entitlement. But you may have security needs such that an Entitlement revoke means delete the user but you still want to be able to globally disable someone under investigation, so let disabled flow.

When the account entitlement is revoked, is the second option, and is very common on the UserAccount entitlement across drivers. What does a revoke of the entitlement imply? Delete the account? Disable the account? Nice having that control..

Third is parameter format, which if you want to use User Application with Roles and Resources, needs to be IDM 4 format which is really JSON. Thus the payload of an entitlement (Inside the path.xml component, in the XML the <param> node will contain something like {"ID":"geoffc"} to carry the values needed to implement the entitlement.)

The legacy format would mean a simple string, that is either the single value, or in the IDM 3.6 plus CMP (Compliance Management Platform) world meant pipe separated KEY=VALUE pairs. This pipe separated format was added to support a fanout style configuration for the SAP User Management driver, How else would provide an Entitlement to specify all the systems you had been granted access, since each system had a unique name.

In general Identity Manager 4 is always the right answer going forward now.


Here the only choice is the parameter format. Chose wisely, chose IDM4.

Exchange Mailbox Provisioning

This one is a bit different since the first question is, are we doing Exchange at all? If so, how do we grant accounts? Thus there are three choices.

  • Use Exchange Mailbox Entitlement

  • Disabled Exchange Provisioning

  • User Policy

If you chose to disable it, no settings required.

If you chose to use Policy, you get asked to specify a default Home Mailbox Database (homeMBD) which is the value that the default policy will use to grant the Exchange account. If you set the homeMDB attribute being sent to Active Directory the Exchange powershell service that IDM installs will convert that to a Exchange command.

The third option is to "Use Exchange Mailbox Entitlement" in which case the payload of the Entitlement (the entitlement value, if you will) is the DN of the Exchange MDB to place the user in.

I ran into an amusing case where I wanted to use Entitlements and load balance across the various MDBs. In the past, for GroupWise, I handled that by querying and maintaining a running count of how loaded each target was. You can read about that approach here:

Others have done the same for Exchange. However, built into Exchange is a load balancing algorithm, and the way you trigger it is by sending a "-database " value of null into the PowerShell. The problem is the driver expects a value so null is not really an option. To solve this, NetIQ called out a special value to send 'defer' that the shim knows to interpret as use load balancing.

Thus if you wanted too, the User Policy mode, with a value of 'defer' would work perfectly. But what if you still wish you use Entitlements? There is no way out of the box to do that. I will probably write up an article on the specific details of how to do this, and include a package you can add to your driver to support it, since it is pretty simple. In a few words, in the Output Transform, catch the query the User App makes to get a list of homeMBD values and add some operation data to it. Then in the Input Transform look for your event with the operation data you set and append one more <instance> node, this one providing the value of defer as the expected DN, and some string identifying it as the load balancing option as the Description.

This way you can make a Resource, assign it an Exchange entitlement, with a value of defer, by the book.

Permission Collection Reconciliation

This is one of those hide/show situations, where changing the first GCV hides or shows the nested values underneath it.

Underneath it we have:

  • Enable Permissions Reconciliation for User Account Entitlement

  • Allow User add via publisher channel

  • Enable Permissions Reconciliation for Group Entitlement

  • Enable Permissions Reconciliation for Exchange Entitlement

  • Enable Permissions Reconciliation for all Custom Entitlements

The gist of these settings have to do with using Entitlements, but getting events from the target system. What should the driver do, if a user is created in Active Directory? In the normal Entitlement model, veto the create. But here you have some better controls. First, if it matches an existing user, add the entitlement for the user, and a Resource that is tied to that entitlement. This way at least your IDM systems view of the target system is still in sync. This is important since Reporting and RBPM rely on the Roles/Resources/Entitlements having meaning and being set properly.

The secondary decision this configuration allows is what to do if the user does not match? Create in the IDV or not. If you allow it to create it picks up the Entitlement and Resource as well.

The same set of controls are there for Group, Exchange, and all other custom entitlements.

One of the things this configuration can do is take a CSV file of DNs and entitlements and update the IDV with them. This is sort of a hold over from the Delimited Text version of this configuration, but extended.

If you have a system that maintains permissions and does not have any API for IDM to connect through (or lack the political will to allow it) as long as it can dump out a CSV of those permissions in a useful format, this driver could import and assign them. The Onboarding Job would trigger the code to go read and reconcile these CSVs.

But also there is a case I still need to understand where you can define entitlements based on other things and those are in the custom entitlement set as well. More on that to come.

Advanced Settings

This too unfolds when you change it and shows the old Resource settings you may have been used too. The GCVs for Data Collection, Role Mapping, and Resource Mapping. Also the Entitlement Extensions XML.

The values set here are meant to be reflected in the entitlementConfiguration object so User App, Catalog Admin, RMA, Reporting, and maybe more can understand the Entitlements each driver offer.

There is lots to be said about the Entitlement Extensions, and I have been reading the DTD trying to wrap my head around them. In short it seems that there are explicit cases called out, when the type of the entitlement is account, group, or exchange. In each case a special XML block is used to represent a second query that would show who has this entitlement in the target system. The primary query in an Entitlement object is to find all the possible values to assign to the Entitlement. This query is for Reporting to validate who actually has the assigned resource, not just what the RBPM model says. As complicated as that seems, I think that is a good thing. Trust but verify.

On that note, a good stopping point. Stay tuned for the next episode.


How To-Best Practice
Comment List