How-to Upgrade DirSync to Azure AD Connect (and move to a new server at the same time)

Back to Blog

How-to Upgrade DirSync to Azure AD Connect (and move to a new server at the same time)

Many a small business using Exchange Online, Office 365 or other Microsoft cloud services has opted to enable Directory Synchronization–this means you can have the same credentials on-premises and in the cloud. Most commonly, this synchronization was achieved with a tool called DirSync. And wouldn’t you know it, that tool is now being deprecated, and will be retired a little less than 1 year from now (support ends in April 2017).

The process for upgrading DirSync to Azure AD Connect in-place is fairly straightforward.  The installation wizard for AAD Conenct will detect your configuration, and automatically export your DirSync configuration and then remove the legacy application for you. However, if you want to upgrade and move to a new server simultaneously, there are a couple of additional steps to be aware of. You might be interested in going this route if your source server is 2008 R2 or older, for example–maybe you’d like to upgrade into something that can stick around for a bit longer like 2012 R2 (or soon, WS 2016).

I followed the process recommended for “parallel deployment” and it went flawlessly. Some field notes from my experience:

  • The tool does require .NET 4.5.1 framework and PoSH 3.0–so you might need to update a 2008 R2 source server
  • Recommend migrating to a member server running Windows Server 2012 R2 Standard or better*
  • You cannot use the same MSSQL server/instance as your DirSync server (most SMB’s will probably just use the included SQL Express install anyway)
  • Be sure you have your Office 365 admin credentials, as well as your DirSync service account credentials handy before you start

The upgrade / migration process:

  1. Install & run Azure AD Connect setup on the source server in export mode
  2. Install & run Azure AD Connect setup on the destination server in migration mode
  3. Uninstall DirSync from the source server & disable staging mode on the destination server
  4. Verify Directory Synchronization health

1. Source Server: Run Azure AD Connect in export mode

After Azure AD Connect is done installing on each server, just exit the setup wizard. You do not need to proceed to configure it. From the source server, go to Start > Run and execute the following command:

"C:\Program Files\Microsoft Azure Active Directory Connect\AzureADConnect.exe" /forceexport



The wizard will then present you with the option to Export Settings from your existing DirSync installation. You can just choose a location accessible on the network to save the export file.


2. Destination Server: Install Azure AD Connect in migration mode

On the destination server, go to Start > Run or open a command prompt and execute (as admin):

"C:\Program Files\Microsoft Azure Active Directory Connect\AzureADConnect.exe" /migrate

This will enable you to import that same file. Browse to the network location and complete the rest of the wizard!  You need to be able to sign-in to Office 365 as well as specify a service account for Directory Synchronization to use. If you have an Exchange Server on-premises, it may also ask you about preserving hybrid configuration, and of course if you wish to keep that functionality intact you would select that option.


3. Uninstall DirSync & disable staging mode

One more thing: you need to uninstall DirSync on the source server, and finally launch Azure AD Connect on the destination server, and disable staging mode. Until you do this, the new server will not be exporting any data to Azure AD.


4. Verify Directory Synchronization health

Of course, as with anything, it is worth verifying the success of this process. Check out the Directory Synchronization health in your Office 365 portal, just to be safe.  If you see no errors, then cheers; you’re done!



*AAD Connect cannot be installed on Small Business Server or Windows Server Essentials–it must be installed on Windows Server Standard or Datacenter. Note: it can be installed on a member server or Domain Controller, as long as it uses a writable 2008 R2 or later DC (RODC not supported).

Comments (26)

  • Sandro Alves Reply


    if I have a working environment with dirsync and SSO (ADFS), just to upgrade all settings will be maintained?

    I will not need to enter Azure AD Connet and configuration settings from my ADFS?

    Note: I did ran the upgrade process for Dirsync and everything remained. Regarding ADFS, as no use, I need to know if the need to set up something after dirsync upgrade process already performed.

    Thank you.

    June 13, 2016 at 7:09 am
    • Alexander Reply

      Hi Sandro, if you are having trouble with ADFS after performing this move, I would do two things. First: open Azure AD Connect tool and step through the wizard again (customize rather than express settings). Make sure on the User sign-in page, you have ADFS selected so you have a chance to specify that for the config. Number two: view the current AD FS server and the cloud service settings using the Microsoft Azure Active Directory Module: Connect-MSOLService, then run Get-MSOLFederationProperty –DomainName . This allows you to check that the settings on the AD FS server are consistent with those in the cloud service. If the settings do not match, you can run Update-MsolFederatedDomain –DomainName . More on this topic here.

      June 16, 2016 at 9:04 am
    • Alexander Reply

      Also refer to this page for more on choosing SSO method with Azure AD Connect

      June 16, 2016 at 9:12 am
  • Sandro Reply

    After enable federation

    So you want to enable federation in office azure 365 users unsynchronized ( @onmicrosoft ) still log in applications ( CRM , Sharepoint , etc. ) ?

    June 16, 2016 at 11:33 am
    • Alexander Reply

      I’m not sure I follow what you’re asking here, but from my understanding, if you are upgrading in-place from DirSync to Azure AD Connect, it is straightforward process to run the installation on the same server where DirSync already lives. Otherwise, this procedure applies specifically to migrating the tool to a new server at the same time. There are no “gotcha’s” in the Azure AD Connect documentation for performing this procedure whether or not ADFS is present. However, note that you can always re-configure the Azure AD Connect tool at anytime on the new server (e.g. might as well check the settings before you take it out of staging mode). Just ensure it is setup for ADFS instead of just the Password sync option, and you should be good to go.

      June 16, 2016 at 2:44 pm
  • Sandro Reply


    sorry by Google translation. :)

    I have some users who use sign (@, but not synchronized to enter the applications (CRM, for example).

    after I set my office 365 is federated, these users (@ not synchronized, they can log into applications (CRM, for example)?

    If the answer is yes, I believe I will have password problem because they were not synchronized?

    If the answer is no, I have to synchronize them before enabling the federation?

    Users (@ will continue to access the portal Office 365 normally?

    Timing password, previously run by Dirsyn, now updated to AAD Connect after the federation enabled it remains necessary for users that were synchronized?

    Thank you.

    June 16, 2016 at 3:00 pm
  • Sandro Reply

    It is that I have two rooms actually …

    One with domain only dirsync without ADFS that will deploy.

    And with dirsync with ADFS, which will migrate to AAD Connect.

    In case you have (dirsync + ADFS) what I have found is when I have a room already working with ADFS and DirSync when I do upgrade, it already does all migration.

    That is, if everything is working in the old way (dirsync + ADFS), when do I upgrade it shows no option at all, unless you are upgrading and voila!

    If after the upgrade I have to enter the Azure AD Connect and set the ADFS settings again …

    I want to keep the environment as it is and just upgrade to the ADF Connect.

    Thank you for the patience.

    June 16, 2016 at 3:06 pm
    • Alexander Reply

      Okay, I think I see what you’re saying. Yes–I believe you are on the right path. Basically you can do an in-place upgrade to AAD Connect and it should work the same as before when it was DirSync, then if you wanted to migrate that config to a new server afterward, it should also be possible using export settings feature. As for differences between @onmicrosoft vs. users:
      1) @onmicrosoft users should be unaffected and work normally either way as authentication happens in the cloud, not on-prem
      2) users would be authenticated back to local AD if ADFS is present, so be sure the UPN names are set to match both on-prem and in the cloud (should not be set to [email protected]).

      You can enable OU or attribute filtering so not every user will be included in the directory sync.

      June 16, 2016 at 3:51 pm
  • Sandro Reply


    I just talk with Microsoft Support and they also do not know what happens in this case, where there is already (DIRSYNC + ADFS).

    They believe that everything will remain as before.

    What they were asked to make a backup of the entire server and run the setup. If it presents the settings as they were before with (DIRSYNC + ADFS), we can go ahead.

    In relation to matche the usuá[email protected], they need to be equal, because ADFS will attempt to authenticate using this handle and can not.

    Is there a way using the email alias, but we use ‘ImmutableId’ will not work the same.

    Thank you very much.

    June 16, 2016 at 5:06 pm
    • Alexander Reply

      Yes, you can use SMTP matching also, however the best way to configure directory synchronization is just to set the on-prem accounts to match the UPN suffix of the internet routeable domain name.

      June 16, 2016 at 7:40 pm
  • Jerome Martinez Reply

    Quick question: I see that you give instructions to uninstall DirSync on the source server. After completing all these steps and confirming that all is working well, is it safe to delete Microsoft Azure AD Connect on the OLD (Source Server) as well?

    July 19, 2016 at 5:53 pm
    • Alexander Reply

      Sorry for the delay in response! Yes, if you are exporting on the destination server from Azure AD Connect, it is completely appropriate to remove it from the source server.

      July 26, 2016 at 9:42 am
  • Jeff Reply

    Using parallel upgrade method, do I have to uninstall dirsync before enabling AD connect? Could I simply disable dirsync and turn off the server? Then uninstall later. This would give me a fall back incase something goes terribly wrong.

    August 17, 2016 at 10:25 am
    • Alexander Reply

      They key is to avoid the potential of having two separate tools that could attempt export at the same time. I think this would be difficult to guarantee without fully removing DirSync. DirSync and Azure AD Connect work much in the same way–they export data from local AD to another local database first, and the information from that database is what then exports to the cloud. After it dumps to the local db, it will remain in staging mode until you take it out, giving you a chance to review the configuration if you like. If you don’t like what Azure AD Connect is exporting, you can make adjustments (OU or attribute-based filtering, etc.), and then re-enable.

      August 18, 2016 at 4:15 pm
  • alainSaav Reply

    Hi Alexander, your Blog is very interesting, I have DirSync yet, and ADF too, in different Servers, I have a question. I can migrate Only Dirsync to Azure AD Connect. not affect to ADFS?

    February 8, 2017 at 6:02 am
    • Alexander Reply

      Correct, the directory synchronization is just an export to Azure AD, ADFS doesn’t need to be aware of where that export is taking place on your network, just that it is taking place is fine. I have described a “parallel deployment” in this article, but you can also do an in-place upgrade if moving to a new server is not a requirement. Check out this resource for another detailed description of both options.

      February 10, 2017 at 10:16 am
  • Viraj Talpade Reply

    Thank you for the detailed article. I cannot get the /forceexport switch to work with AzureAdConnect.exe on my current DirSync server. Windows 2008 R2. Any thoughts?

    March 9, 2017 at 5:16 pm
    • Alexander Reply

      Interesting. Have you tried opening an elevated command prompt and running it from there? Or navigating (cd) directly into the program folder and executing from there? Also, make sure you’re using the correct quotes around the command, before the switch. Copy/paste from browser doesn’t always work so well, either for getting the correct characters. Let me know if you are able to resolve it!

      March 10, 2017 at 1:56 pm
  • Brad H Reply

    I have DirSync and ADFS 2.1. I’ve already installed ADFS 3 Farm and imported the settings from 2.1 to 3. I’ve run the ADFS health tool and everything checks out for ADFS 3. I can also hit the sign in page for ADFS 3 and SSO works. Should I move the org to the new ADFS 3 first, then when that is working w/DirSync still in place, upgrade DirSync to AAD Connect? If so, when I do the in-place upgrade to AAD Connect, do I let it complete then re-run the AAD Connect wizard to connect it to the ADFS 3 Server? I know they have FIM installed on the DirSync server so I assume I will need to uninstall that after the AAD Connect Upgrade? They have over 5,000 users so I want to make sure I take it in steps so there isn’t much of an outage other than moving some internal/external DNS records to the new ADFS 3 Farm.

    March 29, 2017 at 8:39 am
    • Alexander Reply

      Hi Brad, if you do the in-place upgrade, you will not need to perform an uninstall of FIM. Some of the FIM components are still leveraged by AAD Connect, and everything will be taken care of in that upgrade process. I suppose it wouldn’t hurt to run through the AAD Connect configuration after you upgrade the DirSync instance, but I don’t think it would be necessary, unless you are seeing Directory Synchronization errors after the upgrade. The AAD Connect tool, and DirSync before it, would have been running an export of Directory information to a small local database (or an SQL server elsewhere on the network), and that would have been the basis for export in turn to the Azure AD tenancy. This all happens outside of AD FS, and does not rely on it. If you are setting up AD FS from scratch, then AAD Connect setup can be leveraged to help deploy the AD FS service on whatever target servers you specify, but if you already have AD FS, this is not necessary. The upgrade will detect that you already have AD FS, and the directory export should therefore still continue to function the same as it did before the upgrade. Since you have AD FS in place now, this means that it would NOT export the password hash to Azure AD, since authentication takes place via the on-prem AD FS proxy instead of in the cloud. If you were changing your authentication method to something other than AD FS, and you wanted to enable password sync instead, then you would need to re-run the configuration of AAD Connect, but if you are staying as-is, then I don’t believe it requires any reconfiguration. Does that make sense?

      March 29, 2017 at 12:21 pm
      • Brad H Reply

        I left a reply, but it didn’t show up within the website so will shoot another one in the event you didn’t get it. I see what you are saying and AAD Connect is more of setting up new Windows 2012R2 WAP/ADFS services, troubleshooting and repairing ADFS trusts etc. IF we have ADFS 2.1 already setup w/Dirsync, then we can just upgrade Dirsync and it will know that ADFS 2.1 is already setup. It should function as Dirsync and continue to replicate.
        Once I upgrade Dirsync to AAD Connect, I will eventually move from ADFS 2.1 to the 3.0 Servers. I know you can setup some stuff in AAD Connect, but was curious if I have to do anything in AAD Connect when I switch to the new ADFS server? We will be keeping the DNS records the same along with the ADFS Service, Display name, etc. I did one of the export config from 2.1, keep the same cert and import it into the new system. Different WID’s but same settings etc. If I move DNS records I assume AAD Connect will see the DNS change and work with the new 3.0 server or will have I have to run the wizard to tell it I have new 2012r2 ADFS server?

        April 3, 2017 at 8:56 am
        • Alexander Reply

          Brad, I do not believe that you will need to do anything with Azure AD Connect to make that switch-over to ADFS 3.0. Azure AD Connect will just continue exporting directory information to Azure AD, and part of that configuration with the tenant is your AD FS setup, which is referenced by DNS name only, so far as I know.

          April 3, 2017 at 1:45 pm
  • Kevin Conway Reply

    I see the step where you “disable” staging mode during the process for Uninstalling Dirsync from the source machine. Is there a step at the beginning that you need to “enable” staging mode from the Export Process or the Install of Azure AD Connect on the Destination Machine? Also are users able to login and use the service during the process of the Parallel Upgrade?


    Kevin C.

    October 31, 2017 at 10:32 am
    • Alex Reply

      1. When you install the AAD Connect tool on the destination server in migration mode, staging is automatically enabled. That is why you need to disable it after everything is settled. Only one export should be taking place at a time–source server or destination server, just not both.
      2. The login functionality should not be disrupted at all during the process.

      October 31, 2017 at 11:31 am
  • Kevin Conway Reply


    Thanks for your reply. I have one other question. If your users already have licences issued to them in the previous Dirsync machine, do they have to be re-licensed once you perform the parallel upgrade to a new machine on Azure Ad Connect? In the following link:

    at the bottom of the article, it mentions a “Next Steps” section that states you need to add licenses. Is this necessary if your users already have a license before the upgrade? I’m not sure if this implies that the upgrade process removes the license (seems strange) and that you would have to re-add it after the upgrade.

    Kevin C

    November 3, 2017 at 7:50 am
    • Alex Reply

      Should not be necessary to re-license existing users.

      November 3, 2017 at 2:14 pm

Leave a Reply

Back to Blog

Helping IT Consultants Succeed in the Microsoft Cloud

Have a Question? Contact me today.