Microsoft Azure AD Connect PowerShell Troubleshooter

For connecting your on-premise Active Directory environment to Microsoft’s Azure directory, the two choices available are to either synchronize the local directory to Azure’s directory or to use federation to point users authenticating to Azure services to your local environment. To synchronize the environments, the best (and only currently supported) tool available is Microsoft’s current iteration of Azure AD Connect. Originally labeled as Windows Azure Active Directory Sync (dirsync) and then Azure Active Directory Sync, the current version is Azure AD Connect, or shortened as AAD Connect.

Having a local Active Directory synced to Azure Active Directory is often done during Office 365 migrations where IT wants users to use the same password to log into the Office 365 services as they use to sign into their local Windows Active Directory joined PCs.

AAD Connect is available here for download:

The tool synchronizes most attributes automatically every 30 minutes. It synchronizes passwords even more often.

Once it is installed in your environment, there is built-in logging so administrations can see what is going on via the Azure AD Connect Synchronization Service tool. Additionally, built into the application is a PowerShell Troubleshooter. To access the Troubleshooter, launch the tool. Be aware whenever the tool is launched that all synchronizations are paused. Continue through the tool by clicking Configure.

Azure AD connect

There are many options to choose from at this point, and likely the most common one is “Customize synchronization options” as this is where the tool is reconfigured as needed. To troubleshoot the current configuration, you can click on the last choice: Troubleshoot. Select it and click Next.

troubleshooting Azure AD connect

The full walkthrough of how to use the Troubleshooter from Microsoft is here:

Click Launch to start the tool.

click launch

You will be prompted what troubleshooting steps you would like to perform.

Let us run through an example where the local Windows Active Directory environment has one forest with 2 sibling domains. The issue is that users from one domain can log into and access Azure services without a problem, while users from the second domain get an error about an invalid password when signing into Azure services. AAD Connect is configured for password hash synchronization. Users show up from both domains in Azure AD Users. In the logs online, there are attempts shown from users logging in, but with invalid passwords. The passwords are verified as being typed correctly.

In the troubleshooter, we choose option 2 to troubleshoot password hash synchronization.

troubleshoot password hash synchronization

Again, because all users from one domain can not sign in, we will select option 1, Password Hash Synchronization does not work at all.

admin windows powershell

This leads to the tool starting to investigate the environment. Be patient while the tool gathers information.

We find that the tool came back with this – there have been successful attempts for one domain, but for the other domain the synchronization agent has never attempted to synchronize passwords. Obviously, that is the underlying issue.

password synchronization issue

Looking into the configuration of AAD Connect we see that this feature is checked.

optional features checkbox

The fix here is a simple IT resolution of turning it off and back on again. Run through the AAD Connect configuration and turn off password hash synchronization. Complete the configuration. Then come back and configure AAD Connect again, this time checking the box for password hash synchronization. After completing this, run the troubleshooter again and follow the same steps. We see now that both the first and second domains are syncing correctly and verify that users can sign in.

azure ad password synchronization resolved

Have any questions regarding troubleshooting Azure AD Connect for your organization or regarding Azure AD Connect in general? Please contact us at any time.

This publication contains general information only and Sikich is not, by means of this publication, rendering accounting, business, financial, investment, legal, tax, or any other professional advice or services. This publication is not a substitute for such professional advice or services, nor should you use it as a basis for any decision, action or omission that may affect you or your business. Before making any decision, taking any action or omitting an action that may affect you or your business, you should consult a qualified professional advisor. In addition, this publication may contain certain content generated by an artificial intelligence (AI) language model. You acknowledge that Sikich shall not be responsible for any loss sustained by you or any person who relies on this publication.

About the Author