Adding new custom entitlements to a driver (and getting it to work)

Recently I ran into a need to add a new custom entitlement to an Active Directory driver, along with some custom policies to implement the entitlement. I found that the documentation does not include a few interesting bits and pieces, leading to confusion and frustration. So, here are the details.

If you look at the documentation (, there is a nice section here on how to add a new entitlement. Easy. No problem. You can do that, it works exactly as documented. Well, sort of. Designer doesn't seem to follow exactly the script as laid out in the documentation, but it's close enough to follow.

But, to use an entitlement, you need to do more, of course. There's the UserApp (Roles Based Provisioning Module). You have to go to the Roles catalog, and create a Role. You have to go to the Resource catalog, and create a Resource. You add the Resource to the Role. Then, finally, you can add your new Entitlement to your Resource. And ... where is it? Your new Entitlement isn't showing up.

The UserApp doesn't actually read Entitlements. There are a few other steps. In order for the UserApp to see the Entitlement, it has to be added to the EntitlementConfiguration object. The UserApp searches for EntitlementConfiguration objects, reads those, and that is what you see in the dialog to add the Entitlement to the Resource.

EntitlementConfiguration objects are just an XML listing of the Entitlements, with some additional bits and pieces for language localization support, and the L10N* objects used for that.

You can edit the EntitlementConfiguration object, it's just yet another object full of XML. But not. You can try to do that, and it will seem to work initially, but what will happen is that your changes will disappear later. The EntitlementConfiguration object is dynamically built, on the fly, every time the driver starts. It is created and managed by the NOVLADENTEX-Startup-InitEntitlementConfigurationResource policy that runs every time the driver starts. This policy searches for Entitlement objects, L10N* objects, and then builds a new EntitlementConfiguration object based on what it found. This object also contains a "last updated" time stamp, which changes every time the driver starts, showing that the policy does not attempt to update it, it just overwrites it with a new copy.

How then do I get my new custom Entitlement into this object? A co-worker ("Hi Geoff!") adds a custom policy to the Startup policies, which then pokes his custom Entitlement into the EntitlementConfiguration object. This works, but seems more complicated than should be necessary, and has to be updated each time to add more entitlements. I decided that I didn't like that approach, and kept digging.

In an obscure forum post, I found a clue. There was a reference to a Linux driver that wouldn't implement Entitlements at all. Digging in to the solution posted on that thread, I found a pointer to some interesting references to parts of the NOVLADENTEX-Startup-InitEntitlementConfigurationResource policy that I had previously ignored, and to some driver objects that I had also previously not paid much attention to. They turn out to be the key to making this work with minimal effort.

The solution: After creating a new Entitlement on the driver, find the Mapping Table object named "PermissionNameToFile". This object does not seem to be documented anywhere, its name certainly doesn't make it obvious what it's for, and even looking at it (it is initially an empty mapping table) does not really yield any clues as to what it's for. But, if you put your new Entitlement in the "entitlementName" column, put "CN" in the "assignmentAttribute" column, ignore "csvFile", and put a "true" or "false", whichever is appropriate, in the "multivalued" column, you're good to go. Deploy the Entitlement, and the Mapping Table. Now restart the driver.

On startup, as usual, the NOVLADENTEX-Startup-InitEntitlementConfigurationResource policy runs, finds the various Entitlement objects, and creates a new EntitlementConfiguration object. The difference now is that it will find the new custom Entitlement because it was added to this undocumented mapping table, and will happily put it into the EntitlementConfiguration object for you, ready to use.

Now, finally, you can go to the UserApp, refresh the Entitlement code map, and you will see the new custom Entitlement as an option to be added to a Resource.

Simple, right?


How To-Best Practice
Comment List
  • You need to look at the policy that makes the Entitlementconfiguration object.

    Usually this is in the Startup policy set as David called out.

    Usually you have to add your own entitlement handling in that policy. Or in the next policy, intercept the write to eDir of the modify for attr-name XMLData on the EnttlementConfiguration object and tack on your extra set of nodes.

    As always, trace is the way to show what happens and why...  In this case I would suggest moving to the User Discussions area instead of comments on an article for further troubleshooting.

  • Hi,

    I have the issue on an eDirectory driver and I followed the procedure to update the mapping table. First I had to create one as it did not exist, and then I updated it adding all custom entitlements. But it did not work. Checking the driver log I could see that the query for the entitlements returned all of them, but the EntitlementConfiguration object was updated only with the default Account and Group entitlements. As I did not have the mapping table, is there any other configuration that needs to be done to make it work?