Walking through the Office 365 IDM driver - Part 1


There are many drivers available out of the box from NetIQ and even more available from various partners. You can get a feel for the scope in the article below, where I have listed the DirXML-Associations values for the various drivers that are known:
Open Call – IDM Association Values for eDirectory Objects

One of the issues with supporting an out of the box driver is that when something does not go quite right, often you assume, well it must work that way for a reason. But there is no really good way of knowing what that reason is, or whether it is really a bug.

I have been trying to work on that issue by walking through a variety of drivers, policy by policy, item by item, explaining as best I can what is going on. This way you get an idea for what should be happening and why. My hope is that this has been a useful tool for troubleshooting issues for folk out there. Please let me know if one of my walk throughs has helped you out, I am curious to know.

On a recent Designer restart I saw that the Office 365 driver packages were released in the Novell update channel and since this is a new driver, I would love to start working through it, and get some content out there for it beyond just the documentation.

First off in the documentation I noticed that it supports the following Microsoft services.

  • Microsoft Exchange Online

  • Microsoft SharePoint Online

  • Microsoft Lync Online

  • Office Professional Plus

  • Office WebApps

What I note is missing is the old BPOS and Live@Edu. But that is a nice list of supported services from one driver. This also is seen a little deeper in, that Licenses can be granted as entitlements to control access to the different services.

Also of interest this is the second driver that uses the .NET Remote Loader. (The first was the Sharepoint driver). This does mean that you have to run the .NET Remote Loader on a Windows machine. It appears that you must use a Remote Loader, and not run it local, even if your engine server is running on Windows.

With the release of packages, I can now actually offer a real versioning of what this document is based upon. In the past I had to describe which version of Designer or iManager I got it from. Packages are a great step forward! I used the following packages to build a driver to review:

  • NOVLOFFIBASE Base package

  • NOVLOFFIDCFG Default configuration

  • NOVOFFAUDENT Audit Entitlements

  • NOVLOFFIATRK Account tracking for Identity Audit

  • NOVLOFFIPSWD Password Synchronization

  • NOVLOFMSINFO Managed System Info

  • NOVLOFFENT Entitlement support

  • NOVLOFFIOPTL Optional Packages

I also picked up some package dependencies and got:

  • Account Tracking Common

  • Audit Entitlements Common 1.0.0

  • Data Collection Common 1.0.0

  • Password Synchronization Common

There were a couple of driver set packages that came in via dependencies as well:

  • Advanced Java Class 1.0.1

  • Common Settings 1.0.01

Like most drivers these days, the MSI, Audit, Entitlement, Password Sync, and Account Tracking packages are probably pretty much the same. The MSI for example usually differs between drivers by a single static value set in the NOVLOFMSINFO-itp-InitManagedSystemInfo policy. This needs to differ for every driver, and for some reason it is hard coded in this policy. An amusing side note is that the most common thing to be missed on a new driver release seems to be this one value, however this time they remembered to change it in advance. The value is Office365 in case anyone was interested. The Active Directory driver is AD, and so on. It used to look like it needed to be 2 or 3 characters, but that seems to have drifted as one of the SAP driver had a four character value, and now this has a 9 character value.

When you look at this driver in Designer, you will see quite a number of prompts objects. Prompts are used to manage settings and GCV values during install and upgrades. That is, if you have a GCV object in your package and wish to change it during the upgrade process, you can either overwrite all the values currently on the driver (No prompts object) or else define a prompts object that copies the existing values into the display, lets the administrator installing the new driver specify a new or modified value, and then copy the final results into the GCV object when complete. I count 13, which might be a record. Some of this comes from the use of standard packages, modified, like Account Tracking Common, and then the package to customize it for this driver. So it seems like a lot but in reality it is probably the new normal.

Starting at the driver level, there are five GCV objects included in this driver. Most of these, Password Sync, Account Tracking, and Managed System Info come from standard packages and are about what you see on every driver. The Entitlements GCV is pretty common in terms of being present, but it's contents of course differ from driver to driver.

The Password Sync policies are an interesting case. What happens is, you include the common Password Synchronization Common package, which adds the policies needed to the driver, in the Command Transforms of both channels, but does not link them in. That is, it creates the policies, but leaves them unlinked.

Then there is a driver specific policy, which in this case is the NOVLOFFIPSWD package that links to the external policies and then includes a few customizations of its own. It also includes the GCV object with any custom bits. This way a fix by NetIQ of a Password Sync common policy can be used in many drivers. Yet the different drivers can still customize password synchronization processes as needed. You can see examples of this in the Notes/Domino driver where the old password is needed to change a password, so there is a minor tweak to one of the policies. This comes in the Notes specific password sync policy and leaves the common password sync policy that it replaces unlinked. The BiDirectional eDirectory driver which needs to handle RSA passwords as well (What it calls Password Sync 1.0) has a special policy for that added in via the driver specific vs the common password policies.

Here too we see a minor tweak. At first, in the GCVs for Password Synchronization that are very common. In this driver they did something I have never seen before. The Connected System or Driver Name GCV, is used by the email templates in the Input Transform (ITP) and Output Transform (OTP) to send email messages on failed password events. This GCV is in fact set to another GCV, ~drv.name~ using the tilde notation. This is a fun trick as it works in surprising places, due to how it is implemented. When a driver starts up, it does a global search and replace on all policies and things for any ~GCVName~ style entries, and expands them. This is a tiny bit faster than the $GCVName$ notation that is used in other places. The dollar sign notation is evaluated at run time, instead of just once at driver startup. The problem is, I cannot find where this GCV is set.

Next up is a GCV, Set Password Never Expires and Disable Force Chaneg Password at First Login, which are Office 365 specific settings that I assume (will find out as we progress through this series) are options on user create.

Then we have the normal set of Password Management GCVs to control direction of password flow, usage of Distribution Password, and so on. For a fun twist on those settings, take a look at this article about Password tunnelling mode. I never knew it existed until we had a clever use for it at a client:

For more information on how Password Synchronization works at a policy by policy level, as well as how the GCVs control it, consider reading these two articles:

Account Tracking and Managed System Info I will not discuss again. Managed System Info is discussed in great detail in my series on the Managed System Gateway and Data Collection Service drivers, including the use of this GCV:

I intend to write up a standalone series on the Account Tracking policies and GCVs so I will skip those for now as well.

Entitlements is the next GCV set of interest. Some of these are familiar from other drivers. For example, settings to control each entitlement's usage. That is, for User Account, Group, License, and Roles they can be enabled or disabled by GCV. The User Account has one extra twist as is common, to define what to do when it is revoked. A group or role entitlement when revoked means remove the user from the group or role. But what does a revoke of User Account mean? Delete the user? Disable the user? Well those are your choices, so choose wisely.

Each Entitlement lets you specify the format for the entitlement parameter. This is important as there are now three entitlement formats supported as of IDM 4.01. Initially the <param> node in path.xml component of the entitlement grant (The DirXML-EntitlementRef attribute on the object getting granted the entitlement) contained a single value. The parameter, literally just the one. But with support for the SAP UM fanout mode, where one entitlement implied access to many systems, a new notation was added, where multiple values were pipe (|) separated. However it turned out that was not so scalable, so in IDM 4.01 a new format, now called IDM 4 vs Legacy, which uses JSON format inside the <param> node. JSON is a key=value style notation, with some specific separators like {"key":"value"}. Amusingly, the description text in this build says JASON not JSON. Someone heard the word, but had never seen it written down before or did not know what it stood for. Really just a funny typo.

There are four entitlements in this driver. UserAccount, Group, License, and Role. The first two are obvious. License is an interesting one, it is used to grant permissions to services within the Office 365 world. I am trying to track down specific values that are allowed. The final one, Role, is mapped to an object in Office 365 called MSolRole and I imagine is some kind of permission role in the remote system. I am trying to track down what the appropriate values to insert here are but have not yet succeeded. From the policies it is clear that the key named ID's value will be used to send to fill in the attribute Role and LicenseAssignment. When I find out more info I will update with it.

One way to possibly figure out the license entitlement values would be to look at some objects in the O365 system. To support entitlements there is a query defined in a GCV that defines how to get the needed information. That looks like this:

<query class-name="MSolLicense" scope="subtree">
<search-class class-name="MSolLicense"/>
<read-attr attr-name="AccountSkuId"/>
<read-attr attr-name="AccountName"/>

Looks like there is an MSolLicense object, which has a couple of attributes of interest AccountSkuId and AccountName. I suspect we want the AccountSkuId values. If you have access to an O365 system and could query it for such an object I would love to see what the output looks like.

The UserAccount entitlement can only be added once, but the Group, Role, and License entitlements can be added to a user multiple times to allow for multiple group, role, and license assignments. I hope there is a set of composite license values, so rather than having to grant multiple license values on each user, one can suffice. Or perhaps some form of negation so as to allow all but this type. Otherwise you will end up with users with lots and lots of entitlements to support this service.

That is about it for this article, stay tuned for more, lots more interesting stuff to work through next!


How To-Best Practice
Comment List