Einrichtung SSO im Authentication Service (Docker)
Keytab-Datei
Wenn der Authentication Service unter Docker läuft und SSO verwendet werden soll, wird eine Kerberos Keytab-Datei (https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html) benötigt. Diese muss vom Administrator über einen ActiveDirectory Server erstellt werden.
Folgende “Variablen” werden in dieser Dokumentation verwendet, diese müssen auf die Gegebenheiten beim Kunden angepasst werden:
Name | Bedeutung |
|---|---|
ServiceUser | Ein normaler Benutzer im ActiveDirectory welcher vom Authentication Service für die Ticketerstellung verwendet werden soll. Kann ein bestehender oder neuer “normaler” AD-Benutzer sein. |
ServiceUserPassword | Passwort des ServiceUser Benutzers |
server | Hostname des Servers auf welchem der Authentication Service läuft und von den Clients erreichtbar ist. |
server.domain.local | FQDN des Servers auf welchem der Authentication Service läuft und von den Clients erreichbar ist. |
DOMAIN.LOCAL | Der Domänenname des AD (Großschreibung beachten!) |
DOMAIN | NetBIOS Name der Domäne |
Zuerst muss dem Benutzer der Server HTTP Dienst zugewiesen werden. Dazu muss der Administrator auf dem ActiveDirectory Server eine Administrator-Eingabeaufforderung öffnen und die folgenden Befehle eingeben:
setspn -S HTTP/server.domain.local@DOMAIN.LOCAL ServiceUsersetspn -S HTTP/server@DOMAIN.LOCAL ServiceUserDanach kann die krb5.keytab-Datei erstellt werden:
ktpass -princ HTTP/server.domain.local@DOMAIN.LOCAL -pass ServiceUserPassword -mapuser DOMAIN\ServiceUser -pType KRB5_NT_PRINCIPAL -out krb5.keytab -crypto Allzusätzlich sollte noch ein Eintrag ohne Domäne in der Datei erstellt werden:
Der “-in krb5.keytab” Parameter muss hier angegeben werden, damit ein 2. Eintrag in der Keytab erstellt wird. Diesen Parameter können Sie auch nutzen, um mehrere Domänen in die Keytab einzufügen. Dazu die krb5.keytab auf den zweiten Domänencontroller kopieren und die oben genannten Schritte ausführen. Darauf achten, dass nun bei allen weiteren ktpass-Befehle der “-in krb5.keytab” Parameter mit angegeben wird.
Diese Datei muss auf den Authentification Service geladen werden. Dies kann über den Designer im Bereich Security > User Directories erledigt werden:
Der Web-Designer hat allerdings bis einschließlich Version 2.0.3 einen Bug, bei welchem die KeyTab-Datei nicht korrekt hochgeladen wird. Die Alternative dazu ist, die Datei über die API des Authentication Services hochzuladen. Hierzu bieten sich verschiedene Wege an.
Keytab über Powershell hochladen
Die Keytab kann auch über Powershell hochgeladen werden. Hierzu muss folgender Befehl ausgeführt werden. Bitte die URL (http/https, server.domain.local und den Port 30001) und den master_token ensprechend anpassen.
Keytab mittels curl hochladen
Im awrun-Umfeld kann es hilfreich sein, die keytab-Datei über curl hochladen zu können. Hierzu kann der folgende Befehl verwendet werden. Bitte die URL (http/https, server.domain.local und den Port 30001) und den master_token ensprechend anpassen.
Keytab mit Postman hochladen
Über die Anwendung Postman (Download Postman | Get Started for Free) kann die Keytab-Datei ebenfalls hochgeladen werden.
Dazu ist folgende Route in der Methode “PUT” aufzurufen:
Beim Aufruf der Route muss ein “Bearer Token”, d.h. ein Token zur Anmeldung am Authentification Service (z.B. der Master-Token oder ein hochgeladener “Access Key” aus dem Credential Store des Designers), verwendet werden. Hierzu in Postman auf den Reiter Authorization wechseln, Bearer Token auswählen und einen Token eintragen:
Im Reiter Body den Typen “binary” auswählen und dort über Select File die Keytab auswählen:
Zusätzliche Voraussetzungen
Desktop Client (alt)
Der Authentication Service muss nun bei den Clients als server.domain.local konfiguriert werden. Zusätzlich muss server.domain.local bei den Clients als Intranet-Computer bekannt sein. Dies kann über die alte Systemsteuerung unter Internetoptionen → Sicherheit → Lokales Intranet → Sites → Erweitert konfiguriert werden. Hier einfach server.domain.local hinzufügen. Diese Einstellung kann auch über eine Gruppenrichtlinie an die Clients verteilt werden.
Die betreffende Gruppenrichtlinie befindet sich im Gruppenrichtlinieneditor unter:
Computerkonfiguration → Administrative Vorlagen → Windows-Komponenten → Internet Explorer → Internetsystemsteuerung → Sicherheitsseite → Liste der Site zu Zonenzuweisungen
Diese Einstellung muss Aktiviert werden und dann muss dann der Servername mit dem Wert 1 in der Liste hinzugefügt (erscheint beim anklicken von “Anzeigen”) werden:
Web Client und webbasierter Desktop Client
Authentication Service
Der Authentication Service benötigt eine zusätzliche Konfiguration, da für SSO strengere CORS Regeln gelten. Unter Windows müssen während des Setups die Allowed Origins eingetragen werden. Hier muss die URL des Web Clients eingetragen werden. Sind mehrere URLs für vorhanden, könnten diese kommagetrennt eingetragen werden:
In Docker muss alternativ die Umgebungsvariable SSOALLOWEDORIGINS gesetzt werden. Der Name der Umgebungsvariablen kann auch als Parameter für das Setup mitgegeben werden, um den Wert zu setzen.
Microsoft Edge / webview2
Um SSO für den Authentication Service über Microsoft Edge zu aktivieren, muss ein Registry Schlüssel auf den Clients gesetzt werden. Unter dem Schlüssel
muss ein String-Wert mit dem Namen “AuthNegotiateDelegateAllowlist” angelegt werden. Dieser enthält dann eine kommagetrennte Liste mit Hostnamen. Hier müssen dann alle möglichen Hostnamen des Authentication Services eingetragen werden:
Diese Einstellung kann auch über eine Gruppenrichtlinie verteilt werden. Hierzu muss zunächst die administrative Vorlage für Microsoft Edge von der folgenden Seite heruntergeladen werden:
https://www.microsoft.com/de-de/edge/business/download
Dort gibt es für die jeweiligen Edge-Versionen einen Link zum herunterladen der Windows-Richtlinie. In den meisten Fällen wird dies die Richtlinie für Windows 64-bit sein:
Heruntergeladen wird eine .cab-Datei. Diese kann im Windows-Explorer geöffnet werden und enthält die Datei MicrosoftEdgePolicyTemplates.zip.
Die Zip-Datei muss nun zunächst aus der .cab-Datei herauskopiert werden. Danach wird die .zip-Datei geöffnet und der Inhalt des Ordners “windows\admx” der Zip-Datei in den Ordner C:\Windows\SYSVOL\domain\Policies\PolicyDefinitions eines Domänen-Controllers kopiert werden.
Beim nächsten Domänen-Replikationsintervall sollten die Vorlagen auf alle Domänencontroller repliziert werden.
Nun kann über den Gruppenrichtlinienverwaltungs-Editor für die Default Domain Policy die Richtlinie konfiguriert werden. Dazu wird das Programm mmc.exe geöffnet (Windows-Taste + R → mmc.exe → Enter)
Ist mmc.exe geöffnet, wird im Menü Datei → Snap-In hinzufügen/entfernen gewählt. Dort dann den Gruppenrichtlinienverwaltungs-Editor auswählen:
Und den Knopf “Hinzufügen” betätigen. Im darauffolgenden Dialog auf Durchsuchen klicken und “Default Domain Policy” auswählen:
Danach auf Fertig stellen und in der Konsole erscheint der Editor.
Dort dann im Pfad Default Domain Policy → Computerkonfiguration → Richtlinien → Administrative Vorlagen: … → Microsoft Edge → HTTP-Authentifizierung
Den Eintrag Gibt eine Liste der Server an, an die Microsoft Edge Anmeldeinformationen von Benutzern delegieren auswählen und öffnen:
Hier dann kommagetrennt eine Liste von Hostnamen einfügen, unter welchen der Authentication Service erreichbar ist. Mit einem Klick auf OK wird die Gruppenrichtlinie aktiviert und bei der nächsten Gelegenheit auf die Clients verteilt.
Weitere Informationen finden sich unter den folgenden Links:
https://learn.microsoft.com/de-de/deployedge/microsoft-edge-policies#authnegotiatedelegateallowlist
Problembehandlung
Wenn der Client sich nicht mittels SSO Authentifizieren kann, kann im Docker-Container über eine Shell geprüft werden, ob der Container ein Kerberos5 Ticket vom Domänencontroller abrufen kann.
Öffnen Sie zunächst eine Konsole im laufendem Authentication Service Container (Shell über Portainer oder mittels docker-compose exec … /bin/bash)
Nun kann über den Befehl:
geprüft werden, ob ein Kerberos Ticket erstellt werden kann. Falls hier der Fehler “Cannot find KDC for realm “DOMAIN.LOCAL” while getting initial credentials” erscheint, können Sie unter /etc/krb5.conf mit folgendem Inhalt anlegen:
Falls weitere Domänencontroller existieren, können diese über einen weiteren kdc Eintrag angegeben werden. Mehrere Domänen können über einen weiteren Eintrag angegeben werden:
Nun nochmals mittels des folgende Befehls testen:
Alle hier weiteren auftretenden Fehler müssen behoben werden. Die Datei /etc/krb5.conf muss dann über ein Docker-Volume persistent gemacht werden.
Windows verwendet NTLM
Wenn in der Log-Ausgabe des Service beim Aufruf der Route (http://<auth_service_host>:<port>/api/v2/auth/login/sso) die folgende Fehlermeldung erscheint:
GSSAPI operation failed with error - An unsupported mechanism was requested.
Dann ist Windows auf NTLM zurückgefallen. Da NTLM nicht vom Authentication Service unterstützt wird, wird diese Fehlermeldung ausgegeben.
In diesem Fall, müssen Sie die Ursache des Zurückfallens ermitteln.
Eine Seite welche dabei behilflich seinen kann, ist folgende:
https://docs.microsoft.com/de-de/troubleshoot/iis/troubleshoot-kerberos-failures-ie
Fehler im Log: LoginSSO: User username not found in database! Denying request
Gute Nachricht! Das SSO selbst hat funktioniert, das System nur noch den Benutzer welchen es vom Betriebssystem erhalten hat, nicht auf einen Benutzer in seiner Datenbank zuordnen.
In diesem Fall ist folgendes in der User Directory Konfiguration im Designer zu Prüfen:
Ist ist der NetBIOS Name korrekt gesetzt?
Ist das SSO User Name Template korrekt gesetzt?
Beispiel 1: Username mit @
In diesem Fall muss der NetBIOS Name mit “DT.LOCAL” angegeben werden (der Teil hinter dem '@')
Das SSO User Name Template muss dann auf “%sAMAccountName%@DT.LOCAL“ gesetzt werden.
Beispiel 2: Username mit \
In diesem Fall muss der NetBIOS Name mit “DT” angegeben werden (der Teil vor dem '\')
Das SSO User Name Template muss dann auf “DT\%sAMAccountName%“ gesetzt werden.