SAML Authentifizierung für Apache Guacamole

Letzte Aktualisierung am 12.08.2023, 12:08:16 Uhr

Mit Ausbruch der globalen Pandemie (COVID) habe ich meinen ersten Beitrag zur Installation und Konfiguration von Apache Guacamole geschrieben. Hintergrund ist, dass damals kurzfristig so viele Personen wie möglich von zu Hause arbeiten sollten/mussten.

Zu damaligen Zeitpunkt habe ich für die Authentifizierung von Benutzern die Möglichkeit über LDAP beschrieben. Damit verbunden wurde oftmals Apache Guacamole in das selbe Netzwerk (in der DMZ oder sogar im LAN) wie der LDAP Server platziert. Die Anbindung von Directory Services, DS (z.B. Active Directory) über LDAP bzw. LDAPS ist bis heute diskussionswürdig. Da es grundsätzlich möglich ist alle Objekte eines DS auszulesen.

Daher habe ich mich an Weihnachten letzten Jahres endlich mit der Anbindung von Apache Guacamole in Verbindung mit Microsoft Active Directory Federation Service (AD FS) beschäftigt. Damit spielt es keine Rolle mehr, ob Apache Guacamole in der DMZ im eigenen Netzwerk oder direkt im Internet bei einem Webhoster bereitgestellt wird.

Voraussetzung dafür ist eine funktionierende AD FS (inkl. WAP) + Grundinstallation von Apache Guacamole (siehe Link oben). Darauf setze ich bei diesem Beitrag.

Konfiguration Guacamole

Für die Anbindung AD FS (SAML2) gibt es eine Erweiterung mit dem Namen SSO. Mit Hilfe von Putty/TeraTerm SSH auf die Apache Guacamole Instanz verbinden.

Installation der Erweiterung

Festlegen der aktuellen Version von Apache Guacamole.

export guacver=1.5.3
echo $guacver

Download der Erweiterung SSO.

wget --trust-server-names "https://apache.org/dyn/closer.cgi?action=download&filename=guacamole/$guacver/binary/guacamole-auth-sso-$guacver.tar.gz" -O /usr/src/guacamole-auth-sso-$guacver.tar.gz

Archiv der Erweiterung entpacken.

tar xvzf /usr/src/guacamole-auth-sso-$guacver.tar.gz -C /usr/src/

Erweiterung in das Programmverzeichnis kopieren.

cp /usr/src/guacamole-auth-sso-$guacver/saml/guacamole-auth-sso-saml-$guacver.jar /etc/guacamole/extensions/

Konfiguration JVM des Apache Tomcat

Falls Apache Guacamole direkt mit dem AD FS kommuniziert (wenn beide Server im selben Netzwerk stehen), muss das SSL-Zertifikat der eigenen PKI dem CA Store von Java hinzugefügt werden.

Zertifikat der Root CA im Format base64 exportieren. Anschließend die Datei in einem Editor (z.B. Notepad++) öffnen. Das sollte so aussehen:

In die SSH Sessions wechseln, mit dem Editor eine neue leere Datei erzeugen. Dort dann den kopierten Inhalt einfügen. Datei Speichern und schließen.

Initialer CA Store vom Java sichern.

cp /etc/ssl/certs/java/cacerts /etc/ssl/certs/java/cacerts.original

Das Root CA Zertifikat dem CA Store hinzufügen.

keytool -trustcacerts -keystore "/etc/ssl/certs/java/cacerts" -storepass changeit -importcert -alias LAB03-Wydler-RSA-TLS-RCA2022-1 -file "/usr/share/ca-certificates/lab03-wydler-rsa-tls-rca-2022-1.crt"

Hinweis: Der Alias entspricht in meinen Fall dem Namen meiner Root CA.

Konfiguration der Erweiterung

Nachstehend Konfiguration wird der bestehenden Konfigurationsdatei /etc/guacamole/guacamole.properties erweitert.

SPA="$(printf ' ')"
cat << EOF >> /etc/guacamole/guacamole.properties
#
#SSO Einstellungen für Microsoft AD FS
#
${SPA}
#The URI of the XML metadata file that from the SAML Identity Provider that contains all of the information the SAML extension needs in order to know how to authenticate with the IdP.
saml-idp-metadata-url: https://login.lab03.daniel.wydler.eu/FederationMetadata/2007-06/FederationMetadata.xml
${SPA}
#The base URL of the SAML IdP. This is the URL that the SAML authentication extension will use to redirect when requesting SAML authentication. If the saml-idp-metadata-url property is provided, this parameter will be ignored. If the metadata file is not provided this property is required.
#saml-idp-url:
${SPA}
#The entity ID of the Guacamole SAML client, which is generally the URL of the Guacamole server, but is not required to be so. This property is required if either the saml-idp-metadata-url property is not specified, or if the provided metadata file does not contain the SAML SP Entity ID for Guacamole Client.
saml-entity-id: https://guac01.lab03.daniel.wydler.eu
${SPA}
#The URL that the IdP will use once authentication has succeeded to return to the Guacamole web application and provide the authentication details to the SAML extension. The SAML extension currently only supports callback as a POST operation to this callback URL. This property is required
saml-callback-url: https://guac01.lab03.daniel.wydler.eu/
${SPA}
#Require strict security checks during SAML logins. This will insure that valid certificates are present for all interactions with SAML servers and fail SAML authentication if security restrictions are violated. This property is optional, and will default to true, requiring strict security checks. This property should only be set to false in non-production environments during testing of SAML authentication.
saml-strict: false
${SPA}
#Enable additional logging within the supporting SAML library that can assist in tracking down issues during SAML logins. This property is optional, and will default to false (no debugging).
saml-debug: false
${SPA}
#The name of the attribute provided by the SAML IdP that contains group membership of the user. These groups will be parsed and used to map group membership of the user logging in, which can be used for permissions management within Guacamole Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”.
saml-group-attribute: saml-group-attribute: http://schemas.xmlsoap.org/claims/Group
${SPA}
#To ensure users are redirected to the SAML identity provider immediately (without a Guacamole login screen), ensure the SAML extension has priority over all others.
extension-priority: *, saml
${SPA}
#A comma-separated list of the identifiers of authentication providers that should be allowed to fail internally without aborting the authentication process. 
skip-if-unavailable: saml
${SPA}
EOF

Hinweis: Nicht vergessen, die Werte bei den Parametern für euch anzupassen!

Konfiguration AD FS

Die AD FS Management Konsole starten und links im Navigationsbereich „Relying Party Trusts“ auswählen. Anschließend auf der rechten Seite den Eintrag „Add Relaying Party Trust“ auswählen.

Danach müssen noch zwei Claim Policies eingerichtet werden, damit die richtigen Werte von AD FS bzw. Active Directory an Apache Guacamole weitergereicht werden.

Die Konfiguration mit „OK“ übernehmen.

Funktionstest

In einem Browser starten und dort die Adresse des Apache Guacamole aufrufen. Links unten auf SAML klicken. Es erfolgt dann die Weiterleitung zur Anmeldemaske von AD FS. Aktuell kann sich jeder Benutzer (siehe initiale Konfiguration des Relying Party Trust) anmelden.

Anmeldung hast problemlos funktioniert – sehr schön!

Zuweisung von Verbindungen über Gruppen

Das Ganze funktioniert natürlich nur, wenn die Verbindungen im Apache Guacamole dort auch entsprechenden Gruppen zugeordnet wird. Somit erhalten  die Nutzer bei Anmeldung genau die Verbindungen, die Sie benötigen.

Zuerst müssen hierfür natürlich Verbindungen angelegt werden. In meinem Fall sind es vier Stück.

Danach lege ich die neue Gruppe „test1“ an.

Anschließend noch eine weitere neue Gruppe „test2“.

Damit AD FS die Attribute den Nutzer zuweisen kann, müssen die Gruppen natürlich im Active Directory angelegt werden.

Hinweis: Die Gruppen im AD müssen nicht den gleichen Namen haben wie im Apache Guacamole heißen. Hier gibt es keine Abhängigkeit!

Nun muss die Verknüpfung zwischen AD und Apache Guacamole im AD FS hergestellt werden.

Hinweis: In den Rules ist es wichtig, dass der Wert vom „Outgoing claim value“ dem Namen der Gruppe, welche im Apache Guacamole angelegt wurden, entsprechen.

Abschließend die Domänen-Benutzer in die Gruppe „gg-guac-test01“ und/oder „gg-guac-test02“ aufnehmen. Ich habe für den Funktionstest den Benutzer in die letzte Gruppe im AD aufgenommen.

Wie zu sehen ist, sieht mein Testbenutzer nur zwei der vier Verbindungen. Das entspricht auch der Verknüpfung der Verbindungen zu Gruppen im Apache Guacamole (siehe oben).

Fehlersuche/Aktivierung Debugging

Leider funktionieren solche Anbindungen und Konfiguration nicht immer sofort. Oftmals sind es Details, die den Unterschied zwischen Fehler und Funktion machen.

Logfiles AD FS/Apache Guacamole

Seitens AD FS werden entsprechende Einträge im Event Viewer unter „Application and Services Logs -> AD FS -> Admin“ protokolliert.

Bei Apache Guacamole ist die erste Anlaufstelle das Logfile von Tomcat bzw. Catalina. Diese Datei ist im Verzeichnis „/var/log/tomcat9“ zu finden. Standardmäßig werden allerdings nur „INFO“ Meldungen mitgeschrieben.

Die Konfiguration des Loglevels erfolgt über die Datei „/var/lib/tomcat9/webapps/guacamole/WEB-INF/classes/logback.xml“.

Dort den Wert von „info“ auf „debug“ ändern. Die Datei speichern und schließen. Bittet nicht vergessen, den Service Tomcat9 neu zu starten.

Danach werden im Logfile „/var/log/tomcat9/catalina.out“ alle Events protokolliert. Nicht vergessen, die Änderungen wieder rückgängig zu machen, wenn der Fehler gefunden wurde. Anderenfalls wird früher oder später vermutlich die Festplatte volllaufen.

SAMLResponse auswerten

Wenn die Anmeldung grundsätzlich funktioniert, aber z.B. die Zuordnung von Active Directory zu Apache Guacamole Gruppen fehlerhaft ist, so bietet sich an den SAMLResponse auszuwerten.

Hierzu eine Anmeldung am Apache Guacamole aufrufen. Wird die Anmeldeseite von ADFS anzeigt, über die Taste F12 die Entwicklermodus öffnen. Danach in den Reiter „Netzwerk“ wechseln.

Nun die Anmeldung mit einem Domänen-Benutzer durchführen. Ist der Vorgang abgeschlossen in dem Bereich Netzwerk nach ganz oben scrollen. Dort sollte es einen Eintrag mit dem Namen „Callback“ zu sehen sein.

Den Eintrag anklicken und rechts den Reiter „Nutzlast“ auswählen.

Nun ist dort der Parameter SAMLResponse mit dem dazugehörigen Wert. Es handelt sich hierbei um eine Codierung mit Hilfe von base64.

Den Wert 1:1 kopieren, die Webseite SAML Decoder Tools aufrufen und dort im Bereich „Deflated and Encoded XML“ einfügen.

 Ist das Encoding erfolgreich gewesen, wird im Bereich „Deflated XML“ der Klartext ausgeben. Den Inhalt kopiere ich gerne in Notepad++, um es bessere lesen zu können.

Die gelbmarkierte Stelle enthält die übergebenen Attribute vom AD FS.

Sonstiges

Standardmäßig erscheint nun beim Aufruf der Internetadresse von Guacamole die Anmeldeseite für die lokale Authentifizierung gegen die Datenbank.

Über den Parameter „extension-priority“ in der Datei „/etc/guacamole/guacamole.properties“ kann das Verhalten gesteuert werden. Dessen Wert „*, saml“  ist die Reihenfolge der Authentifizierungsoptionen. Möchte man standardmäßig immer direkt zur AD FS Authentifizierung umgeleitet werden so muss dem Parameter folgenden Wert „saml, *“ zugewiesen werden. Bedeutet im Umkehrschluss, dass man erst einmal nicht mehr an die lokale Authentifizierungsseite ran kommt, um als lokaler Administrator Änderungen vorzunehmen.

Daher habe ich den Parameter unverändert gelassen und habe stattdessen auf dem Apache Webserver einen weiteren vHost definiert (guac.lab03.daniel.wydler.eu). Diese leitet automatisch beim Aufruf auf „https://guac.lab03.daniel.wydler.eu/api/ext/saml/login“ um. Somit habe ich für für die Administration guac01.lab03.daniel.wydler.eu und für die Nutzer guac.lab03.daniel.wydler.eu.