Migrating from ADFS 2.1 to 4.0

{There was a section here on converting Windows 2016 server eval to full version for enterprise customers, but as Windows 2016 is properly out there now it seems pointless. I’ve pasted what was here into the comments below in case anyone needs it}

Upgrading ADFS

The first question after deciding to roll out a new version of Windows server into your organisation is what to deploy first, and the answer for me, at least, turned out to be ADFS 4.0. We were running a 2.1 system and as we’re looking for a few upgrades that will take advantage of some of the things in ADFS 4.0 on Windows Server 2016 this seemed like an easy place to start.

It turns out that there are very few, if any, guides for migrating from ADFS 2 to 4 so I guess this is my attempt at addressing that balance. The good news is that it appears that the guides for ADFS 2.1 to 3.0 are actually still pretty decent guides for 2.1 -> 4.0 migrations, so things shouldn’t be too difficult, and ADFS 3.0 to 4.0 is even easier still.

I will quickly run through the process I used for a 2.1 to 4.0 migration that leaves the ADFS 2.1 server available. I am expecting a certain degree of familiarity with Windows server in this guide (e.g. I’m not going to go into a 20-step process for installing a role or tell you when/how to click ‘Next’) but this should still be useful as a step-by-step guide.


Firstly, of course, you need to build a Windows Server 2016 server and join it to your domain. Current best practice suggests that ADFS should be sitting on a domain controller, which is something that will complicate a migration like this one, but I will skip around that for now; for the purposes of this article, both the Windows 2012 (ADFS 2.1) server and the Windows 2016 (ADFS 4.0) server are domain members. You will also need the Windows 2016 install media available to be mounted on both the ADFS 2.1 and ADFS 4.0 servers.

Understand that ADFS 4.0 is very different in its requirements from ADFS 2.1; it no longer uses IIS, so this should not be installed as a prerequisite for ADFS on the new server. ADFS 4.0 should be published to the world via a Windows Server Web Application Proxy server, which can work as both a secure/hardened endpoint to publish your ADFS service to the world and also (as the name implies) a reverse proxy for publishing internal servers to the outside world, which gives you the ability to enable SSO for all the services published via the Web Application Proxy fairly painlessly. Windows Web Application Proxy is a component of the Remote Access Windows Server role.

Prepare another server for the Windows 2016 Web Application Proxy role and think hard about how you want to deploy that in line with your current security requirements and policies.

If you’ve managed to give your ADFS 2.1 server the same Windows host name as the federation farm name, you will need to play with hosts records on your new ADFS 4.0 server and its corresponding Windows Application Proxy server to ensure that the new ADFS server and related infrastructure sends all traffic to the ADFS 4.0 server

e.g. if my ADFS 2.1 server has a host name of adfs.thingydo and my ADFS federation farm name is adfs.thingydo.itsalwaysmyproblem.com then I will need to edit c:\windows\system32\drivers\etc\hosts on the server to point all traffic for adfs.thingydo.itsalwaysmyproblem.com to the ADFS 4.0 server, and I will probably also need to check and tidy up SPNs when I decommission the ADFS 2.1 server.

Carry out all the steps below on the ADFS 2.1 server:

  • adfs1Start the AD FS management tool, go to Edit Federation Service Properties… and make a note of the details on the General tab. Next, expand Service -> Certificates, and make a note of the Service Communications certificate. It is important that these are entered correctly on the ADFS 4.0 server later on.
  • Close the AD FS Management tool and open up local services. Make a note of the account that the AD FS Windows Service is using. This should be a domain account, and you will need this account and its password when installing ADFS on the ADFS 4.0 server.
  • adfs2Open the certificates store for the Local Computer and export the Service Communications Certificate, along with its private key, to a file (this will generally be in the Personal store for the local computer account) Keep this file protected and stored somewhere safe.Remember not to delete the certificate or its private key from the 2.1 server – we’re trying to leave the old ADFS infrastructure online while we migrate to the new, and deleting certificates it relies upon is not going to help.
  • Finally for the ADFS 2.1 server, mount the Windows Sever 2016 install media and open a Powershell prompt as Administrator. In Powershell, navigate to the \support\adfs\ folder, then:
    • create a folder to export your adfs configuration to with mkdir c:\adfsbackup,
    • run export-federationconfiguration.ps1 -path c:\adfsbackup to export a copy of your ADFS 2.1 configuration to the folder you just created.
  • Dismount the Windows 2016 install media and copy the ADFS 2.1 export folder and certificate you exported above to a secure area that’s accessible from the new server, then log out.

Carry out all the steps below on the ADFS 4.0 server:

  • Import the Service Communication certificate into the same store on the ADFS 4.0 server that it was located in on the ADFS 2.1 server. To do this, open the certificate store for the local computer, navigate to  the local computer’s personal certificate store and import the certificate you exported from the ADFS 2.1 server, marking the public key as exportable during the import process. You should now see the certificate available in the local computer personal certificates store, and it should show ‘You have a private key that corresponds to this certificate’.
  • adfs-5Open Server Manager and go to Add Roles and Features. Select Active Directory Federation Services and proceed through the role installation. When the role is installed, click through to Configure the federation service on this Server.
  • Select Create the first federation server in a federation farm, and on the next page of the wizard select a domain admin account to install ADFS. Do not put in the service account at this time.
  • Select the certificate we just imported – this must be the correct, valid Service Communications certificate we exported above, and enter the Federation Service Display Name this must match the ADFS 2.1 farm name we made a note of above.
  • Enter the service account for the ADFS service to run under on the ADFS 4.0 server. Again, this must be the ADFS service account we made a note of from the 2.1 server.
  • Specify a database. I’m assuming that if your needs are unsophisticated enough that this guide is useful, and if that’s true then select the default Windows Internal Database. You can use an (already setup and available) MSSQL server should you wish but don’t use the same database/instance as the ADFS 2.1 farm if you’re using MSSQL.
  • adfs3Click through prerequisite checks and click Configure. When this has completed, you can open the AD FS Management console and hopefully see that you have a working ADFS 4.0 farm. Your imported certificate should be visible in the Services / Certificates tab. If you expand Trust Relationships / Relaying Party Trusts, you should see that your configuration from the ADFS 2.1 farm has not been imported yet.
  • Mount the Windows Sever 2016 install media and open a Powershell prompt as Administrator. In Powershell, navigate to the \support\adfs\ folder on the install media then:
    • run import-federationconfiguration.ps1 -path c:\adfsbackup (change the path here to point to wherever you saved the configuration export from above) to import a copy of your ADFS 2.1 configuration into the ADFS 4.0 server.
    • The import routine will warn you that it will remove / overwrite the config on the target server. You are sure you’re on the right server before you proceed, I hope. Once you’ve double-checked that, go ahead.
  • adfs4The import should run fairly quickly. Once it’s complete you can go back to AD FS Management and verify the import behaved as expected by checking  rust Relationships / Relaying Party Trusts and ensuring the services there are the ones you expect to see imported from the ADFS 2.1 server.
  • We are nearly ready to test ADFS from a test client, which we can do by editing the hosts file on that client to point to your new ADFS 4.0 server, and visiting the ADFS IDPInitiatedSignon page (e.g https://adfs.thingydo.itsalwaysmyproblem.com/adfs/ls/IdpInitiatedSignon.aspx).
    • On the ADFS 4.0 server, we need to test that page is enabled prior to testing. To do that, from an administrative powershell prompt run (get-adfsproperties).EnableIDPInitiatedSignonPage.
    • If the value returned is false, run Set-ADFSProperties -EnableIDPInitiatedSignonPage $true. Re-run the get-adfsproperties command above to check the value is now true.
  • From the test client, with the hosts file modified, we are now ready to test signing in. Visit your ADFS 4.0 server via the federation name (e.g. for my test, I’m using https://adfs.thingydo.itsalwaysmyproblem.com/adfs/ls/IdpInitiatedSignon.aspx) and verify that the login screen looks how you’d expect (much more modern page than the 2.1 signing screen, with (C) 2016 Microsoft at the bottom of the page) then check that you can sign in.
  • For troubleshooting, use the AD FS event logs and work through the various issues you might find there (this is how I diagnosed the issue in the previous step, which logs MSIS 7012 errors in the event log). Keep in mind that you may need to play with hosts files on the ADFS 4.0 server and any test workstations to ensure that authentication traffic is routed through the ADFS 4.0 server for testing.

Adding further servers and going into production

You can now move towards production. Add WAP servers as you require, pointed to the ADFS 4.0 server. You can add additional ADFS 4.0 servers if you need by just starting the ADFS role configuration and adding them as additional ADFS servers into the ADFS 4.0 farm.

When you are ready to go into production, undo all the hosts files edits you’ve made to test the ADFS 4.0 server and update internal and external DNS records to point all requests for ADFS traffic to the new ADFS 4.0 server(s).


  1. Hi Majeed, thanks for commenting.

    You need to do the export-import method. I’ve outlined the exact steps for 2.0 to 4.0 that worked for my org, but yes the export-import thing is what I did. The other method (adding members to the farm) only works from ADFS 3.0 upwards.

    We have quite a few different relying trusts that were using SAML, Shibboleth, etc. as well as the Office 365 connection so we had a fairly complicated setup but the steps I talk about above worked as easy as anything. The bug I mentioned in my October 24th comment is now fixed by the way, which makes the process even easier

    And you don’t have to switch off the old ADFS system until you’re sure the new one works, after all!

  2. Windows 2016 Licensing – going into production with evaluation media — this comment was previously part of the main article, and I’m moving it as its no longer relevant.

    So Windows Server 2016’s availability this month (October 2016 when I wrote this) raises a couple of questions, such as “If you’re deploying this right now, how are you getting around the evaluation key on the media that’s available right now?” – and the answer, for those of you with Volume Licensing anyway, is:

    Open an Admin command prompt.
    Check what edition of Windows is installed with this command: DISM /online /Get-CurrentEdition (It might say something like “Current Edition : ServerDatacenterEval”).
    See what versions you can licence (assuming you have keys for them) with DISM /online /Get-TargetEditions.
    Then run DISM /online /Set-Edition: /ProductKey:XXXXX-XXXXX-XXXXX-XXXXX-XXXXX /AcceptEula, where is the edition you want to convert to, and the value for ProductKey is your valid server key.
    Restart the server and check to see if its properly licensed (You can do this from the GUI: Settings, Update and Security, Activation)… Mine was not (It had changed the product key and failed to activate the first time, and I had to enter the product key again to activate successfully).
    There are a few zero-day Windows Updates for W2016 server. Be sure to install them before using it in anger. No, seriously.

  3. My import is just hanging on my ADFS 4.0 environment. It has been about 2 hours and still says importing. The setup is pretty small. Have you ever seen this?

  4. I will be going through this upgrade soon, the only difference is we have a proxy server. Can ADFS 2.0 function with ADFS 3.0?

  5. Hi Mark,
    I don’t think ADFS 2.0 and 3.0/4.0 can co-exist through the same proxy as they work completely differently.

    You can minimise the impact of the cutover by playing games with hosts files for testing the new ADFS infrastructure: if you edit the hosts files on your test clients and the new ADFS farm servers to point the federation URL back to the new farm while leaving the name ‘as is’ on DNS until you’re ready then you can test without disrupting normal use too much… but I think that’s as good as it gets.

    1. Hi Krisna,
      Sorry for this but I completely forgot to mention that in my post, I took this part for granted as I’d already rolled out 2012r2 on to my domain controllers and had an extension to 2016 planned.

      I think you need to extend the AD schema as per https://ronnydejong.com/2014/05/27/deploy-active-directory-federation-services-ad-fs-3-0-in-a-pre-windows-server-2012-r2-era/ and https://social.technet.microsoft.com/Forums/ie/en-US/dc9482d6-8cc8-4961-992f-3d6149d7c92d/adfs-40-ad-schema?forum=ADFS.

      You’ll need to extend the schema to 2012R2 level to get even the ADFS 3.0 features working, then again to 2016 level to get any ADFS 4.0 feature benefits on top of the 2012r2 schema features.

      Sorry about that, hope this clears up any confusion.

    2. I was able to implement using 2008 R2 schema. With no issues. I am currently working on upgrading all our DC to 2016 by the of this month.

      1. Hello Mark
        Could you confirm that you started from a domain controller / schema in 2008 R2 to an ADFS 4.0 without updating the schema and without adding an additional domain controller in 2012 or 2016?
        because in my case I have 2 domain controller in 2008R2 and I intend to migrate ADFS on a new server 2016 without touching the domain controller

  6. Hi Rob,

    Do you need to have all your DC’s at Server 2016, with the DFL and FFL raised to 2016, or do you just need a single 2016 DC in the environment?

    1. Hi Chris,
      You only need one DC – not all of mine are 2016 yet so I’m pretty confident on that score. Actually I’m not sure you need a 2016 DC if we’re being picky. I think you just need the appropriate schema extensions to your forest and domain(s) rather than any new 2016 feature as such, but it’s probably sensible to upgrade at least one DC.

  7. Hi Rob,

    I migrated from 2.0 to 4.0 a farm of 20 relying parties. I am testing with my hosts file to the new farm, 3 of the relying parties work, but the others do not. Is this expected behavior? I opened a case with Microsoft, and they think its because the public DNS is still pointing to the old 2.0 (production) farm.

    They stated everything should just work when we cutover the prod DNS. I dont want to take that chance if there is the possibility of it being an issue.

    1. Hi Rob, I have to say “it worked for me” with their approach but I appreciate that’s no guarantee. I did test by using host files to redirect the relying party logins you wish to test and you can do the same,but you’d need to do this on client, ADFS server, WAP (if applicable), relying trust server and everything else in the chain, and then tidy them all up which is a bother afterward.

      I tested one or two I was especially worried about, then decided I was happy. With 20 to check you might feel the same!

  8. Thank you for the quick reply. Unfortunately I don’t have the ability to change the relying parties as they are 3rd party hosted. Guess I’ll have to roll the dice on a test cut over!

  9. Good read. One odd question, My ADFS 2.0 server doesn’t have a Service Communications Cert. Just a Token Signing and Decrypting. Is that going to cause me any problems?

    1. Hi Jason,
      ADFS 2.0 and ADFS 2.1 are quite different. I don’t want to suggest you follow my procedure for migration for ADFS 2.1 on an ADFS 2.0 server without a _lot_ of testing.

      As for the SCS cert, you must have one if your ADFS server is working 😉 but if my memory serves me rightly, as the SCS cert is essentially just bound to the website used for the ADFS “web site”, in ADFS 2.0 the cert is linked to IIS rather than to ADFS because ADFS 2.0 uses IIS to provide its https website function. (Also, https://support.microsoft.com/en-us/help/3044974 seems to say much the same where it refers to certificate troubleshooting for ADFS 2.0).

      Sorry I can’t be of more help but I’d be guessing at this point and I guess both of us would hate my suggestions to mess your system up because I didn’t want to admit that…

      1. Yes, the IIS site does have a valid cert so that must be the SCS cert.

        Thanks for the advice, am going to keep looking for migrating from 2.0.

  10. Hi thank you for the clear directions from ADFS migration, I just successfully complete my ADFS move from 2.1 to Server 2019 with very little downtime.. thank you..

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.