An interesting quirk in the Entitlement Tokens

5 months ago

A colleague of mine pointed out something that I had never noticed before (Bad colleague!  Bad!) about how the Entitlement tokens handle DirXML-EntitlementRef attributes.

First off, DirXML-EntitlementRef is an interesting attribute. It is Path syntax so  has three components, volume, nameSpace, and path. But this uses path,xml instead of path, which requires valid XML and is treated like a nodeset not a string containing XML.


<nds dtdversion="4.0" ndsversion="8.x"> <source> <product version="">DirXML</product> <contact>NetIQ Corporation</contact> </source> <input> <modify class-name="User"> <modify-attr attr-name="DirXML-EntitlementRef"> <add-value> <value type="structured"> <component name="volume">ACME\DSet\MyDriver\MyEntitlement</component> <component name="nameSpace">1</component> <component name="path.xml"> <ref> <src>NRF</src> <id></id> <param><param>{"ID":"Test"}</param></param> </ref></component> </value> </add-value> </modify-attr> </modify> </input> </nds>


That is an example of granting an entitlement. It is an add-value for DirXML-EntitilementRef, with a nameSpace of 1 (granted vs 0=revoked)


Revoking one is usually, remove the value that has a nameSpace of 1 and add a value with a nameSpace of 0.


If you simply event on the attribute DirXML-EntitlementRef and not use any of the special entitlement tokens, this works fine and as expected.


However there are a number of built in tokens for Entitlement handling.  They do several clever things.

For example:

If you loop over the nouns Token Entitlement, or Removed Entitlement as a nodeset, the current-node variable is actually the contents of the path.xml's <param> node.  Which in modern IDM should contain JSON which you use an ECMA function to get the ID or ID2 out of.  (See the Lib AJC for the ECMA functions).  This abstracts a lot of work you would otherwise have to do to get the data which is good.

If you use any of the Entitlement Actions/Conditions/Nouns, you can simply select the name of the Entitlement and Designer looks them up and presents them just as simple object names.  This abstracts out the volume component and the driver DN at the beginning and so on. 

There are condition tokens like If Entitlement which can be changing, available, equals, etc.

There is only a Implement Entitlement action, and it is not really used any more.

 In the Argument Builder, there are several Nouns, like:

  • Added Entitlement (added in document)
  • Entitlement (like source attribute)
  • Removed Entitlement (removed in event document)

All of them provide the shortcuts mentioned, and are very handy for that reason.


But the twist my colleague mentioned is that the tokens react to adding a value with a nameSpace of 1 as an added entitlement. And the add of a value with a nameSpace of 0 as a revoke.

But like Booleans in eDirectory, they have an extra state. (Booleans in eDir are either true, false, or absent (which behaves like false).  That is, simply removing the value with a nameSpace of 1, does NOT count as a revoke.

I always thought it did, but had to prove myself wrong.

To do so, I made a simple policy inside an existing driver. (Because the DN of the entitlement is referenced, you have to change my example to match your drivers entitlements) with this simple rule:


<rule> <description>Test Entitlement Delete</description> <conditions> <and> <if-entitlement name="MyEntitlement" op="changing"/> </and> </conditions> <actions> <do-for-each> <arg-node-set> <token-removed-entitlement name="MyEntitlement"/> </arg-node-set> <arg-actions> <do-trace-message> <arg-string> <token-text xml:space="preserve">Kooey</token-text> </arg-string> </do-trace-message> </arg-actions> </do-for-each> </actions> </rule>



Which really is simple and looks like this in Designer.



Then I hit Simulate (A chevron with a play button, upper right in Designer when in Policy Builder and next to the Live-Compare button) and fed in a document example like I  started with of each case. 

When it was an add value with a nameSpace of 1, it counted as a changing entitlement (for my condition block) and was an added entitlement.

When it was an add value with a nameSpace of 0, it counted as a changing entitlement, and was a removed entitlement.

When I simply removed the value with a nameSpace of 1, it was a changing entitlement but was not a removed entitlement.

Who knew?  Interesting.  Learn something new every day.




Support Tip
Comment List
  • Thats because namespace is used as a bitmask in DirXML-EntitlementRef.

    The "namespace" (or integer) portion of the DirXML-EntitlementRef attribute is used as a bitmask to hold a set of flags. Bit 0 of the 32-bit integer is used for this flag value and is known as the state bit. 0 means revoked, 1 means granted. Bit 1 is used to flag a granted entitlement that is the result of the upgrade process and is known as the upgrade bit. 1 means that the entitlement was previously granted in the legacy format and is therefore not a change in the entitlement state. Bits 2-31 are reserved for future use.


Related Discussions