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 (https://www.netiq.com/documentation/identity-manager-46/entitlements/data/bfnrgf6.html), 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.
Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment. It just worked for at least one person, and perhaps it will be useful for you too. Be sure to test in a non-production environment.