Use integrated identity information to create and manage identities and control access to enterprise resources. We provide identity and access management, single sign-on (SSO), access governance, and more.

Detect and respond to all potential threats quickly and decisively. By monitoring user activities, security events, and critical systems, we provide actionable security intelligence to reduce the risk of data breach.

In this article I want to talk about what it means for a driver to support entitlements.

If you read the documentation, then you will see that some drivers are reported to support entitlements with either the configuration file (Pre-IDM4) or via a Package configuration (Post IDM 4). On a side note, the documentation is getting better, but if you happen to be reading it and see something wrong, or missing, or maybe just a simple addition that would clarify things, then make sure to click the Add Comment link at the bottom of every page (Online docs only, no idea how to do this for the PDF versions, sorry). This opens a bug for the documentation writers to look at. They alas, do not often get back to you, but magically in the darkest of night changes will appear. It is worth doing, since it makes the docs better for everyone involved.

At the moment, the following drivers are said to support entitlements in IDM 4.01. I have grouped them into three categories. There are the simple case, where the documentation says they support entitlements out of the box. Then there are those that either do not specifically say they support it entitlements or else explicitly say they do not support them. Finally there is a third category for utility drivers, where Entitlements would make no sense to implement at all.

Entitlements supported out of the box (14 in total):

These are not yet configured to support entitlements out of the box in IDM 4.01 (12 in total):

You will notice that there are some drivers where Entitlements make no sense, the third category. I.e. The Work Order driver does not entitle some object to something, rather it delays actions for a period of time. The ID Provider is more of a service driver to generate unique ID’s within the system. The Entitlements Service driver is one of the granting agents that actually processes entitlements, but of course does not itself contain any entitlements.

I think that the list is instructive (and the fact there are over 30 drivers) by itself, but understanding what supporting entitlements means is probably most important.

As discussed in part 1 and 2 of this series, Entitlements are just attributes. They are granted by something (Currently 3 supported agents that grant entitlements), they are really just a value in a multi valued attribute and they store the results in another attribute.

So supporting entitlements is not really a driver side issue. The driver really has to do nothing to support them, it is all a policy thing in the engine. Now there happen to be some specific tokens that if you use them, everything works better, but even if you did not, most of the system would still work.

For example, we have a condition test. If Entitlement. As usual, there is equality testing, for a valued entitlement. There is availability testing, which is helpful. This one has some subtle bits worth talking about later.

There is an Implement Entitlement action in Policy Builder. Why would you use this? Well that will make a bit more sense later when talking about how you might actually use entitlements.

In the Argument Builder there are two nouns, Removed Entitlement, and Entitlement. These allow you to select the entitlement that is changing to use. (You need to pass a nodeset of the entitlement to the Implement Entitlement, and this is the easiest way to get the proper one to pass in).

That is just 4 tokens in total to handle entitlements, yet they seem to have so much power in the system. How does that all come together?

Well if you look at any of the current drivers from my list that actually support entitlements out of the box, you can see how they do it. The principle is simple, how you implement it can get complicated.

The most basic thing to remember is that the entitlement for this ‘thing’ is a gatekeeper. You can’t get this ‘thing’ until you have the entitlement first.

Those of you who are familiar with IDM should immediately know where this should be handled. Those who do not immediately get it, you should really take a few minutes and read David Gersic’s truly excellent (in the Bill and Dave sense) series on what each policy set in the driver flow does:

Of course this should be implemented in the Create policy set. Specifically the Subscriber channel Create policy set. The Create rule is where you specify minimum requirements before creating something in the connected system. Just like many drivers will veto a User create if there is no nspmDistributionPassword in the event, since usually you want a password before you create a user. At this point in the policy set you would want a rule that requires a specific entitlement or else the event is blocked. This works for later modify events, as since the object is not yet associated, the modify gets converted to a synthetic add and thus ends up back in this rule again.

Now before you may have noticed I referred to entitlements being the gatekeeper for a ‘thing’ in a connected system. I used that term specifically as there are at least three good examples in shipping drivers of things that Entitlements could enable you to get. The obvious one is a User object, an account. But less obvious is the fact there are Group entitlements, where getting the entitlement means you get added to a groups member list. Even less obvious at first, but makes great sense once you think about it would be an entitlement for a mailbox (whether that is in Exchange, GroupWise, or Notes/Domino).

These three are by no means the only options, they just happen to be the three I know of. In principle and in practice you could add an entitlement for anything that makes sense in your target system. Perhaps you have some physical device you represent in the system. An entitlement would be a good way to indicate it if the target system provisions it somehow. Perhaps you have some structure that is basically like a group in your target system, but it represents an access role, you could use an entitlement to represent it as well. For simplicity lets just consider Users as the thing of interest.

As was discussed in the first two articles in this series, the Roles Based Provisioning Module (RBPM) builds Roles out of other Roles and Resources. Resources, generally map one to one against Entitlements. Thus by representing these other ‘things’ as entitlements, then the RBPM module can deal with them.

So where else should we enforce the entitlement requirements?

Well on an add event (synthetic or otherwise) we will get a Match attempt made, we should decide if we let a match even proceed, without an entitlement or block it. This could let us block it even before it hits the Create policy set.

Then we have the additional case of managing what happens when an Entitlement is changing. What should you do when you revoke an entitlement for an already associated user, or even grant an entitlement to an already associated object (say in the case of a mailbox entitlement.)

If you look at the various drivers that have implemented entitlements in Policy you will see that they often have a Global Configuration Variable (GCV) to control whether a revoke event maps to a delete or disable in the target system. As always, this is a case by case thing. Each use case should be considered separately. This is typically done in the Subscriber channel Command Transform.

In fact, I think this is why in some of the listed drivers as not having Entitlement support in Policy, are lacking such support.

Some of the drivers are just plain too generic to make sense to pre-build any kind of entitlement handling. This is probably the JDBC and Delimited Text drivers are lacking such support. What does an event mean in the Delimited Text driver? Well it depends on so much context of how you choose to implement it that providing one in advance is almost impossible.

Same thing with the SOAP driver. Every SOAP system seems to be different. Though in reality, the SPML and DSML configurations basically are generalized SOAP API’s for handling User like objects, so they could probably get some kind of entitlement enabled. But it would only be useful in a couple of cases. Now that sounds like a reasonable excuse to avoid it, but most drivers I have looked at use a GCV to control whether Entitlement enforcement should be enabled or disabled. In which case the SOAP driver could benefit where it works by turning on the GCV and then off for when it will not be helpful.

The Sharepoint and Salesforce.com driver I suspect it was just an oversight

The SAP HR case is interesting, as really this is more of a Publisher channel driver, focused on getting authoritative information into the identity system. Sort of the same thing for PeopleSoft.

Thus so far it looks like we need some kind of rule in the Matching or Create policy sets to handle users who do not yet exist in the target system.

Then we need something in the Command transform to handle the case where an entitlement is being revoked on an existing user. (If the user does not yet exist, and they get granted an entitlement, then that generates a synthetic add and then the policy in the Match or Create will control it. But for Group or Mailbox style entitlements we should probably handle granting as well, since the user can already exist with or without the extra entitlement).

I think the way to do this is to mock us some sample rules in Designer, and build them into a Package and then attach it. The good news is that the Package may not work with versions of IDM before 4.0 but it is really easy in an empty Driver set to just import the policy in Designer 4.01 (there are some huge memory leak fixes between 4 and 4.01 so get rid of 4 and upgrade to 4.01 before you do anything else!) and then look at it, and copy the policies into an older driver.

On top of all this we need to remember to handle the Entitlement to Resource mappings that RBPM needs in order to work. This was all discussed in an article by Volker Schreuber and John DaSilva, and I wrote a nice companion piece explaining what their policy is doing. So I think that is worth including in the Package as well.

This should all fit nicely into a reasonable Package. Now the problem is, really you need to customize this more and into what you need. The good news is you can use the Package I provide and copy the policies into your own Package, so that you can easily manage upgrades and versioning as you work on it. Basically no one set of rules will suit every case, nor even most of the cases, but lets see how many can be handled.

If you want to read more about Packages, since they are lots of fun and very interesting, take a look at this somewhat wordy series on the topic:

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.