We’ve migrated many Active Directory Federation Services (AD FS) implementations from Windows Server 2012 R2 to Windows Server 2016 and beyond. This blogpost intends to share our experiences during these migrations, so you can take advantage of them during your migrations.
How we migrate
In general, we migrate AD FS servers by adding additional AD FS servers to the AD FS Farm. From there, we take one of three routes:
- We cut over the external IP address of the AD FS Farm in the internal DNS zone to the new AD FS server. If applicable, we also change the IP address of the AD FS Farm in the perimeter DNS zone or in the HOSTS file of Web Application Proxy server(s). This is our usual path when an organization wants to migrate one single AD FS server to a new one.
- We add the additional AD FS server(s) to the load-balancer that spreads the authentication requests to a pool of AD FS servers. After a short period of coexistence to check if everything works, we remove the AD FS server(s) the organization no longer wants to use. This is our usual path when an organization has a load-balancer in place; a typical situation when an organization has deployed multiple AD FS servers.
What is migrated
Some settings are configured, by default, when you add an AD FS server to an existing AD FS Farm, while others require manual migration:
Created, by default
By default, the following settings and configuration items are automatically provisioned on additional AD FS servers to the same AD FS farm:
- The certificate-based trust to the Active Directory Federation Services (AD FS) farm for the Web Application Proxy server(s)
- Membership to the AD FS Farm’s FarmNodes configuration for the AD FS farm
- User rights assigments and delegations for the AD FS (managed) service account
- Windows Firewall exceptions to allow inbound communications
Migrated, by default
By default, the following settings and configuration items are automatically provisioned on additional AD FS servers to the same AD FS farm:
- Configuration of all Relying Party Trust (RPT) and AD FS endpoints
- Device Registration settings
- Token-signing and Token-decrypting certificates
- The AD FS certificate, but only when the additional AD FS server is created through the Azure AD Connect wizard
Needs to manually be set or migrated
However, important parts need to be migrated or configured manually:
- The AD FS certificate, unless the additional AD FS Server is created through the Azure AD Connect wizard
- Name resolution to relying parties, when it is not dependent on a DNS infrastructure
- Any firewall rules between the AD FS server and the (load balancer for the) Web Application Proxy Server(s)
- Any firewall rules
- between the AD FS server and the (virtual IP address and the individual nodes of the) SQL Server (cluster or Always-on Availability Group), if SQL Server is used to host the AD FS Configuration Database (by default: TCP1433), or
- between the AD FS server and the other AD FS servers, if Windows Internal Database (WID) is used to host and synchronize changes to the AD FS Configuration Database (by default: TCP80)
- Any network firewall rules and/or network proxy exceptions between the AD FS server and the relying parties
- When the last AD FS server for a down-level version of Windows Server is decommissioned, the AD FS Farm Behavioral Level (FBL) needs to be upgraded. This is a manual action.
Creating an inventory
To transition AD FS servers, it’s a good idea to create an inventory beforehand. Answer these questions:
Q1 What does the AD FS farm look like?
Determine the amount of AD FS servers that are part of the AD FS farm and their hostnames, so you can check the routes and firewall rules from any (new) AD FS server. Run the following line of Windows PowerShell from the AD FS server that is the primary server in case of WID, or any AD FS server when Microsoft SQL Server is used to host the AD FS configuration database:
(Get-AdfsProperties).Hostname
(Get-AdfsProperties).ArtifactDbConnection
(Get-AdfsFarmInformation).FarmNodes | Format-Table
The above three cmdlets return the URL of the AD FS Farm, whether its using Windows Internal Database (WID) or a Microsoft SQL Server as the AD FS configuration database and a table with all the AD FS servers, including their roles in the AD FS farm.
Q2 What domain are the AD FS servers joined to?
As all AD FS servers in an AD FS farm need to be joined to the same Active Directory domain, we’ll look up the DNS domain name using any one of the AD FS servers with the following line of Windows PowerShell:
(Get-WmiObject Win32_ComputerSystem).Domain
Q3 What are the current Relying Party Trusts?
To gather this information, you need to run the following lines on the AD FS server that is the primary server in case of WID, or any AD FS server when Microsoft SQL Server is used to host the AD FS configuration database::
(Get-ADFSRelyingPartyTrust).Name | Format-Table
(Get-ADFSRelyingPartyTrust).MetadataUrl | Format-Table AbsoluteUri
The above two cmdlets return the names of the Relying Party Trusts (RPTs) configured on the AD FS farm, and their federation metadata URLs.
Q4 What do the AD FS servers use for name resolution?
Now that we know the URLs for the AD FS Farm, and federation metadata URLs for relying parties, we can determine the name resolution method used by the AD FS servers. They’re either using a DNS server or using the HOSTS file. The above URLs are mostly covered by DNS, but a safe check is to check the HOSTS file for uncommented entries on the current AD FS server(s) with the following line of PowerShell:
Get-Content C:\Windows\System32\drivers\etc\hosts | Select-String -NotMatch "^#"
Entries in the HOSTS file indicate IP addresses used by AD FS servers to locate services and hosts.
Q5 What additional routes do the AD FS servers use?
Use the following line of Windows PowerShell to find any additional routes that the current AD FS server(s) use:
Get-NetRoute
Q6 What are the AD FS Certificates in use?
An AD FS Farm uses three certificates:
- The Service Communications certificate
- The Token-signing certificate
- The Token-decrypting certificate
To get a handle on all three, use the following Windows PowerShell scripts:
$ADFSCerts = Get-AdfsCertificate
$CertArray = @()
ForEach ($Cert in $ADFSCerts) {
$CertObject = [PSCustomObject]@{
CertificateType = $Cert.CertificateType
Subject = $Cert.Certificate.Subject
NotAfter = $Cert.Certificate.NotAfter
}
$CertArray += $CertObject
}
$CertArray
This outputs a table with the three AD FS-specific TLS certificates, together with their subjects and their expiry dates.
Q7 What are the current certificates in use?
We also need to know which other TLS certificates are available on the current AD FS servers. As we’re only interested in TLS certificates for the local machine, we can use the following lines of PowerShell:
Set-Location Cert:\LocalMachine\My
Get-ChildItem | Format-Table FriendlyName, Subject, NotAfter
This outputs a table with TLS certificates, together with their subjects and their expiry dates.
Implement the new AD FS server
Implementing the new AD FS server is easy. Simply create a new (virtual) machine with your favorite supported Windows Server version on it.
A1 Domain-join the AD FS server
As stated for Q2, all AD FS servers in the same AD FS farm need to be joined to the same Active Directory domain. With the answer of Q2, join the AD FS server to the domain using the following two lines of Windows PowerShell:
Add-Computer -DomainName "domain.tld"
Restart-Computer
Note:
You may have to configure a fixed IP address and/or DNS server address on the Windows Server installation before you’re able to join the Active Directory domain.
A2 Take care of the basics
Although domain-joining a Windows Server installation to Active Directory takes care of most things, double check that the Windows Server installation is activated, up to date with Windows Updates, protected with an anti-malware solution and configured with the right time and time zone before you continue with the next steps.
A3 Implement the required name resolution method
The new AD FS server needs to be able to resolve the hostname for AD FS server(s) and the federation metadata URLs. When the answer to Q4 pops up with HOSTS file entries, then recreate these on the new AD FS server as well.
A4 Configure the right networking settings
As the new AD FS server needs to be able to communicate to the other AD FS server(s) or the SQL Server (cluster), the Web Application Proxy servers, the federation metadata URLs for its relying parties and any other services, systems and/or applications on your network, Take care of:
- The necessary routes,
- Firewall rules and
- Proxy exceptions.
The required information is in the answers to questions Q3 and Q5.
A5 Install the certificate(s)
Install the same TLS certificate(s) that is/are used by the current AD FS server(s) on the new AD FS server, too. Export these certificates from the current Web Application Proxy server(s) and/or AD FS server(s) with their private keys, or download the certificate(s) again from your certification authority. The required information is in the answers to questions Q6 and Q7.
A6 Install the AD FS Server feature
Run the following lines of Windows PowerShell to install the AD FS Server feature:
Install-WindowsFeature ADFS-Federation -IncludeManagementTools
A7 Configure the AD FS Server
Run the following lines of Windows PowerShell to configure the AD FS server:
Note:
This example uses a user account as AD FS service account and adds the server to the AD FS farm, based on the Primary Server in a WID setup. Here is an example that uses SQL Server and a group Managed Service Account.
$Thumb = (Get-ChildItem -path cert:\LocalMachine\My | Where-Object {$_.Subject –match "sts.domain.tld"}).Thumbprint
$ServiceCred = Get-Credential
Add-AdfsFarmNode -CertificateThumbprint $thumb -ServiceAccountCredential $ServiceCred –PrimaryComputerName PrimaryServerDNSName
Restart-Computer
Alternatively:
As an alternative to actions A5 through A7, you can also use the Azure Active Directory Connect Configuration wizard to install the certificate, install the AD FS Server feature and add the AD FS server to the AD FS Farm. This method requires traffic over TCP port 5985 from the Azure AD Connect server(s) to the AD FS server(s).
A8 (Optionally) Configure Azure AD Connect Health
To monitor the health of the new AD FS server, install the Azure AD Connect Health agent for AD FS onto it and configure it. Through the Azure AD Connect Health dashboard that is part of the Azure Portal, you can then see the activity and health for the AD FS server when you put it in use.
A9 Harden the AD FS server
Of course, you want to apply hardening before you put the AD FS server in use. Refer to these earlier blogposts for my hardening recommended practices:
- HOWTO: Disable Unnecessary Services and Scheduled Tasks on AD FS Servers
- HOWTO: Disable weak protocols, cipher suites and hashing algorithms on Web Application Proxies, AD FS Servers and Windows Servers running Azure AD Connect
Put the AD FS server in use
The AD FS server is now ready for use.
A10 Testing the Functionality of the new AD FS server
However, before you put a new AD FS server in use, check that you can sign in to the applications, services and/or systems that are represented by the relying party trusts, like you would normally. Check this by pointing an internal device through its HOSTS file to IP address of the new AD FS server for the DNS name of the AD FS Farm
This technical and functional test verifies that the AD FS Server is functioning properly to meet your organization’s needs.
A11 Add the AD FS Server to the pool, or switch it
Now you can add the AD FS server to the back-end pool of the load balancer, if you want to add it to an already existing load-balanced of AD FS servers.
If you want to switch around an old AD FS server with a new AD FS server, instead, switch the DNS record from the old AD FS server to the new AD FS server.
If there are Web Application Proxies connected to the AD FS farm, switch these around too, be either switching the entry for the AD FS farm in the Web Application Proxy’s HOSTS file or changing the IP address for the AD FS farm in the DNS zone for the perimeter network.
A12 Monitor the new AD FS Server’s traffic and load
As you put the AD FS server in use, monitor its traffic using Azure AD Connect Health to see if your load balancer is indeed flowing authentication requests to it. Monitor the CPU and memory on the new AD FS server to assure the load is as expected.
Decommissioning the old AD FS Server(s)
Now that the new AD FS server is running as it should, we can decommission any AD Fs server that is faulty, redundant, running a previous version of Windows Server or you want to get rid of for some other reason.
Perform these actions to decommission an AD FS Server:
A13 Remove the AD FS Server from the pool
Remove the AD FS server as an endpoint from the back-end pool of the load balancer. Monitor traffic to the AD FS server to make sure no more authentication requests are sent to the host.
A14 Change the AD FS Primary server
Chances are, the AD FS server that you want to remove is the primary AD FS server for an AD FS farm running the Windows Internal Database (WID) as the method to host the AD FS configuration database. This is part of the answer to Q1.
Note:
You don’t have to perform this action for an AD FS Farm that uses SQL Server as the method to host the AD FS configuration database.
On the new AD FS server or one of the other remaining AD FS servers, you’ll need to run the following line of Windows PowerShell to make the AD FS server the primary server:
Set-AdfsSyncProperties -Role PrimaryComputer
Then, on the other AD FS servers, make sure they all point to the new primary AD FS server with the following line of Windows PowerShell:
Set-AdfsSyncProperties -Role SecondaryComputer -PrimaryComputerName NewADFSPrimaryServer.domain.tld
You can check the role for an AD FS server in a WID-based AD FS Farm using the following line of Windows PowerShell:
Get-AdfsSyncProperties
A15 Remove the AD FS server role
Uninstalling the AD FS Server role from an AD FS server, removes it from the AD FS farm. Perform the following line of Windows PowerShell to do so:
Uninstall-WindowsFeature ADFS-Federation
A16 Check proper removal of the decommissioned AD FS Server(s)
It is important to check that the decommissioned AD FS server are properly removed from the AD FS Farm. To gather this information, you need to run the following line of Windows PowerShell from the AD FS server that is the primary server in case of WID, or any AD FS server when Microsoft SQL Server is used to host the AD FS configuration database:
(Get-AdfsFarmInformation).FarmNodes | Format-Table
If the AD FS server you decommissioned is still there, you’ll have to remove it using Remove-AdfsFarmNode. The way you use this Windows PowerShell cmdlet is subject to the AD FS service account used.
A17 Remove infrastructure services
As you now have decommissioned the AD FS server, make sure to also remove it from monitoring, logging, backup, anti-malware and other infrastructure management services your organization leverages.
A18 Remove the server from the domain
After you have decoupled the AD FS server from the infrastructure services supporting it, remove it from the Active Directory domain using the following line of Windows PowerShell and specifying an Active Directory account that has sufficient (delegated)permissions to remove a computer from Active Directory:
$Cred = Get-Credential
Remove-Computer –UnjoinDomaincredential $cred -PassThru -Verbose -Restart
Afterward, remove the computer account for the server from Active Directory and DNS.
After you have decommissioned an AD FS server
After you have decommissioned an AD FS server, answer this question:
Q8 Is this the last AD FS Server running this version?
An AD FS farm operates using a specific Farm Behavioral Level (FBL), depending on the oldest Windows Server version used by AD FS servers in the AD FS farm. When the last AD FS server running a previous version of Windows Server is removed from the AD FS farm, the FBL can be upgraded with action A19.
After you decommission an AD FS server, answer these questions:
A19 Upgrade the AD FS Farm Behavioral Level (FBL)
When all AD FS servers running a previous version of Windows Server have been decommissioned, you can opt to upgrade the AD FS Farm Behavioral Level (FBL). There are some good reasons to upgrade the FBL if you’re coming from Windows Server 2012 R2 to Windows Server 2016:
- Built-in Azure Multi-Factor Authentication AD FS Adapter and Azure MFA as primary authentication method
- Device compliance status for AD FS claims issuance rules and Azure AD Connect device write-back for Azure AD-joined devices
- Sign-in with Windows Hello for Business
- Oauth 2, Open ID Connect and SCIM support
- SAML 2.0 inCommon and eGov support
- Access Control Policies manageability
- Sign-in with accounts from non-Active Directory LDAPv3 directories
- Sign-in with accounts from Active Directory forests to which an Active Directory two-way trust is not configured
- Sign-in with accounts from Active Directory Lightweight Directory Services (AD LDS)
- Per-Relying Party Trust branding
- Improved auditing (more streamlined, less verbose)
- Send password expiry claims to RPTs to notify users when using Office 365
Use the following line of Windows PowerShell to do so:
Invoke-ADFSFarmBehaviorLevelRaise
A20 Convert claims rules to Authentication Policies
A common way to define multi-factor authentication for extranet access on an AD FS Farm running Windows Server 2012 R2 is to define it using claims issuing rules and/or through Custom settings per Relying Party Trust. In AD FS on Windows Server 2016, and up, these settings are managed through Authentication Policies. This is a good time to convert to Authentication Policies. If need be, you can create your own additional Authentication Policies to provide custom authentication settings. By applying an Authentication Policy to a Relying Party Trust, you apply the authentication settings.
A21 Testing the Functionality of the AD FS Farm
The FBL upgrade is an important upgrade to get these new features, but there is also a risk: As many relying parties query your AD FS Farm’s federation metadata and endpoints, their infrastructure might decide that your infrastructure is now capable of OpenID Connect, for instance, and try to communicate using it, while your Relying Party Trusts (RPTs) might not support it in their settings yet.
Check that you can sign in to the applications, services and/or systems that are represented by the relying party trusts, like you would normally.
Concluding
The above approach is our real-world tested approach to transitioning AD FS Servers, based on projects with our customers.
Enjoy!
What i am missing is upgrade the upgrade WAP config to the latest level Set-WebApplicationProxyConfiguration -UpgradeConfigurationVersion
Oops didnt see the WAP article 🙂 its described there. Thanks for the articles!
Can you perhaps provide some details if Enable-PSRemoting isn't done before installing ADFS, are there any workarounds to do so later:
https://blog.rmilne.ca/2017/05/26/psremoting-for-office-365-ad-fs-configuration/ ?
Yes,
For non-domain-joined Web Application Proxy Servers, you'll need to perform some additional actions to manage them with Azure AD Connect.
These steps can also be followed for AD FS servers: