Talking about Entitlements - Part 2

Novell Identity Manager introduced the concept of Entitlements several versions back. In fact, I am not sure when they got added, I imagine around the Identity Manager 3 or 3.5 time frame.

As a reminder, since it is handy to have the XML floating around, an Entitlement is DirXMLEntitlementRef attribute value, that would look something like this if you queried for it in Policy:
<nds dtdversion="3.5" ndsversion="8.x">
<product version="">DirXML</product>
<contact>Novell, Inc.</contact>
<instance cached-time="20110221221739.710Z" class-name="User" src-entry-id="813253" timestamp="1298326659#1">
<attr attr-name="DirXML-EntitlementRef">
<value timestamp="1298326653#2" type="structured">
<component name="nameSpace">1</component>
<component name="volume">\ACME-TEST-05\services\IDM\DriverSet\ADDriver\EntitleTest1</component>
<component name="path.xml">
<id>services\IDM\DriverSet\Entitlement Policies\RBE-RoleTest1</id>

There are three entitlement granting agents available from Novell right now.

  • Roles Based Entitlements (RBE) driver,

  • Roles and Resources driver (part of RBPM 3.7)

  • Workflow (via Grant Entitlement or Role activity)

In Part 1 of this series ( Talking about Entitlements - Part 1 ) I talked about Entitlements in general, and the first of those agents, the Roles Based Entitlements driver.

In this article lets talk about the next agent, the Roles and Resources driver, which is part of the Roles Based Provisioning Module (3.7 and 4).

This driver is interesting as it actually does a whole bunch of different things, and I wish I had the time to go catch it in the act of doing each of those various things.

For example, it is not just the Roles driver as it was in IDM 3.6.1 with the Roles Based Provisioning Module (RBPM) or as it was called back then just the Provisioning module. With the release of IDM 3.6 and RBPM 3.7 (and the same is true of the RBPM in IDM 4) it because the Roles and Resources driver as it also manages Resources now.

Resources are an additional abstraction layer on top of basic entitlements, primarily because the entitlement names for groups would be the GUID in the connected system, which is pretty darn ugly and there is no way an end user would succeed at picking their entitlement from the list in that circumstance. So Resources map, usually one to one, to Entitlements. This way, the Resource is named HR-Accounting-AD and the entitlement is an ugly GUID (By ugly I mean a 16 or 20 digit hexadecimal value).

Now Resources can be assigned to Roles. There are three levels of Roles provided for in the RBPM model.

Thus a Role can be made up of other Roles, each of which may also be made up of other Roles, but at the lowest level they probably have some Resources attached to them. The Resources are really just pointers at Entitlements, so when someone is granted a Role the driver has to parse that apart, add the Role, then enforce whatever the Role defines in terms of other Roles (I think this is the case, I have not actually tested whether it drops an attribute value for each Role that is included in a Role or just the parent Role.) and the Resources they entitle the user too, and finally the Entitlements that the drivers will actually react too and grant the underlying privilege.

That is one busy little driver, isn't it? Notice that this happens in the Roles and Services driver, not in the User Application per se. The distinction is that the RBPM module (Usually managed via the User Application, either in a user request for a Role, or a Workflow process that grants a Role, or possibly even Role Mapping Administrator deciding to modify some Role definitions.) has granted a Role. This is expressed by the creation of a RoleReq object in the AppConfig container. There are other objects stored there, things like PRD (Provisioning Request Definitions), the DAL (Directory Abstraction Layer) configuration, the Roles catalog, Roles definitions and so on.

A quick diversion about User Application and the AppConfig container. Why does the User Application (A Web application) need an IDM driver? Well there are a couple of reasons, but one of them is as simple as the User Application (Web app) needs a place to store its configuration in eDirectory, which is in the AppConfig container, underneath the User App DirXML-Driver object. Inside the AppConfig are a LOT of objects and containers. Under RoleConfig, there is a Requests container object which is where RBPM writes out an object, when you assign a Role.

This is the sort of thing you would see in the User App log, when such a Role grant occurs:
2010-09-16 12:31:21,761 INFO  [com.novell.idm.nrf.service.RoleManagerService] (http- [Role_Request] Requested by cn=admin,ou=admins,o=acme,dc=com, Target DN: cn=securityadmin,ou=Security,ou=admins,o=acme,dc=com, Source DN:cn=secAdmin,cn=System,cn=Level20,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application,cn=IDM,ou=Drivers,o=acme,dc=com, Request DN:cn=20100916123121-e080d05cee9f4df3801bb878e315a402-0,cn=Requests,cn=RoleConfig,cn=AppConfig,cn=User Application,cn=IDM,ou=Drivers,o=acme,dc=com, Request Category: 10, Request Status: 0, Original Request Status: 0, Correlation ID: 5443c88adc2642a38417434a6c6a73d3

You can read more about some of this Roles granting and troubleshooting, specifically for the built in Roles that you set at first User App startup in this article:
User App Roles Failing to Apply for Administrators

The LDIF of such an object looks something like this:
dn: cn=20100916123121-e080d05cee9f4df3801bb878e315a402-0, cn=Requests, cn=Rol
eConfig, cn=AppConfig, cn=User Application, cn=IDM, ou=Drivers, o=acme, dc=c
nrfStartDate: 20100916163121Z
nrfCategory: 10
nrfRequester: cn=admin,ou=admins,o=acme,dc=com
nrfSourceDN: cn=secAdmin,cn=System,cn=Level20,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application,cn=IDM,ou=Drivers,o=acme,dc=com
nrfTargetDN: cn=securityadmin,ou=Security,ou=admins,o=acme,dc=com
nrfCorrelationId: 5443c88adc2642a38417434a6c6a73d3
objectClass: nrfRequest
objectClass: Top
nrfImmediate: TRUE
cn: 20100916123121-e080d05cee9f4df3801bb878e315a402-0
nrfDescription: RBPM Security administrator assignment request.
nrfDecisionDate: 20100916163121Z
nrfStatus: 50
nrfRequestDate: 20100916163121Z

There are a number of attributes and objects involved in this process, some I understand, some not so much, after all, this is well documented, right? (Actually, if someone can find any documentation about this aspect I would love to read it, please forward on any links you have).

You can see that the name is a CN with the date stamp, then a GUID which is probably a tracking number against the RBPM database but I am not sure. I would have thought that would be the nrfCorrelationId. I imagine then that the nrfCorrelationID is probably a value out of the User Application database that can be used to reference this event back to a request made in (or through) User Application. The 'through' User Application reference is to something like the Access Governance Suite, which can read out your various roles and entitlements (not necessarily the eDirectory/Identity Manager entitlements we have been discussing here) in a variety of systems and try to first calculate some likely suggested Roles. But over time to also validate that the Roles are enforced correctly, and report on them. Once you use the Access Governance Suite to generate some Roles, it can push it back into User Application, and this might affect a number of users, thus AGS is using User App at the way to get at the Roles and Resources definitions, but not directly through the User Application interface. (It is using SOAP or REST I imagine to do this work). Additionally, the Role Mapping Administrator works in a similar fashion to help manage Roles and Resources. We are starting to see a fair bit of tooling in Identity Manager use the User Application as the base for its approach. Reporting as an example uses the Roles model to authorize access to Reporting. Thus an eDirectory administrator means nothing to Reporting in terms of access. That user would need to be made a Reporting Admin or Manager to work in Reporting. I am torn on how I feel about the bifurcation of permissions.

The nrfStartDate, nrfRequestDate, nrfDecisionDate, and if there is an end date, the nrfEndDate, are all date stamps for when stuff happened. The Start and End date stamp for the Role. The Request Date, is when it was requested, and the Decision Date is when it was actually either approved or granted. Thus you could in principle see how long approvals for Role Requests are taking. Note that I show the representation of the object via an LDIF export, which reports time in LDAP's format. In reality these are Time syntax attributes in eDirectory and it is actually stored in CTIME, which is a count of seconds since the very beginning of 1970 (January 1st right at the turn of midnight). Alas, this is a signed 32 bit integer and runs out of

nrfCategory is 10, 20, or 30 I believe, based on the three levels of Roles that are supported in RBPM. There have been requests for more levels, and someone always has a model that uses more, but for sake of simplicity three levels seems to usually be enough.

nrfRequester, nrfTargetDN, nrfSourceDN are all DN (Distinguished Name) syntax attributes, that point at the various objects involved. The Requester is the one asking for the Role. The SourceDN is the Role itself that is being discussed. As you can see from its DN, it too exists in the AppConfig object, under the RoleConfig and then RoleDefs containers.

nrfImmediate is interesting, and I assume it tells the Roles and Services driver process on the event, instead of on some polling interval. There is a similar flag on a DirXML-WorkOrder object as used by the Work Order driver. There the DirXML-nwoSendToPublisher flag is used to trigger an event in the Work Order drivers filter, and if true, the event is processed. I imagine this attribute is being used the same way. This way the Roles and Services driver can poll on some reasonable interval (1, 5, or say 30 minutes) and then if an event is needed post haste, this flag is available to get it flowing as soon as it is requested.

nrfStatus is something I would like to see better defined. I have watched in trace on the Roles and Services driver and clearly there is a progression. I have seen 0, 20, 30, and 50 go by. I assume there may be additional states, but I have not had the time to dissect the log to figure it out. Again, if you happen to have figured it out already, or found a documentation source, please let me know! Clearly 0 looks like the beginning state, and 50 the completed state. But what do those intermediate values mean? And are there error states? Inquiring minds want to know! After writing this complaint, I searched and found it, certainly not in an obvious spot in the docs, but I will take what I can get. User Application API

Here are the values. Interesting to see the allowed states, it tells you a bit about the processing that the Roles and Services driver does in the background.
NEW_REQUEST			0	Set by the User Application on a newly created nrfRequest object.

SOD_APPROVAL_START_PENDING 2 The Role Service driver attempts to start the SoD workflow again. This is used for requests in the SOD_APPROVAL_START_SUSPENDED mode.

SOD_APPROVAL_START_SUSPENDED 3 Occurs when the Role Service driver is not able to start an SoD workflow. A driver task then resets these requests to SOD_WORKFLOW_START_PENDING to retry the starting of the workflow.

SOD_EXCEPTION_APPROVAL_PENDING 5 Set by the Role Service driver after successfully initiating an SoD exception workflow.

SOD_EXCEPTION_APPROVED 10 Set by the SoD exception workflow when the exception is approved.

APPROVAL_START_PENDING 12 The Role Service driver attempts to start the workflow. The request must be in APPROVAL_START_SUSPENDED mode.

APPROVAL_START_SUSPENDED 13 Occurs when the Role Service driver is not able to start the approval workflow. A driver task then resets these requests to APPROVAL_START_PENDING to try to start the workflow again.

APPROVAL_PENDING 15 Set by the Role Service driver after successful role assignment workflow.

APPROVED 20 Set by the role assignment workflow when the exception is approved.

ACTIVATION_TIME_PENDING 25 Set by the Role Service driver after obtaining all necessary approvals and the activation time has not yet been reached.

PROVISION 30 Set by the Role Service driver after all the necessary approvals have been approved and the role activation time has been reached.

PROVISIONED 50 Set by the Role Service driver after a role has been provisioned.

PROVISIONING_ERROR 80 Set by the Role Service driver when an error occurred during provisioning/deprovisioning

SOD_EXCEPTION_DENIED 90 Set by the SoD exception workflow when the exception is denied.

DENIED 95 Set by the role assignment workflow when the exception is approved.

CLEANUP 100 Set when nrfRequest workflow should be cleaned up (deleted). This is intended to be triggered by a batch process some configurable amount of time after the request has either been fulfilled or denied.

As I surmised there are a number of possible error states actually only two 3 and 80 it looks like. But because more than just simple approval is involved, we need more states. There is the entire SOD (Separation of Duties) flow that needs to be both accounted for and handled. Of course Denial is not just a river in Egypt (D-Nile, get it?) and needs to be handled as well.

So the values I have noticed were for simple approvals that succeeded. 0 for new, then 20 for Approved, then 30 for Provision, and 50 for Provisioned.

I think playing around with the Roles and Services driver to better understand what sort of things it does under the covers would be worthwhile, and I guess I should add it to my list of things I need to look at. The log is quite informative in terms of understanding what is going on inside the driver. Very little happens in policy, most of it is happening in the shim, and the good news is that it traces a fair bit of information from the shim in the process, which makes it possible to better understand.

The final agent for handling entitlements is the User Application Workflow, where you can assign a Role, in which case it is basically the same process as above, as that generates an nrfRequest object which is handled by the Roles and Services driver.

What I am unclear on, is if the Entitlement granting activity in a workflow directly grants the entitlement or uses the nrfRequest mechanism. That is something worth looking into further. This activity predates the notion of a Roles and Services (or even the Roles driver before Resources became available) so it probably grants it directly.

The payload of the Entitlement is interesting, and there is a DTD that defines its contents. The engine does require that the path.xml component have valid XML, or else it throws a nice error, which I had captured, but lost on a reboot.

The DTD is referenced here:
Novell Entitlement Document Type Definition (DTD)


How To-Best Practice
Comment List