Thursday 2 February 2017

Upgrade ADFS 3.0 to 4.0 with Windows Server 2016 using PowerShell

Windows Server 2016 introduces the ability to perform an in-place upgrade of Active Directory Federation Services (ADFS). In previous versions of Federation Services, you were required to “rip and replace” the deployment with a new set of servers, you would then have to export/import your configuration data.

It should be noted that an OS level upgrade from Windows Server 2012 R2 to 2016 will not automatically upgrade the ADFS farm.

         Windows Server 2012 R2 – ADFS 3.0
         Windows Server 2016 – ADFS 4.0 
Due to the nature of what ADFS does this was problematic for organizations, if your organization was using Federation Services for Office 365 authentication an upgrade would result in downtime to the service. ADFS 4.0 introduces the concept of a “farm behavior level” which is similar to how domain functional levels work in Active Directory. When you have ADFS 3.0 & 4.0 in the same farm this is considered a “mixed” farm. The features available across the server farm will be constraint to ADFS 3.0 if you are running in mixed mode. From the research I have done there are no reasons to retain a mixed mode farm, ADFS 4.0 is 100% backwards compatible with 3.0. A mixed mode farm will literally be for the period in which you introduce your new servers.

Step 1 – Upgrade Active Directory Schema

You must first upgrade the Active Directory schema before you can introduce ADFS 4.0 servers into the environment. This upgrade is non intrusive however it is recommended you ensure a healthy backup of your Active Directory is available in case it goes wrong. The upgrade code is on the Server 2016 ISO at \support\adprep you must also perform the upgrade with an account that has Schema & Enterprise Admin permissions. In addition to this the changes should be made on the Domain Controller that hosts the Schema Master FSMO role.

The following command can be used to determine your FSMO role holders

netdom query fsmo

The forest must be prepared first using the following command

adprep /forestprep

I do not think the /domainprep command is required if you only have a single domain

adprep /domainprep

Step 2 – Prepare the Windows Server 2016 ADFS Server

The command installs ADFS on the target server

Install-WindowsFeature Adfs-Federation -IncludeManagementTools

Step 3 – Introduce Server 2016 (ADFS 4.0) into the existing server farm

Set the following variable which is used to store the ADFS service account credentials, these should be entered in the format DOMAIN\username

$creds = Get-Credential

The following command joins the new server to the server farm hosted on the primary server, please note you do not need the -OverwriteConfiguration switch if you are running this for the first time

Add-AdfsFarmNode -ServiceAccountCredential $creds -PrimaryComputerName primaryserver.domain.local -CertificateThumbprint "DB84EE68879B8xxxxxxxx" -OverwriteConfiguration

Once this has completed run the following command on the new server this reconfigures the farm, and makes the new server the primary

Set-AdfsSyncProperties -Role PrimaryComputer

The following command must be run on all other ADFS servers

Set-AdfsSyncProperties -Role SecondaryComputer  -PrimaryComputerName "oldfsservers"

If you try to launch the ADFS Management console from the new Server 2016 instance it should open as the primary. 

The following command will show only the ADFS 4.0 servers in the farm


The CurrentFarmBehavior outlines what Farm Behavior Level the ADFS farm is operating at. Once the Server 2012 R2 instances are decommissioned and the farm level is raised this will be set to “3”.

Step 4 – Decommission Server 2012 R2 and ADFS 3.0 from the farm

In my environment, the requirement was to upgrade the entire server farm to ADFS 4.0, therefore before I could do this all the old ADFS 3.0 instances must be removed.

The following command has been deprecated in Windows Server 2012 R2.


The recommendation from Microsoft is to uninstall ADFS from the server to remove it from an ADFS server farm.

Step 5 – Raise ADFS Farm Behavior Level

It is advisable to run this command first to check you are in the position to upgrade the farm level


From the primary server run the following command to raise the ADFS server farm level


The Enterprise Key Admins group apparently does not exist until there is a Server 2016 Domain Controller introduced to the Active Directory, so it can be ignored for now. Yet to find any official documentation to support this.