Another documentation gap: nrfCorrelationId

I've tried to avoid anything UserApp-ish in the last decade or so, for a reason. Unfortunately I finally had to stop looking away and start working with it, and the deeper I look under the hood of the NRF role model the more I dislike it. The fact that many details seem completely undocumented does not make it fun to work with, either. HWMNBN's legacy, I guess...

So another riddle to solve: how exactly is nrfCorrelationId used by UA and RRSD? Where does it's value come from? Just another GUID-style random value or a reference to anything meaningful?

Any insights or pointers very welcome...

 

  • You my friend, will just end up being even more frustrated.

    I found this "nrfCorrelationId: UserApp#RoleRequest#2911ddf2-8404-4936-a2a0-8e3933a5a43b":

    <perpertrator>#<what>#GUID

    Where the GUID comes from I do not know, but I would suspect that it could have something to do with an object, or something crazy else.

    From the Documentation (https://www.netiq.com/documentation/identity-manager-47/policy_designer/data/dostartworkflow.html)


    CorrelationID: An identifier used to correlate related workflows. By default, Operation event correlation is used. If no value is specified for the identifier, default value is used.

    NOTE: CorrelationID is not available in the Policy Builder user interface of this version.

     

    As the CorrelationId isn't required on the SOAP/REST calls, maybe you can find the code which generates it (if interested).

    And yes, the Role model does tend to generate some gray hair.

    Casper

  • I've found it helpful to get a copy of SoapUI and start poking at the various API calls. It makes more sense when you can see what it's doing.

    CorrelationID - I assume you're looking at RolesAssignmentRequest. It's anything you want it to be. UserApp seems to stick some kind of GUID thing there. You can use anything you want.

     


  •  wrote:

    CorrelationID - I assume you're looking at RolesAssignmentRequest. It's anything you want it to be. UserApp seems to stick some kind of GUID thing there. You can use anything you want.


    Yes, I'm looking at nrfRequest objects, where the nrfCorrelationID attributes shows up and has some GUID value in many cases - but I've seen date strings as well or other "meaningful" stuff, e.g. strings that look like path-syntax attributes via LDAP ("some\dn\like\string#something#something else").

    If can be random, what are it's requirements and limitations, e.g. does it have to be globally unique or must two request use the same correlation ID under specific circumstances? When is it used and by whom e.g. does RRSD send that value to UA in some SOAP call when processing role requests?

    https://www.netiq.com/documentation/identity-manager-47/policy_designer/data/doaddrole.html says: "An identifier to correlate the role assignment process. "

    So how is the role assignment process correlated then, and what role plays this ID in the process?

  • You need to delve in with SoapUI. It'll make more sense what you see in the objects when you see the requests made at the API level.

    As far as I can tell, correlationID is any string you want to put in the role assignment request. It's for your use, and you can use it later to find the request if you want to see what happened to it.

    The role grant request looks like:

    <ser:requestRolesAssignmentRequest> <!--Optional:--> <ser:assignRequest> <!--type: RoleAssignmentActionType - enumeration: [grant,revoke,extend]--> <ser:actionType>grant</ser:actionType> <!--type: RoleAssignmentType - enumeration: [USER_TO_ROLE,GROUP_TO_ROLE,ROLE_TO_ROLE,CONTAINER_TO_ROLE,CONTAINER_WITH_SUBTREE_TO_ROLE]--> <ser:assignmentType>CONTAINER_TO_ROLE</ser:assignmentType> <!--type: string--> <ser:correlationID>sonoras imperio</ser:correlationID> <!--type: dateTime--> <ser:effectiveDate>2004-02-14T12:44:14</ser:effectiveDate> <!--type: dateTime--> <ser:expirationDate>2018-11-01T00:36:46-05:00</ser:expirationDate> <!--type: string--> <ser:identity>circum claustra</ser:identity> <!--type: string--> <ser:originator>nimborum in</ser:originator> <!--type: string--> <ser:reason>foedere certo</ser:reason> <ser:roles> <!--Zero or more repetitions:--> <ser:dnstring> <!--type: string--> <ser:dn>profundum quippe ferant</ser:dn> </ser:dnstring> </ser:roles> <ser:sodOveridesRequested> <!--Zero or more repetitions:--> <ser:sodjustification> <!--type: string--> <ser:justification>et carcere</ser:justification> <!--type: string--> <ser:sodDN>iovis rapidum iaculata</ser:sodDN> </ser:sodjustification> </ser:sodOveridesRequested> </ser:assignRequest> </ser:requestRolesAssignmentRequest>

    whatever you put in for the correlationID, shows up in the request object.

    The only place I can see that this is useful is in the search for role requests:

    <ser:getRoleAssignmentRequestStatusRequest> <!--Optional:--> <!--type: string--> <ser:correlationId>gero et</ser:correlationId> </ser:getRoleAssignmentRequestStatusRequest>

    So, if you made a role request using correlationID "foo", you can search for role request status using correlationID "foo".

    There is a comment in the docs that correlationID is used "for auditing".

    https://www.netiq.com/documentation/identity-manager-47/identity_apps_admin/data/role-web-service-role-api.html 

    so, maybe that's a thing too.

    UserApp makes its own correlationID values. They look like GUID things. Probably they get stored in the database or somewhere like that.

    The DN looking ones you've spotted, I think, come from the do-add-role token.

  • As far as I remember it is shown together with the request status (as far as I remember) - which means that it will be to be found somewhere in the database, and without being too sure (haven't looked at it for a while) it is also being used with auditing/logging.

    If you look at the REST API doc. you'll see that it's as informative (not) as the SOAP documentation, it just mentions it.

    It would be nice if the documentation would put a max length on it (could probably get it from the database schema), as the SOAP end-point will probably just throw an useless error if one uses something which is too long.

     

  • I have actually used it to correlate specific items together.  Within Roles and Resources driver, all child nrfRequest and nrfResourceRequest objects will share the correlationId value.  That value will also be passed into the approval workflow if I recall.  This way, if you have a single request for 3 roles and each of those roles contain 2 child roles, which each contain 3 resources, all of those individual request items when they become exploded to be granted on the roles and resources driver will be correlated (as the name implies) together.  This can help you understand that they are all related to one another.

    Also, when we are doing PRDs in userapp, sometimes we have a PRD call one or more other PRDs.  Similarly, we pass the correlationID value forward into the next workflow so that we know all of those are essentially one big macro process through the system.

    Those correlationID values show up in the logs that are pushed to Sentinel for IGA.  They can then be stitched back together for audit purposes.  Otherwise, you'll see role requests go through without approvals in those audit logs and the only thing to tie them back to their approvals is that correlationID.

    As to how we figured this out, that is a completely different animal.  We were actually writing some logic that runs in parallel to the roles and resources driver to provide some additional logic.  Without getting into details, we had no way of correlating the individual requests together without that correlationId value.  Without it, we would have had no way of knowing whether or not separate requests were at all related.

     

    Hope this helps.