Duplicating your production AAD Connect sync rules on your staging server using the AAD Connect Helper Module

Duplicating your production AAD Connect sync rules on your staging server using the AAD Connect Helper Module

Once upon a time, migrating your AAD Connect primary sync server configuration to your staging server was a simple matter of using the Get-ADSyncServerConfiguration and Set-ADSyncServerConfiguration cmdlets provided as part of the ADSync module.

However, in the most recent versions of AAD Connect (v 1.1.751 and later) the Get-ADSyncServerConfiguration cmdlet still works, however the Set-ADSyncServerConfiguration cmdlet returns a warning that use of the cmdlet is now unsupported…

(I suspect that someone must have shot themselves in the foot somehow with this method and then tried to get Premier to help them out of the mess… but I digress)

The best, and currently supported method of migrating your configuration from a primary sync server to a staging mode server is to duplicate all the custom sync rules by exporting the custom rules from the Sync Rules Editor on the primary server.

You can select one or more rules (using Ctrl-click, or Shift-Click) in the editor, and then click Export to be presented with a notepad document containing an export of all the necessary PowerShell commands to re-create the sync rules.

This is great for backing up and restoring rules on the same server, however the PowerShell commands that are returned in the notepad document include a reference to the Connector ID value.

In my lab, the connector ID value for contoso.com is 800aa7ae-cd91-435a-b093-c2d60b738769

You can see the same information on the server using the Get-ADSyncConnector cmdlet

Get-ADSyncConnector | Select Name, Identifier

Sadly, on my staging server the connector ID value is different, as seen below.

This means that I cannot simply take my exported PowerShell commands from my primary sync server and run them on the staging server.  If I did, I’d get something like this…

The error – specified management agent cannot be found – is due to the mismatch of connector ID value.

(note: the term “Management Agent” makes reference to a term in FIM/MIM – which AAD Connect is based on – in AAD Connect it’s called a “Connector” )

As a result, we need to modify the PowerShell commands, updating the connector reference, before we can run the commands on our staging server.

The Solution…

For these purposes, I’ve created the AADCHelper PowerShell module, it’s currently a collection of functions that I’ve built for the purposes of reporting and converting sync rule exports to work on other servers.

(Before following any of the steps below, be sure to back up your server configuration and sync rules on both your primary sync server and your new staging server)

Firstly – if the custom rules on the primary server are a result of cloned default rules, we will want to disable the same default rules on the staging server (because we’re importing the same cloned rules).  In the module, there’s a function called Get-DisabledRules – use this cmdlet on the primary sync server to generate a list of all the disabled rules.

Once you have the list of disabled rules, proceed to your new staging server and launch the Sync Rules Editor.

Locate each rule (compare number AND name, to make sure the rule numbers align), click on the rule and select Edit.

When prompted to clone the rule, click NO.  (We are just disabling it, and we don’t want to create a cloned copy – if you click Yes, it will clone the rule – do don’t do that)

Select the Disabled check-box and click Save.

Note: upgrades to AAD Connect will replace these rules, but they will remain disabled.

Now that you’ve disabled all the same default rules on the staging server, copy your export TXT (or PS1) file from the primary sync server to the staging server.

The next function, Import-SyncRules, is the real workhorse here, it does the sync rule conversion so that you can simply run the PS1 file to import the rules from the primary server.

Simply run the cmdlet Import-CustomRules with the -FileName parameter set to the PS1 or TXT file which contains your exported rules from the primary sync server.

Note : the cmdlet identified there is only 1 Active Directory connector (ie. non-Azure) and therefore it defaults to that connector for the replacement action within the file.

If there were more than 1 Active Directory (see below), you will be prompted to choose the connector that the rules should be applied to.

You would enter the number value for the connector the export is for, and press <enter>

The cmdlet will save a new file to the same folder, with the addition of -updated.   If this is a PS1 file, you can simply run it to apply the customizations, if it’s a TXT file it either needs to be renamed to PS1 or the contents copied and pasted into a PowerShell window.

Once you have completed the re-import of custom rules on your staging server, you can then use the Get-CustomRules cmdlet on both servers to generate a report of all custom rules for comparison purposes.

In closing – the process outlined above, and the helper scripts I’ve provided, should make the forklift of sync rule customizations from your primary to staging mode servers both easier and more reliable.  That said, make sure to make a backup of your server before making any changes.

The AADCHelper PowerShell Module and how to install it can be found here

Leave a Reply

Your email address will not be published. Required fields are marked *