Introducing the Start Workflow Token - Part 1

0 Likes
over 11 years ago

Novell Identity Manager has been slowly accreting new tokens with each new release. I have discussed some of them in the past:

One I have used before, but not really written about is Start Workflow. This is an interesting token, as it appears to be a wrapper around a SOAP call, that specifically calls a single SOAP function exposed by the User Application. The token allows you to start a workflow, passing in all the data needed on the Request form, without human intervention. This is nice because you can develop a single workflow that the system automatically runs under the correct circumstances or works for a person (or cat!) to request some kind of entitlement.

I do however start to wonder about the start workflow token being a wrapper around a SOAP call, as I was watching the server.log as I used the iManager plugin to manage Workflows, and that very clearly makes SOAP calls that you can see in the trace, if you have the right logging level enabled. The Start Workflow token looks very different, so I do wonder. If anyone has any insights on this, I would appreciate the feedback. It is pretty meaningless, but it makes me curious.

To save the suspense, here is what a Start workflow looks like in the Identity Manager DSTrace view.

This start workflow:

[06/08/10 15:45:42.563]:spml PT:      Action: do-start-workflow(id="cn=arewethereyet@td.com",url="http://10.1.1.2:8080/IDMProv",workflow-id="CN=Client Contact,CN=RequestDefs,CN=AppConfig,CN=User Application,CN=IDM,OU=Drivers,O=ACME,dc=com",arg-password("password"),arg-dn("cn=" token-dest-name() "," token-global-variable("d")),token-operation(),"cn=" token-dest-name() "," token-global-variable("d"),token-op-attr("Internet EMail Address"),token-time(format="!CTIME",tz="UTC"),token-op-attr("Telephone Number"),token-op-attr("Given Name"),token-op-attr("Surname"),"Dunno",token-local-variable("ACCOUNT"),token-local-variable("LEASEDLINE"),"x",token-op-attr("acmeGARegion"),token-op-attr("acmeGASite"),token-op-attr("acmeGAUserSignature")).

Here is a screen shot of what the Start Workflow token looks like in Designer.

I circled a couple of things of interest. First off I like to use a GCV (Global Configuration Value) for the address of the User Application server for a couple of reasons. Primarily because the development and production User Apps are almost never at the same address. Additionally, we rarely enable SSL in development, and later change to an SSL'ized URL for production, so even if you played some DNS games to keep the URL's IP Name the same, you would likely have to change the text of the URL anyway.

Next up, I noted that I used a GCV for the password. In this case, I would use a GCV of type password-ref. This is a cool GCV type that allows you make a GCV, that points at a Named Password, and when you reference the GCV, you get the value of the named password. Named passwords are a mechanism to store passwords encrypted in the driver in a way that the engine can retrieve. This way you do not have to hard code passwords in the clear in the driver configuration. You can read more about the various types of GCVs in these articles I wrote:

Now as it turns out, since there is a String Builder button on the password line, you get the chance to actually use a Named Password directly as well. But the GCV works just as well. I like using the GCV, since there are a number of instances where you do not get a String Builder interface to select a Named Password, but the $GCV-Name$ or ~GCV-Name~ notation will work. The flexibility is quite nice, and powerful.

The third item I circled was the was Specify Strings line.

This is probably the most critical part of the start workflow token. Depending on how you are doing your development, then this is the major integration point between the Identity Manager engine and the Provisioning side of the house.

You can imagine how this token works, by imagining that the token programmatically fills in the Request form in the PRD, and then clicks Submit. If there are any errors then the workflow does not start, much like you would get an error back in the form. Thus he workflow engine when it receives this sort of a token is basically filling in the fields, and returning the error in the server.log of the JBoss (or whatever Java Application server you are using, which could be IBM's WebSphere, or WebLogic) server. You get a truncated version back in DStrace on the engine side.

So where do you get the list of strings you need to send in the token? Well you look at the Workflow tab of the Provisioning Request Definition (PRD), at the Start Activity, and then enable the Data Items mapping view (Right click on the Start Activity and it is an option). Then click on the Post-Activity Mapping. Any field listed there, needs to be sent in the Start Workflow token.

The good news is that when you open a Start Workflow token in Designer, and then pick a PRD object (note that PRD's are stored under the AppConfig container in the User Application driver, so you can find it when browsing the eDirectory tree) Designer is actually smart enough to read out all the needed fields and pre-populate the drop down box in the Specify Strings sub window. Just make sure you will in all of them, and send the data in the proper format. It is a little awkward, as you have to add a string to the editor one at a time, and be sure to select all the strings. If you have a fair number of strings (Say 10 or more) it can be a little hard to be sure you got them all. I do think perhaps an add all style button would be very helpful in this part of the user interface.

Now the particular example in trace that I showed before was taken from a more complex rule that had lots of strings provided, which are a little hard to see in the trace, as you do not get an complete summary of string values that get sent, rather you have to read through as the engine builds each string, based on how you defined it.

The submission of the token generates this error:

DirXML Log Event -------------------
Driver: \IDVAULT-LAB\com\ACME\Drivers\IDM\SOAP-SPML
Channel: Publisher
Object: 003T000000OL9KGIA1 (com\ACME\Contacts\arewethereyet@td.com)
Status: Error
Message: Code(-9194) Error in vnd.nds.stream://IDVAULT-LAB/com/ACME/Drivers/IDM/SOAP-SPML/Publisher/[acme] pub-ctp-Fork off events for Workflow approval#XmlData:222 : Couldn't start workflow 'CN=Client Contact,CN=RequestDefs,CN=AppConfig,CN=User Application,CN=IDM,OU=Drivers,O=ACME,dc=com' for recipient 'cn=arewethereyet@td.com,': com.novell.soa.af.impl.soap.AdminException={_Reason=Logged in user is not a Provisioning Administrator.}

Well that was ok. We needed to add the ability for users to start provisioning workflows. Tried it again, and we get a 403 error this time.

HTTP 403 is usually a web server side error about lack of permissions to see a web page. But why would the User Application be returning that? Seems a bit odd.

DirXML Log Event -------------------
Driver: \IDVAULT-LAB\com\ACME\Drivers\IDM\SOAP-SPML
Channel: Publisher
Object: 003T000000OL9KGIA1 (com\ACME\Contacts\arewethereyet@td.com)
Status: Error
Message: Code(-9194) Error in vnd.nds.stream://IDVAULT-LAB/com/ACME/Drivers/IDM/SOAP-SPML/Publisher/[acme] pub-ctp-Fork off events for Workflow approval#XmlData:300 : Couldn't start workflow 'CN=Client Contact,CN=RequestDefs,CN=AppConfig,CN=User Application,CN=IDM,OU=Drivers,O=ACME,dc=com' for recipient 'cn=arewethereyet@td.com,ou=Contacts,o=acme,dc=com': java.rmi.RemoteException: HTTP 403 Forbidden

Well as usual, Google is your friend. John Dasilva answered this in the Novell Support Forums:
http://forums.novell.com/novell-product-support-forums/identity-manager/im-userapp-workflow/401590-http-403-forbidden.html

John notes that:

You need to be a provisioning administrator to start the workflow. The Authorized User DN ID and password that you provided in the Start Workflow Action must be a valid Provisioning Admin.

Well I thought I had done that. But after further investigation we realized a major issue! Rights within the User Application are in an interesting mix of eDirectory trustee rights, and internal ACL's in the User Application work space. What manages the second half of those ACL's? Well it turns out that the Roles and Resources driver does.

For some reason we had installed our Identity Manager engine, without the Roles and Resource driver. Thus although we had gone into the User Application and granted the roles to allow various actions for different users, turns out they were never 'enforced' or 'enabled' by the Roles and Services driver.

Once we installed a Roles and Services driver, looked through the dstrace logs from that driver to see what it does, and here is what happened when we added a User to the provAdmin group:

<nds dtdversion="3.5" ndsversion="8.x">
<source>
<product version="3.6.11.4904">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<nrf:identity dn="dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com" event-id="0" xmlns:nrf="urn:dirxml:nrf"/>
</input>
</nds>
[06/09/10 14:09:27.005]:Roles ST:: Recalculating roles for identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com
[06/09/10 14:09:27.006]:Roles ST:: Role sync operation ignored because container is out of scope
Container DN: dc=com
User-Group root DN: com\ACME
[06/09/10 14:09:27.013]:Roles ST:: Process Equivalent To Me
Role: Process Equivalent To Me
Role: dc=com\O=ACME\OU=Drivers\CN=IDM\CN=User Application\CN=AppConfig\CN=RoleConfig\CN=RoleDefs\CN=Level20\CN=System\CN=provAdmin
Operation: 5
Identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com
Operation: {1}
Identity: {2}
[06/09/10 14:09:27.014]:Roles ST:: Retrieving resource association objects based on a role or resource DN. DN: dc=com\O=ACME\OU=Drivers\CN=IDM\CN=User Application\CN=AppConfig\CN=RoleConfig\CN=RoleDefs\CN=Level20\CN=System\CN=provAdmin
[06/09/10 14:09:27.014]:Roles ST:SubscriptionShim.execute() returned:
[06/09/10 14:09:27.015]:Roles ST:
<nds dtdversion="3.6.1">
<source>
<product instance="Role and Resource Service" version="3.7.0.4862">Novell Role Service Driver</product>
<contact>Novell, Inc.</contact>
</source>
<output>
<status event-id="0" level="success">nrf:identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com</status>
</output>
</nds>
[06/09/10 14:09:27.015]:Roles ST:No input transformation policies.
[06/09/10 14:09:27.015]:Roles ST:No schema mapping policies.
[06/09/10 14:09:27.015]:Roles ST:Resolving association references.
[06/09/10 14:09:27.016]:Roles ST:Processing returned document.
[06/09/10 14:09:27.016]:Roles ST:Processing operation <status> for .
[06/09/10 14:09:27.016]:Roles ST:
DirXML Log Event -------------------
Driver: \IDVAULT-LAB\com\ACME\Drivers\IDM\Role and Resource Service
Channel: Subscriber
Status: Success
Message: nrf:identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com

That is interesting trace to look through as you can see what it is trying to do, to add the Role entitlement to a user.

Now the part that sticks out to me is:

[06/09/10 14:09:27.013]:Roles ST:: Process Equivalent To Me
Role: Process Equivalent To Me
Role: dc=com\O=ACME\OU=Drivers\CN=IDM\CN=User Application\CN=AppConfig\CN=RoleConfig\CN=RoleDefs\CN=Level20\CN=System\CN=provAdmin
Operation: 5
Identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com
Operation: {1}
Identity: {2}

In that, I see that in fact the driver is processing the Equivalent To Me attribute, not the Group Membership attribute. Groups in eDirectory are different than in most other systems. In Active Directory for example, a Group has a list of its Members, in the Member (which is actually all lower case as "member") attribute, but there is no actual attribute on the object that stores the groups the user is a member of. Even though the Active Directory Users and Computers will show you the list, in the back end, the snapin actually queries for any group whose Member attribute has the current users DN in it. Now at least Active Directory has a minimum of referential integrity and when you delete the User object, the membership in the groups gets cleaned up. Contrast that with Lotus Domino (the server behind the Lotus Notes email and database system) which stores the membership on the Group objects as just a string, and if you delete the user, they remain in the groups member list. This is quiet an annoying way to run a railroad, and in fact most Domino implementations run a job on some schedule (nightly, weekly, or monthly) that looks at each group, tries to find every listed member, and clean up any that have since been deleted. As you can imagine that is a bit of a less than optimal solution.

eDirectory on the other hand does not have any of these issues. A User added to a Group generates 4 attribute changes. There is a reciprocal link between Group Membership (on the User) and Member (on the Group). There is a similar reciprocal linkage between the attributes Security Equals (on the User) and Equivalent To Me (on the Group). It turns out that trustees in eDirectory and effective rights, flow because of the Security Equals / Equivalent To Me attributes, and not the because of the Group Membership / Member attributes. Tools, like Console one, iManager, and even NWAdmin (There is a blast from the past eh?!) know about this and when you click to add a user to a group, manage all four attributes. If you are writing code to do this in your application (say via LDAP, or even in Identity Manager policy) you are responsible for handling all four attributes. On top of this eDirectory has referential integrity and if you rename an object that is referenced by one of these four attributes, no problem. The system manages it in the background for you. Actually there is no management to do, since the DN reference attribute syntax type just stores a reference in the database that has nothing to do with the name (which changes in a rename) or location in the tree (which changes in a move event).

This also has an interesting feature of decoupling the trustee management from the group membership, and allows other uses of the trustee management. Thus when you are added into a Role, you could imagine it being a group if groups were all you could do (Can you spell Active Directory?) but since this is eDirectory, it is not a Group, it is more (or less, as the case dictates) an object that confers trustees. Thus Equivalent To Me and Security Equals get set to link the User (or Group even!) to the Role.

Now we see the driver process this, and that has some interesting bits in it. I wonder what the references to Operation, and Identity mean, specifically:

                Operation: 5
Identity: dc=com\O=ACME\OU=Contacts\CN=arewethereyet@td.com
Operation: {1}
Identity: {2}

Now I need to figure out what the 5, {1}, {2} refer too. If you happen to know, please pass the info on, so I can make sure someone else can find it.

Well thats it for now on the Start workflow token. I have more thoughts to share, and a nice trouble shooting example to work through, in terms of tracking down the root cause of a Start workflow failing to start.

Labels:

How To-Best Practice
Comment List
Anonymous
Related Discussions
Recommended