Walking through the Office 365 IDM driver – Part 3


In part one of this series I walked through some of the configuration, Packages, and GCVs used in the Office 365 IDM driver.

In part two of this series I walked through more of the GCVs and looked at some possible values for the License entitlements.

In this article I would like to look at the Filter and Schema Map. But first, one last point on the entitlements and GCVs. The other entitlement I was not certain of possible values was the Role entitlement. (User and Group were pretty standard. License is a bit confusing but hopefully the previous article at least gets an idea of what it should be)

I think I found a good explanation of the possible Roles in Office 365. It turns out in BPOS the Exchange 2007 based previous version (Office 365 is based on Exchange 2010 services) that there was no real delegation of administrative roles allowed. However now there are, and they are called Roles. The current roles supported are:

  • Global Administrator

  • Billing Administrator

  • Password Administrator

  • User Management Administrator

  • Service Support Administrator

I found a good definition of the roles at this site: http://mycentraladmin.wordpress.com/2012/04/17/account-roles-in-office-365/

  • Global Administrator: this is also known as the “Company Administrator” role, and maps to the old Administrator role available in BPOS. Accounts with this role have full control of your organization’s Office 365 subscription. These are the keys to the kingdom, so make sure to hand them out carefully. Now that there are other role types available, you shouldn't have to give these rights to everyone, so try not to.

  • Billing Administrator: users with this role can manage anything within your Office 365 subscription that’s going to involve a financial transaction. They can purchase additional licenses, change how payments are made for the Office 365 subscriptions, or purchase additional resources such as SharePoint storage or Exchange Archival services.

  • Password Administrator: Password Admins have the ability to reset user passwords, manage service requests that have been submitted to Microsoft for assistance (available with Enterprise or “E” SKUs only since Professional or “P” SKU subscriptions cannot submit service requests), and view the Office 365 Service Health information available within the Admin Portal. This is a handy admin role to have, because you can provide Tier 1 support staff with the ability to handle one of the most common support tasks you’ll face with Office 365, password resets, without the risk of giving them access to more complex aspects of the service that they could harm without the proper training or knowledge. It is important to note that these admins can only reset the passwords of normal users and other password admins; they cannot reset the passwords of admins in the other types of roles.

  • User Management Administrator: In addition to the rights of Password Admins, User Management Admins also have the ability to create user accounts and provision them with Office 365 User Subscription Licenses (USLs) and to create user groups within Office 365. While they can manage normal user accounts and accounts with the Password Admin role, they cannot make changes to accounts with other admin roles (Global or Billing) nor can they reset passwords for those accounts either.

  • Service Support Administrator: I think the Service Admin role is interesting, but can also be a little confusing. On one hand, this is an actual role that can be assigned to a user account, but all a user can do within the Office 365 Admin Portal is view user information and manage support tickets (E SKUs only). But on the other , it is necessary to assign this role to a user if you want them to have the ability to manage one or more of the services within Office 365 (Exchange Online, SharePoint Online, and Lync Online), in addition to granting them admin rights within the service itself. It’s important to remember that these services are very directly descended from their equivalent full server platform versions and retain a lot of the security functionality present within those parent platforms. Exchange Online provides much of the same Role Based Account Control (RBAC) settings as Exchange Server 2010 (defined by Exchange Role Groups such as Organization Management, Recipient Management, Help Desk, etc) and SharePoint Online (including SharePoint privilege levels such as Owner, Contributor, and Reader, roles such as Site Collection Administrator, and the use of SharePoint security groups to manage access control lists). So if you want to grant a user some of those granular admin rights within a specific service, you first need to assign them this role in Office 365.

The question becomes what specific value are expected in the parameter of an Entitlement grant to assign such a Role. We can look back at the entitlementsConfiguration object from the previous article for hints. In the <parameter> node for the Role entitlement we see:

  <parameter mandatory="true" name="ID" source="read-attr" source-name="Name"/>

That suggests that the Name is sufficient, which leads me to think that the names listed above are literal values that should work.

With that we can move on to the filter and schema map policy. The filter allows User and Groups with common attributes that make a lot of sense. In this case, one interesting twist is that DirXML-Associations is set to Subscriber notify which is different than most drivers. This is to allow using the association to a listed Active Directory driver elsewhere to be a gatekeeper for this driver. Passwords, using the Universal Password (and thus the nspmDistributionPassword) is set to Subscriber notify as expected. Otherwise this is pretty much the usual suspects, naming info, demographic stuff (Telephone, mobile, Postal address and code).

Groups get Member, CN, Description, and Owner synced which all make sense.

The schema map tells us that the two classes mapped to users and groups are MSolUser and MSolGroup. What is a little odd is that on the Group object, the Owner attribute is mapped to ManagedBy, but there is a policy in the Output transform that strips ManagedBy. Seems like it would be more appropriate to just remove Owner from the filter.

On the user, a very interesting mapping is that of CN to UserPrincipalName. There are policies to append the @domain.com (from the GCV drv.domain.name). Possibly uniqueID would be a better choice as CN can be multivalued (so can uniqueID but CN is often multivalued, whereas uniqueID is often not). I found it interesting that DirXML-ADAliasName was not used, since that is what the AD drivers use to store the User Principal Name values.

I see a couple of things you will probably want to add some policy to handle, like the mapping of Facsimile Telephone Number to Fax, and Postal Address to Street Address since they use structured syntaxes to hold their data and I do not see any transforms in the policy to 'flatten' them out. For the Fax number, this amounts to always having an extra 0 on the end of the number sent over. This is because the Fax syntax has three components, which I always forget the details, but basically one holds the number, one is always blank, and one defaults to 0, and is the final component. So when you cast this structured attribute to a string the three values (null, fax number, 0) get concatenated together, no spaces, so your fax number gets one digit longer and is always a 0, which is really hard to notice in testing, but breaks the usefulness of the value. Postal Address syntax has six components, all named 'string' (which is really annoying as in XPATH you have to address them using position() shorthand) and they too do not have a processing rule, so they will get all six lines of data concatenated together with no spaces, which is highly unlikely to be what you want. The policies to handle these are pretty trivial, but currently missing. Lets see how hard an example would be to construct.

As I think about it, it becomes clear that Reformat Operation Attribute is the perfect tool for this issue. A simple approach, for use in the Output Transform policy might be this:

For Facsimile Telephone Number: (Note this is after the Schema Map, so using Fax which is the application name)

<do-reformat-op-attr name="Fax"> <arg-value type="string"> <token-xpath expression="$current-value/component[@name='faxNumber']"/> </arg-value> </do-reformat-op-attr>

For Postal Address, you could try something like this. Again, using the application name space, so StreetAddress.

<do-reformat-op-attr name="StreetAddress">  <arg-value type="string">   <token-xpath expression="$current-value/component[1]"/>   <token-text xml:space="preserve"> </token-text>   <token-xpath expression="$current-value/component[2]"/>   <token-text xml:space="preserve"> </token-text>   <token-xpath expression="$current-value/component[3]"/>   <token-text xml:space="preserve"> </token-text>   <token-xpath expression="$current-value/component[4]"/>   <token-text xml:space="preserve"> </token-text>   <token-xpath expression="$current-value/component[5]"/>   <token-text xml:space="preserve"> </token-text>   <token-xpath expression="$current-value/component[6]"/>  </arg-value> </do-reformat-op-attr>

In these cases I just use XPATH on the magical current-value variable, looking for the components that I want.

For Fax it is where the XML attribute name, has a value of faxNumber, and for the Postal Address I just use the 6 values in order, with a space in between. The current-value variable works like it is magical, and it only can be used inside the Reformat Operation Attribute token, (just as current-node only works in the For Each token, although current-op is always available), and it is an implicit loop. You can see it in trace that it performs whatever action you define, over each value in the event document, then loops over the next one (if there is another value). If you treat current-value as a string, you get a string (which for a node-set would be concatenated values as it is cast to a string) and if you treat it as a node-set, you get a node-set. So you can do XPATH tricks like above. Where an XPATH of $current-value/component[@name='faxNumber'] will look at each <value> node, and then look for a <component> child node, whose XML attribute name, is faxNumber. You do not need a trailing /value in the XPATH since you are already inside a <value> node. You could have a trailing /text() though if you wanted. But it will be cast as a string without the text() function.

For the Postal Address case, I just used the shorthand for position()=1 in the predicate, which is just [1] and much quicker to type. I just recently realized why when I tried a variable in a predicate like to provide the position information that $current-value/component[$COUNTER] does not work, but $current-value/component[position()=$COUNTER] is because $COUNTER is probably being seen as a string not an integer, and thus one more alternate way to get it to work would be $current-value/component[number($COUNTER)] which made me feel better once I figured out why that was not working. XPATH is interesting and somewhat confusing in the IDM context. I have tried to offer examples and explanations on the topic and you can read more about them here:


Cool tips:

Another odd schema mapping is eDirectory's workforceId to Office 365's Office attribute. That seems like an odd default choice. I am trying to find a list of the Office 365 schema, but no luck yet. I asked some NetIQ contacts if the driver supports getSchema() and if so, to get me the DirXML-ApplicationSchema attribute from the driver. If your driver supports getSchema() then on the first driver start, and anytime you Refresh Application Schema in iManager, the driver calls the getSchema() function, which is supposed to return the entire application schema and store it on the driver object as DirXML-ApplicationSchema. Not all drivers support it (often the application may not provide it, in which case, the basic driver configuration could pre-populate the attribute, or just ignore it altogether). What this does is to show you the schema attributes, and if they are multivalued. You can see a really clever way to use this, in the context of the Active Directory driver, in this article: Generic Single-valued Schema Enforcement

I have not been able to find documentation from Microsoft yet on the schema used so it is hard to tell if there is a better choice than Office.

The last interesting schema map item I want to talk about is how Internet EMail Address is mapped to AlternateAddresses. In Office 365 it would seem that your User Principal Name is the key, and the main email address. But if you have a different email address in eDirectory that gets sent to the AlternateAddresses attribute.

That about covers the GCVs, schema map and filter settings but I forgot about configuration settings. Before I move on to the fun stuff, the policies I will cover the configuration settings.


How To-Best Practice
Comment List