Follow me on Twitter @AntonioMaio2

Thursday, October 20, 2016

Synchronizing Custom AD Attributes to Office 365 - Part 3

This blog is the 3rd in a 3 part series on synchronizing and working with custom AD attributes in Office 365. In this post we continue with our final step, showing you how to customize the AD Connect synchronization rules.  This will allow your custom AD attributes (customized by extending your AD schema) can be stored in extension attributes in Office 365, so that you can retrieve and work with them.


So, how do we get our custom on premise AD attributes into Office 365 extension attributes so that we can use the Windows Azure AD Module for PowerShell to actually read them?



Step 3 - Customize AD Connect Synchronization Rules

As mentioned previously, you can configure AD Connect to synchronize custom AD attributes to Office 365.  When they are synchronized the attribute name in Azure AD will be extension_<application GUID>_<custom attribute name>.  

However, there are currently NO Office 365 workloads that will consume those attributes.  This means that not even existing PowerShell cmdlets for Azure AD or Exchange Online will retrieve or be able to work with those attributes.

Consider these possible scenarios:
  • So, what if you need to work with those custom on premise AD attributes in Office 365, but you cannot integrate the Graph API yet?  
  • Or what if you have a need to integrate those custom attributes into some existing PowerShell scripts that you already run against Office 365?  
  • And, what if you don't really have an option to modify the on premise AD custom attributes to use the extension attributes because other line of business apps are already writing into those custom attributes?

Well, an option is to modify the synchronization rules on your AD Connect server so that AD Connect still reads the custom attributes from your on premise AD but writes them into the built in extension attributes in Azure AD (customAttribute1, customAttribute2 ...customAttribute15).  This way your on premise line of business apps can continue to work as they currently do, with the custom AD attributes, but you can use the Exchange Online PowerShell cmdlets to retrieve and work with those custom attributes through the built in extension attributes.

Follow this procedure in order to accomplish exactly that:

1. On your AD Connect server, run the Synchronization Rule Editor by executing C:\Program Files\Microsoft Azure AD Sync\UIShell\SyncRulesEditor.exe. 


You'll notice at the top of the window is a dropdown for filtering the list to show either Inbound or Outbound rules.
  • Inbound Rules - will read on premise AD attributes and write them to the sync Metaverse which managed by AD Connect.
  • Outbound Rules - will read attributes from the sync Metaverse and write them to Azure AD in Office 365.
The sync process is always a multi-step process that uses the Metaverse as an intermediary step in the process.

Its extremely important to remember that you should NOT edit existing built in synchronization rules. These are rules that are created and managed by the AD Connection synchronization process.  If you attempt to edit an existing rule you will be presented with the following warning, which we highly recommend that you follow!

2. Select Outbound in the dropdown menu in the window to review the Outbound synchronization rules. Scroll down in the rule list and find a rule called "Out to AAD - User DirectoryExtension".  This rule represents the action of reading the custom attributes you configured in AD Connect from on premise AD and writing their values to users in Azure AD.  


3. Select the rule "Out to AAD - User DirectoryExtension" and click Edit.  When the warning appears, click Yes to create an editable copy of the rule.  
  • The new rule will be named "Out to AAD - User DirectoryExtension - Cloned - <date/time>".

  • In the rule edit window, change the Precedence value of the rule from -1 to 1 more than the original rule.  In my case, the original rule was set to a Precedence of 145 so I set the Precedence for the cloned rule to 146 so that the cloned rule executes right after the original.

  • Click Transformations in the left hand menu.  All of the custom attributes that you selected in AD Connect to synchronize should be listed here.  Notice that the Target Attribute column is the attribute name in Azure AD which the value will be synchronized to.  Notice also that the target attribute name is as we described earlier: extension_<application GUID>_<custom attribute name>.  The Source column is the attribute name within the sync process Metaverse - again, that intermediary location where sync data is stored prior to writing to Azure AD.


4. For each custom attribute, modify the Target Attribute column to be one of the extension attributes: extensionAttribute1, extensionAttribute2 ...extensionAttribute15.  Ensure that you do not use an extension attribute more than once.

This will now force AD connect to read your on premise custom AD attributes, where they are currently configured, and write them into the built in extension attributes in Azure AD in Office 365!

5. The original rule that you cloned has been disabled.  If you wish, you can edit that rule again, this time click No on the warning telling you to create a copy, deselect the Disabled checkbox and click Save.  This means your custom attribute will sync to the attribute in Azure AD it was originally destined for and to the extensionAttribute you just selected.

6. Once all rule modifications are saved, close the Synchronization Rule Editor using the X in the top right corner.  Run the AD Connect configuration wizard and force a fresh synchronization.

7.  Now we test that our custom AD attributes were synchronized to the extension attributes in Azure AD.  Use the Exchange Online PowerShell cmdlets to retrieve the extension attributes for a user that we know has values in those fields.  Once you've connected to the Exchange Online PowerShell cmdlets, use one of the following:

get-mailbox <a user's email address> | select *

get-recipient <a user's email address> | select *

With either of these you will retrieve the Azure AD attributes customAttribute1, customAttribute2 ...customAttribute15 for the user.  You should now see your custom attribute values coming back from Azure AD in Office 365:

Remember: To use Exchange Online cmdlets for a user , that user MUST have an Exchange Online mailbox, which means they MUST be licensed for Exchange Online.  If a user is not licensed for Exchange Online, the sync process still synchronizes the attributes correctly for that user.  However, you will not be able to call the Exchange Online cmdlets for that user to retrieve the attribute values.

Enjoy.
   -Antonio

1 comment:

  1. being new to all these kind of programs and not knowing a thing it gets really hard to handle. and this post helps me quite a lot with it. thank you for posting. keep updating

    ReplyDelete