AD FS: SSL-Zertifikat erneuern und austauschen (PowerShell)

AD FS stellt seine TLS-Endpunkte über HTTP.sys bereit, nicht über eine IIS-Website. Aktuelle AD-FS-Versionen verwalten diese Bindungen mit eigenen PowerShell-Cmdlets. Das TLS-Zertifikat ist außerdem unabhängig von den Tokensignatur- und Tokenentschlüsselungszertifikaten - wer das eine austauscht, muss die anderen nicht anfassen.

VoraussetzungenCopy Anchor Link

• Besorgen Sie eine PFX-Datei mit privatem Schlüssel, der EKU Serverauthentifizierung und dem Namen des Verbunddienstes im SAN. Nutzt die Farm den alternativen TLS-Clientbindungsmodus, muss auch certauth.<Verbunddienstname> enthalten sein.
• Notieren Sie Get-AdfsProperties, Get-AdfsFarmInformation, Get-AdfsSslCertificate, den alten Fingerabdruck und die WAP-Server.
• Sie brauchen lokale Administratorrechte auf jedem Verbundserver und jedem Web Application Proxy (WAP).
• Sichern Sie die AD-FS-Konfiguration und planen Sie ein rollierendes Wartungsfenster. Lassen Sie immer mindestens einen funktionierenden Knoten im Load-Balancer-Pool.

Die Zertifikatsrollen in AD FSCopy Anchor Link

Das TLS/SSL-Zertifikat schützt die HTTPS-Endpunkte und wird mit Set-AdfsSslCertificate bzw. im alternativen Clientbindungsmodus mit Set-AdfsAlternateTlsClientBinding geändert. Das in der AD-FS-Verwaltung angezeigte Dienstkommunikationszertifikat ist Metadaten für die Dienstkommunikation und nicht die HTTP.sys-Bindung. Tokensignatur- und Tokenentschlüsselungszertifikate schützen Token und erfordern einen abgestimmten Wechsel mit den Verbundpartnern; sie sollten bei einer normalen TLS-Erneuerung nicht geändert werden.

AD FS bindet üblicherweise den Verbunddienstnamen auf Port 443, localhost auf 443, die Namen der Geräteregistrierung und einen Endpunkt für die Clientzertifikat-Authentifizierung. Im Standardbindungsmodus nutzt diese Authentifizierung einen eigenen Port wie 49443, im alternativen Modus certauth.<Name> auf 443 mit SNI.

Zertifikat Schritt für Schritt austauschenCopy Anchor Link

1. Importieren Sie die PFX-Datei auf jedem AD-FS- und WAP-Server in Cert:\LocalMachine\My:

   Copy Text

   $password = Read-Host "PFX password" -AsSecureString
   $cert = Import-PfxCertificate -FilePath C:\secure\adfs.pfx `
     -CertStoreLocation Cert:\LocalMachine\My -Password $password
   $thumbprint = $cert.Thumbprint
   Get-Item "Cert:\LocalMachine\My\$thumbprint" |
     Format-List Subject,DnsNameList,EnhancedKeyUsageList,HasPrivateKey,NotAfter

2. Bestimmen Sie die Farm-Eigenschaften, bevor Sie ein Cmdlet wählen:

   Copy Text

   Get-AdfsSslCertificate                       # aktuelle Bindungen
   Get-AdfsSyncProperties | Format-List Role    # PrimaryComputer = primärer Server
   Get-AdfsFarmInformation | Format-List CurrentFarmBehavior

   • Bindungsmodus: Eine Bindung für certauth.<Verbunddienstname> auf Port 443 bedeutet alternativen TLS-Clientbindungsmodus (Schritt 4); eine Bindung auf Port 49443 den Standardmodus (Schritt 3).
   • Farmverhaltensebene: 3 ist Windows Server 2016, 4 Windows Server 2019 und neuer. Die farmweite Aktualisierung in Schritt 3 braucht mindestens 3 und läuft auf dem primären Server.

3. Auf einem primären Verbundserver ab Windows Server 2016 mit Farmverhaltensebene 2016 aktualisieren Sie den Standardbindungsmodus einmal für die ganze Farm:

   Copy Text

   Set-AdfsSslCertificate -Thumbprint $thumbprint

   Das Cmdlet arbeitet über mehrere Knoten und nutzt PowerShell-Remoting; TCP 5985 muss vom primären Server zu den anderen Knoten erreichbar sein. Unter Windows Server 2012 R2 führen Sie Set-AdfsSslCertificate stattdessen auf jedem Verbundserver aus.

4. Nutzt die Farm den alternativen TLS-Clientbindungsmodus, verwenden Sie das passende Farm-Cmdlet statt des Befehls für den Standardmodus:

   Copy Text

   Set-AdfsAlternateTlsClientBinding -Thumbprint $thumbprint

5. Nach der AD-FS-Farm auf jedem WAP-Server ausführen:

   Copy Text

   Set-WebApplicationProxySslCertificate -Thumbprint $thumbprint

   Verhindert eine bereits abgelaufene Vertrauensstellung diesen Schritt, beschreibt Microsoft den Neuaufbau mit Install-WebApplicationProxy und dem Verbunddienstnamen.

6. Zugriff auf den privaten Schlüssel prüfen. Ab Server 2016 geben die TLS-Cmdlets dem Dienstprinzipal adfssrv Lesezugriff auf den Schlüssel; eine zusätzliche ACL für das konfigurierte Domänendienstkonto ist für die TLS-Bindung normalerweise nicht nötig. Bei älteren Versionen, eigenen Zertifikatsrollen oder nach einem manuellen Import prüfen Sie, ob das laufende Konto den Schlüssel lesen kann. So finden Sie es:

   Copy Text

   Get-CimInstance Win32_Service -Filter "Name='adfssrv'" |
     Select-Object Name,StartName,State

   Erteilen Sie in certlm.msc über Alle Aufgaben > Private Schlüssel verwalten nur Lesen, wenn Version und Rolle es erfordern. Ein Zertifikat kann gebunden erscheinen und trotzdem scheitern, wenn AD FS nicht auf den privaten Schlüssel zugreifen kann.

7. Prüfen Sie auf jedem AD-FS-Server, ob jede Bindung das neue Zertifikat trägt:

   Copy Text

   netsh http show sslcert

   Jeder AD-FS-Eintrag sollte den neuen Fingerabdruck als Certificate Hash zeigen. Dann ist kein Neustart nötig. Zeigt ein Knoten noch den alten, nehmen Sie ihn aus dem Load Balancer und starten nur dort AD FS neu:

   Copy Text

   Restart-Service adfssrv

   Starten Sie nie die ganze Farm gleichzeitig neu.

HTTP.sys und ältere AnleitungenCopy Anchor Link

Nutzen Sie HTTP.sys-Befehle bei aktuellen AD-FS-Versionen zum Prüfen, nicht zum routinemäßigen Austauschen der Bindungen:

netsh http show sslcert
Get-AdfsSslCertificate

Ältere AD-FS-Anleitungen lassen netsh http-Bindungen mit einer AppID löschen und neu anlegen. Das direkte Bearbeiten ist nur für die AD-FS-Version und den Bindungsmodus richtig, deren Microsoft-Anleitung es ausdrücklich vorsieht. In modernen Farmen übersieht ein Umgehen von Set-AdfsSslCertificate leicht localhost-, Geräteregistrierungs-, Clientauthentifizierungs-, SNI- oder andere Farmbindungen, und die Änderung erreicht die anderen Knoten eventuell nicht.

Produktspezifische HinweiseCopy Anchor Link

Für die farmweite Aktualisierung ab Server 2016 muss der primäre Verbundserver selbst mindestens Server 2016 sein und die Farmverhaltensebene die Funktion unterstützen. Prüfen Sie jeden Knoten, auch wenn der Befehl nur einmal läuft. Unter Server 2012 R2 bleibt es eine Aufgabe pro Knoten.

WAP-Zertifikate sind lokal und brauchen das WAP-Cmdlet auf jedem Proxy. Verwenden Sie auf AD FS und WAP dasselbe Zertifikat, sofern Design und Microsoft-Vorgaben keine getrennten Namen vorsehen. Tauschen Sie Tokensignatur- und Tokenentschlüsselungszertifikate nicht nebenbei aus; ihr Wechsel betrifft vertrauende Seiten und Anspruchsanbieter.

Neues Zertifikat prüfenCopy Anchor Link

Get-AdfsSslCertificate | Format-Table HostName,PortNumber,CertificateHash
netsh http show sslcert
Get-Service adfssrv

Prüfen Sie von außerhalb der Farm sowohl den TLS-Endpunkt als auch die Antwort der Anwendung:

openssl s_client -connect fs.example.com:443 -servername fs.example.com -showcerts
curl -fsS https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

Testen Sie die Anmeldung, die Geräte- bzw. Clientzertifikat-Authentifizierung (falls genutzt), den über WAP veröffentlichten Endpunkt und jeden Knoten direkt. Prüfen Sie, ob die Verbundmetadaten weiterhin die erwarteten Tokenzertifikate enthalten - die TLS-Änderung darf sie nicht unbemerkt verändern.

RollbackCopy Anchor Link

Verwenden Sie den notierten alten Fingerabdruck mit denselben Cmdlets - zuerst die Farm, dann jeden WAP:

Set-AdfsSslCertificate -Thumbprint <alter-fingerabdruck>        # bzw. Set-AdfsAlternateTlsClientBinding
Set-WebApplicationProxySslCertificate -Thumbprint <alter-fingerabdruck>   # auf jedem WAP

Prüfen Sie die Bindungen wie in Schritt 7 und testen Sie Metadaten und Anmeldung erneut. Das geht nur, solange das alte Zertifikat noch installiert und gültig ist - behalten Sie es, bis alle Farm- und Proxy-Endpunkte bestätigt sind.

Häufige ProblemeCopy Anchor Link

• Das Zertifikat liegt im Speicher des aktuellen Benutzers statt des lokalen Computers oder hat keinen privaten Schlüssel.
• Der Verbunddienstname oder der certauth-Name fehlt in den SANs.
• Das Farm-Cmdlet ab Server 2016 erreicht die anderen Knoten nicht per PowerShell-Remoting.
• Die WAP-Knoten wurden nach der AD-FS-Farm nicht aktualisiert.
• Es wurde nur eine netsh-Bindung geändert, die übrigen AD-FS-Bindungen sind veraltet.
• Die TLS-Erneuerung wird mit dem Wechsel des Dienstkommunikations- oder Tokenzertifikats verwechselt.

Zertifikatstausch mit aethercert automatisierenCopy Anchor Link

Das aethercert-Deployment-Ziel für AD FS importiert das Zertifikat, kann einem konfigurierten Dienstkonto Lesezugriff auf den privaten Schlüssel geben und ruft Set-AdfsSslCertificate für die Dienstkommunikation bzw. Set-AdfsCertificate für Tokensignatur und Tokenentschlüsselung auf. Microsoft unterscheidet die TLS/SSL-Bindung der Farm vom Dienstkommunikationszertifikat in der AD-FS-Verwaltung; prüfen Sie also, ob der gewählte Modus zu dem Zertifikat passt, das Sie austauschen wollen. Farmmodus, WAP-Umfang und die Auswirkungen eines Tokenzertifikat-Wechsels erfordern weiterhin eine bewusste Planung.

Unter Deployment-Ziele finden Sie die Felder dieser Vorlage, die Voraussetzungen auf dem Host und den Stand der Verifizierung.

QuellenCopy Anchor Link

• Microsoft Learn: TLS/SSL-Zertifikate in AD FS und WAP verwalten
• Microsoft Learn: Set-AdfsSslCertificate
• Microsoft Learn: Get-AdfsSslCertificate
• Microsoft Learn: Abgrenzung des Dienstkommunikationszertifikats