ADFS v3 (2012R2) naar ADFS v4 (2016) Migratie – Deel 1/2

Dit is misschien niet meer de meest up-to-date post maar recentelijk ben ik sinds een tijdje weer bezig geweest met een ADFS migratie. Omdat ik deze stappen gedocumenteerd heb was het een kleine moeite om van deze migratie een post te maken en ik kan me voorstellen dat deze post toch nog voor veel mensen enige waarde kan hebben. Server 2012R2 met ADFS v30 komt toch nog geregeld voor en niet iedereen wil meteen upgraden naar Server 2019 met ADFS v5. ADFS v4 kent namelijk t.o.v. v3 heel erg veel verbeteringen. De hoofdrede om te upgraden was om te kunnen integreren met Azure MFA. Deze feature zal in veel gevallen de hoofdreden zijn om te upgraden. Sta je zelf voor een ADFS upgrade van v3 naar v4 dan is het aan te raden om deze post te lezen zodat je geen zaken vergeet en misschien meer inzicht krijgt in ADFS als systeem. Zelfs als je wilt upgraden naar ADFS v5 zijn veel van de stappen identiek. Doe er je voordeel mee.

ADFS, ofwel “Active Directory Federation Services” is een systeem van Microsoft welke de gebruiker kan voorzien van een SSO (Single Sign-On) ervaring met systemen zowel binnen als buiten het interne netwerk. Een SSO sessie kan er als volgt uitzien:

• De gebruiker logt in op zijn eigen PC met zijn eigen gebruikersnaam en wachtwoord en authentiseert zichzelf bij de AD server van zijn eigen bedrijf.
• De gebruiker heeft gegevens nodig v.a. het extranet van een ander bedrijf. De gebruiker gaat naar het extranet. Normaliter zou men om een gebruikersnaam en wachtwoord vragen. Maar aangezien de ADFS server van het andere bedrijf en de ADFS server van het eigen bedrijf een koppeling (trust relationship) hebben met elkaar verzoekt het extranet eerst een “ADFS token” van de ADFS server van het eigen bedrijf. Deze token verteld de ADFS server feitelijk dat de gebruiker die aanmeld geauthentiseerd is om dit te doen. Deze flow is als volgt:
• De cliënt van de gebruiker verzoekt een token bij de eigen ADFS server.
• De ADFS server vraagt aan de AD server of deze gebruiker toegang mag hebben op de resource.
• Bij authenticatie ontvangt de gebruiker van de ADFS server een signed ADFS token met diverse claims.
• De gebruiker verstuurd het ADFS token naar de service (extranet) waar ook de ADFS Web Agent draait. Deze agent neemt het token in behandeling en verstuurd het token weer naar de eigen ADFS server. Bij ontvangst zal de ADFS server (ander bedrijf) de claims in het token verifiëren. Bij akkoord zal de ADFS server tegen de service vertellen dat de gebruiker toegang mag hebben heeft.

Als het bovenstaande gebeurt zeer snel (binnen 1 of enkele secondes). Het voordeel van deze SSO ervaring is dat de gebruiker de resource kan gebruiken zonder dat deze actief hoeft in te loggen.

ADFS gebruikt een “claims-based” authorization model. Dit betekend dat het ADFS token diverse claims bevat en dat op basis van die claims de gebruiker geauthentiseerd wordt. Een “claim” is een AD property zoals een UPN, E-mailadres of groep lidmaatschap. ADFS tokens worden dus geautoriseerd en getekend door een AD server. Omdat ADFS op basis van claims werkt is het dus niet nodig dat de gebruiker fysiek als “user” aanwezig is in het AD van de externe partij.

ADFS kan communiceren en dus functioneren met andere identity protocollen zoals WS-Federation en WS-Trust. SAML 2.0 (en hoger) is echter het default protocol.
 
ADFS kan niet gebruikt worden voor het verkrijgen van toegang op o.a.:

• File Shares
• AD resources
• Exchange on-premise (wel ExchangeOnline / Office365)
• RDP connecties
• Authenticatie tegen diensten die niet overweg kunnen met claims-based authentication

Om ADFS wat beter te begrijpen is het zaak om eerst de verschillende componenten te begrijpen:

Active Directory
Active Directory is de globale identity database waar alle identity informatie opgeslagen is. Microsoft refereert ook wel naar AD als “Identity Provider”.

Federation Server
De federation server wordt meestal de “ADFS” server genoemd. De federation server routeert aanvragen van externe gebruikers en hosts de “security token service” welke tokens genereerd op basis van claims nadat de gebruiker bij AD geauthentiseerd is. Microsoft noemt de federation server ook wel de “Claims Provider”.

Federation Proxy Server
De federation proxy server is meestal de hop tussen het externe netwerk (externe cliënt) en het interne netwerk (federation server) en staat meestal in de DMZ zone van een bedrijf. Een externe cliënt verbindt met de federation proxy server met het verzoek om een “ADFS token”. De federation proxy server routeert het verzoek door naar de interne federation server.

ADFS Web Application Server
De ADFS web server is het onderdeel welke de claims-aware of het Windows token-based role heeft. Deze agent maakt het mogelijk om ADFS tokens te ontvangen van externe personen en om op basis hiervan toegang te verlenen aan externe gebruikers. De ADFS web server wordt vrijwel altijd gehost op de federation proxy server. Dit noemen we dan de “Web Application Proxy” ofwel de “WAP” server.

Identity Provider
Binnen ADFS is de “Identity Provider” de site waar de gebruiker zich authentiseert. De identity provider is de site waar het ADFS token gegenereerd wordt. Dit is dus feitelijk altijd “je eigen kant” (gezien vanuit je eigen interne netwerk). We noemen dit ook wel de “Service Provider”.

Resource Provider
Binnen ADFS is de resource provider de site welke de resource host en waar toegang tot verkregen moet worden. Dit is dus feitelijk altijd “de andere kant” (gezien vanuit je eigen interne netwerk). We noemen dit ook wel de “Relying Party”.

Certificates
De ADFS topologie maakt gebruik van verschillende certificaten. Deze zijn:

• SSL Certificaat / Service Communication Certificate– Dit certificaat is het SSL certificaat. Dit certificaat wordt gebruikt om een veilige versleutelde sessie op te zetten tussen de cliënt en de federation proxy en voor de veilige verbinding tussen de federation proxy en de federation server. Omdat dit certificaat en de hele chain vertrouwd moet zijn door de cliënt is het logisch om hier een public SSL certificaat voor te gebruiken. Let erop dan de subject name van het certificaat overeen moet komen met de namen die gebruikt worden in de ADFS configuratie. Stel voor dat de federation endpoint URL is: https://adfsresource.treyresearch.net/adfs/ls/ dan is de subjectnaam die in het certificaat aanwezig moet zijn: “adfsresource.treyresearch.net”. Dit certificaat moet aanwezig zijn binnen op alle federation servers en federation proxy servers. Er moet dus toegang zijn tot de public en de private key met de mogelijkheid om deze te exporteren.
• Token Signing Certificaat – Dit certificaat wordt gebruikt voor het signen/ondertekenen van het ADFS (SAML) token. Dit certificaat kan een public X509 of een self-signed X509 certificaat zijn. Self-signed certificaten zijn prima in een lab maar worden niet geadviseerd in een productieomgeving. Daarnaast zal van het certificaat een zogenaamd “verification certificate” gemaakt worden. Dit is hetzelfde certificaat maar dan zonder de public key. Alle trusted parties moeten over dit certificaat beschikken om er zeker van te zijn dat het token authentiek is en dat de integriteit in tact is. Default vervalt dit certificaat binnen een jaar en kun je auto-enrollment inschakelen zodat dit certificaat automatisch vernieuwd wordt. Het nieuwe certificaat wordt het primaire certificaat voor het signen van de tokens 15 dagen voordat het oude certificaat gaat vervallen. Het oude certificaat wordt dan een secondair certificaat. De public key blijft gepubliceerd maar het certificaat wordt niet meer gebruikt voor signing.
• Token Decrypting Certificaat – Dit certificaat wordt niet in elke setup gebruikt. Het token decrypting certificaat wordt gebruikt als een resource provider een versleuteld (niet signed) certificaat wilt sturen. De resource provider zal een export van dit certificaat ontvangen met de public key (dus zonder private key) om het verkeer te versleutelen. Wij kunnen het verkeer ontsleutelen omdat wij beschikken over de private key. Ook het token decrypting certificaat kan een self-signed certificaat zijn maar aangeraden wordt om een public certificaat te gebruiken.
• Certificaten van de relying party – Uiteraard moeten wij ook beschikken over de certificaten (public keys) van de relying party welke wij nog hebben om verkeer te versleutelen of om signed tokens te verifieren. Deze zijn aanwezig in de Signature en Encryption tabs van de trust binnen ADFS.

Dus in het kort:

• SSL Certificaat / Service Communication Certificate – Voor het versleutelen van de SSL tunnel tussen de cliënt en de ADFS proxy en tussen de ADFS proxy en de ADFS federation server.
• Token Signing Certificate – Voor het signen van de ADFS (SAML) tokens (de relying party heeft hiervan een export met alleen de public key)
• Token Decrypting Certificate – Voor het versleutelen/encrypten van de ADFS (SAML) tokens (de relying party heeft hiervan een export met alleen de public key)
• Certificate aanwezig in “Signature Tab” van trust – Het verificatie certificaat (public key) van de vertrouwende server (relying party) welke wij kunnen gebruiken om de signing van hun ADFS tokens te controleren.
• Certificate aanwezig in “Encryption Tab” van trust – Het encryptie certificaat (public key) van de vertrouwende server (relying party) welke wij kunnen gebruiken om de versleutelen van verkeer naar de relying party toe.

Met bovenstaande achtergrond kunnen we met een gerust hart starten met de migratie!

ADFS Migratiestappen

ADFS v4 (2016) biedt een aantal nieuwe zaken zoals b.v.:

• Inloggen middels Azure MFA
• Inloggen zonder wachtwoord van InTune trusted devices (device is 2e factor)
• Inloggen via Microsoft Passport
• Inloggen via Windows Hello for Business
• Betere sign-in ervaring
• Betere management features
• Modern Authentication
• Templates t.o.v. ingewikkelde claim rule language

ADFS v5 biedt echter nog een paar interessante features zoals het gebruiken van een externe authenticatieprovider als 1e factor. Maar, voor we uberhaupt gaan nadenken over een migratie naar ADFS v5 gaan we upgraden naar ADFS v4.

Laten we eerst het huidige landschap in kaart brengen:

• 2x Federation Server (v3 – 2012R2)
• 2x Web Application Proxy (2012R2) in DMZ
• 1 Active Directory / 1 Forest
• 1x Netscaler Load Balancer voor de federation proxy servers
• 1x Load Balancer voor de federation servers
• 1x AAD Connect tool op federation server

De gehele setup blijft identiek met uitzondering van de 2 federation servers en web application servers welke geüpdate gaan worden.

De volgende zaken zullen tijdens de upgrade aan bod komen:

• Upgrade van de federation servers
• Upgrade van de WAP servers
• Instellen integratie met Azure MFA

Als we deze stappen verder uitwerken komen we op het volgende migratieplan:

• Installeren 2 nieuwe AD member servers (2016) met eigen static IP en naam
• Zorg ervoor dat de firewall regels die van toepassing zijn op de oude servers gedupliceerd worden naar de nieuwe servers
• Installeren 2 nieuwe stand-alone servers (2016) in DMZ met eigen static IP en naam
• Snapshot maken huidige ADFS machines (federation & proxy)
• Zorg ervoor dat het AD schema up-to-date (2016) is
• Maak backup van de ADFS database, relay parties en certificaten. Installeer de backup tool
• Draai de backup tool
• Installeer het ADFS certificaat op de nieuwe servers (voor selectie in de volgende stap)
• Installeer ADFS + Management Tools + connect naar de huidige farm (v3) tijdens de setup
• Promote 1 nieuwe 2016 federation server als primary in de farm
• Update de overige federation servers zodat ze weten welke primary is
• Controleer op elke server of ze primary of secondary zijn. Dit moet correct zijn
• Installeer de WAP rollen op de proxy servers
• Verwijder de oude WAP servers uit het cluster
• Verwijder de oude federation servers (v3) uit de farm
• Upgrade Farm Behavior Level (FBL) naar ‘2016’
• Controleer of het FBL correct is
• Upgrade de WebApplicationProxyConfiguration versie naar ‘2016’
• Controleer het cluster
• Update de WAP ConfigurationVersion
• Configure ADFS 2016 voor Azure MFA support
• Overige configuratie en best practices

De Migratie – Backups

Nu zijn we klaar om de migratie uit te voeren. Ik ga ervan uit dat je de eerste stappen doorlopen hebt. Je hebt snapshots (backups) van je federation servers en proxy servers, je hebt al nieuwe servers met hun eigen naam en ip adres geïnstalleerd en de firewall poorten zijn geregeld. Ook ga ik ervan uit dat het AD schema (forest en domain) up-to-date (at least 2016) is:

adprep /forestprep
adprep /domainprep

Voordat we beginnen maken we een back-up van de ADFS database, de relay parties en de certificaten. Te beginnen met de certificaten. Zorg dat je de beschikking hebt over de volgende volledige (PFX) certificaten:

• Service Communication Certificate
• Token Signing Certificate
• SSL Certification

Het volgende commando laat zien welke certificaten in gebruik zijn:

Get-ADFSCertificate | Out-File “.\certificates.txt”

De certificaten kunnen we exporteren we met Powershell. Uiteraard moet het certificaat wel als “exporteerbaar” geïmporteerd zijn. Om dit via Powerhsell te doen moet je beschikken over de hash van het certificaat:

cd cert:\
 
cd LocalMachine
 
cd My
 
#Export SSL Certificate:
Export-PfxCertificate -Cert .\LONGSTRINGOFHEX -FilePath 'C:\temp\ADFS-SSL.pfx' -Password (ConvertTo-SecureString -String 'password' -AsPlainText -Force)

Bovenstaande voer je uit voor alle certificaten.

Het volgende dat we moeten weten is welk type database gebruikt wordt voor de huidige ADFS omgeving. Dit kan een SQL database zijn of een interne WID database. Om dit te achterhalen gebruik je het commando:

Get-ADFSProperties

Vervolgens bekijk je de “ArtifactDbConnection” waarde. Als hier een databaseserver gedefinieerd staat dan gebruik je een SQL database. Als dit niet zo is dan wordt een interne database gebruikt.

Om de volledige connectionstring te achterhalen voer je de volgende commando’s uit:

$adfs = gwmi -Namespace root/ADFS -Class SecurityTokenService
 
$adfs.ConfigurationDatabaseConnectionString

In ons voorbeeld maken we gebruik van een SQL database. Zorg ervoor dat de database beheerder een volledige backup maakt.

Nu gaan we de ADFS properties naar een bestand kopieren (als backup):

Get-ADFSProperties | Out-File “c:\temp\properties.txt”

Kopieer de config file “Microsoft.IdentityServer.Servicehost.exe.config” vanuit “%programfiles%\Active Directory Federation Services 2.0\” of vanuit “c:\windows\ADFS”.

De volgende stap is om de gegevens van het ADFS service account op te slaan.

Nu gaan we alle gekoppelde endpoints opslaan:

Get-ADFSEndpoint | Out-File “c:\temp\endpoints.txt”

En we exporteren alle custom claims:

Get-ADFSClaimDescription | Out-File “c:\temp\claimtypes.txt”

Nu gaan we alle claims provider trusts en relying party trusts exporteren. MS heeft hiervoor een PS scripts gemaakt (export-federationconfiguration.ps1) welke te vinden is in “C:\Windows\ADFS” of op de installatie CD van Windows Server 2012 in “media/server_support/adfs”.

Het script draaien we als volgt:

cd c:\windows\ADFS
 
.\export-federationconfiguration.ps1 -path "c:\temp\exportadfs\"

Als het script niet werkt gebruik dan de nieuwe versie van:
https://gist.github.com/jeffpatton1971/12f9e00dbca27abf8b59

Nu we alle handmatige backups gemaakt hebben gaan we een automatische backup maken met de ADFS Rapid Restore Tool (better safe than sorry). Deze tool backupt de volgende:

• AD FS configuratie database (SQL of WID)
• Configuratie bestand (in de AD FS folder)
• De automatisch gegenereerde token signing en decrypting certificaten incl. indien mogelijk de private keys
• Het SSL certificaat en andere extern verkregen certificaten (b.v. token signing, token decryption en service communication certificaten) incl. indien mogelijk de privaqte keys
• Een lijst met custom authentication providers, attribute stores, en local claims provider trusts

Dit gaat als volgt:
1. Download de tool: https://www.microsoft.com/en-us/download/details.aspx?id=56569

2. Installeer de tool (bij een interne WID database installeer je de tool op de primaire ADFS server – “Get-AdfsSyncProperties”):

3. Importeer de Powershell module

import-module 'C:\Program Files (x86)\ADFS Rapid Recreation Tool\ADFSRapidRecreationTool.dll'

4. Draai het volgende commando als domain admin om de hele ADFS configuratie te exporteren incl. DKM container:

Backup-ADFS -StorageType "FileSystem" -StoragePath "C:\temp\ADFS-RD-Export\" -EncryptionPassword "password" -BackupComment "Clean Install of ADFS (FS)" -BackupDKM

*Er zijn vele andere commando varianten mogelijk (b.v. door het ADFS service account te gebruiken i.p.v. een domain admin account). De verschillende mogelijkheden zijn hier te vinden: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/ad-fs-rapid-restore-tool

Om later te restoren (incl. AD DKM container) zou je dit commando kunnen gebruiken:

Restore-ADFS -StorageType "FileSystem" -StoragePath " C:\temp\ADFS-RD-Export\" -DecryptionPassword "password" -RestoreDKM

Nu we een backup hebben van alle ADFS data zorg je ervoor dat je al deze bestanden opslaat op een veilige (niet ADFS server) locatie. We hebben nu alle data geborgd en kunnen doorgaan met de volgende stap.

ADFS Migratie – De migratie

Als eerste gaan we op de nieuwe servers de geëxporteerde certificaten opnieuw installeren. Importeer deze als niet-exporteerbaar:

Verwijder na een succesvolle import de certificaten van de server.
Nu gaan we ADFS installeren op de nieuwe 2016 servers. Dit kunnen we doen met het commando:

Install-windowsfeature adfs-federation -IncludeManagementTools

Of we installeren via de Service Manager:

Na de installatie starten we de configuratie:

Uiteraard gaan we de server toevoegen aan de huidige farm:

Wanneer je een integrated WID database gebruikt vul je de primary federation server in en wanneer je een SQL database server gebruikt vul je de database server in. Als een niet-default (AdfsConfiguration) database instance gebruikt wordt geef je ook de gebruikte instance op:

Vervolgens selecteer je het ADFS SSL certificaat en geef je de credentials op van het gebruikte ADFS service account:

Kijk tenslotte de settings na en bij akkoord klik je op “Next” om de prerequisite check te starten:

Als de prerequisite controle succesvol is klik je op “Configure” om de ADFS configuratie te starten.

Na configuratie zal de ADFS server gereboot moeten worden.

Na een reboot kun je ADFS starten en is eenzelfde configuratie aanwezig als op de “oude” 2012 ADFS servers. Nu gaan we bovenstaande ADFS installatie ook uitvoeren voor de 2e Windows 2016 server.

Nu de 2016 servers geinstalleerd zijn gaan we 1 van deze servers als primary promoten. Dit doen we via het Powershell commando:

Set-AdfsSyncProperties -Role PrimaryComputer

Alle overige servers moeten we updaten zodat ze weten welke primary is (als een WID internal database gebruikt wordt. Met een SQL database is iedere node een primary node):

Set-AdfsSyncProperties -Role SecondaryComputer -PrimaryComputerName %primary-adfs-server%

Om te zien of de ADFS node een primary of secondary node is gebruik je:

Get-AdfsSyncProperties

Om alle (2016) nodes in de farm te zien gebruik je (oude 2012 nodes worden niet getoond):

Get-AdfsFarmInformation

De oude nodes verwijderen we op een later moment in deel 2 van deze post. Op dit moment hebben we de feitelijke ADFS migratie voltooid. Echter zijn we nog verre van klaar. Alle overige stappen zoals het upgraden van de WAP servers, het Forest Behaviour Level en de integratie met Azure MFA volgen in het 2e deel van deze post.

Handige post? Don’t be shy en geef me een leuk berichtje, like of deel mijn post op je social media kanalen of op je website. Much appreciated!