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.

Prerequisites

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:

• Start 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.
• Open 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’.
• Open 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.
• Click 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.
• The 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).