SAML-Authentifizierung für Apache Guacamole – Top schwäbische IT-Praxis

Zuletzt aktualisiert am 12. August 2023, 12:08:16

Mit dem Ausbruch der globalen Pandemie (COVID) habe ich meinen ersten Beitrag über die Installation und Konfiguration von Apache Guacamole geschrieben. Hintergrund ist, dass damals möglichst viele Menschen für kurze Zeit von zu Hause aus arbeiten mussten.

Damals habe ich die Möglichkeit beschrieben, Benutzer über LDAP zu authentifizieren. In diesem Zusammenhang wurde Apache Guacamole häufig im selben Netzwerk wie der LDAP-Server platziert (in der DMZ oder sogar im LAN). Die Anbindung an Verzeichnisdienste, DS (z. B. Active Directory) über LDAP oder LDAPS ist derzeit umstritten. Denn es ist grundsätzlich möglich, alle Objekte eines DS zu lesen.

Letztes Weihnachten habe ich es endlich geschafft, Apache Guacamole mit einem Microsoft Active Directory Federation Service (AD FS) zu verbinden. Das bedeutet, dass es keine Rolle mehr spielt, ob Apache Guacamole in der DMZ Ihres Netzwerks oder direkt im Internet von einem Webhoster gehostet wird.

Voraussetzung hierfür ist der AD FS-Betrieb (inkl. WAP) + Basisinstallation von Apache Guacamole (siehe Link oben). Darüber spreche ich in diesem Beitrag.

Guacamole-Aufbau

Es gibt eine Erweiterung namens SSO für AD FS (SAML2)-Verbindung. Stellen Sie über Putty/TeraTerm SSH eine Verbindung zur Apache Guacamole-Instanz her.

Installieren der Erweiterung

Konfigurieren der aktuellen Version von Apache Guacamole.

export guacver=1.5.3
echo $guacver

Laden Sie die SSO-Erweiterung herunter.

wget --trust-server-names " -O /usr/src/guacamole-auth-sso-$guacver.tar.gz

Entpacken Sie das Erweiterungsarchiv.

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

Kopieren Sie die Erweiterung in das Programmverzeichnis.

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

Apache Tomcat JVM-Konfiguration

Wenn Apache Guacamole direkt mit AD FS kommuniziert (wenn sich beide Server im selben Netzwerk befinden), muss das SSL-Zertifikat seiner PKI zum CA-Speicher von Java hinzugefügt werden.

Exportieren Sie das Root-CA-Zertifikat im Base64-Format. Anschließend öffnen Sie die Datei in einem Editor (z. B. Notepad++). Es sollte so aussehen:

Wechseln Sie zu SSH-Sitzungen und erstellen Sie mit dem Editor eine neue leere Datei. Fügen Sie dann den kopierten Inhalt dort ein. Speichern und schließen Sie die Datei.

Speichern Sie den ursprünglichen CA-Speicher aus Java.

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

Fügen Sie das Root-CA-Zertifikat zum CA-Speicher hinzu.

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: In meinem Fall entspricht der Alias ​​meinem CA-Root-Namen.

Erweiterungskonfiguration

Diese Konfiguration erweitert die vorhandene Konfigurationsdatei /etc/guacamole/guacamole.properties.

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: 
${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: 
${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: 
${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: 
${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: Vergessen Sie nicht, die Parameterwerte selbst anzupassen!

AD FS-Konfiguration

Starten Sie die AD FS-Verwaltungskonsole und wählen Sie im linken Navigationsbereich „Relying Party Trusts“ aus. Wählen Sie dann auf der rechten Seite den Eintrag „Relaying Party Trust hinzufügen“ aus.

Als nächstes müssen zwei Anspruchsrichtlinien konfiguriert werden, um die richtigen Werte von AD FS oder Active Directory an Apache Guacamole zu übergeben.

Übernehmen Sie die Konfiguration mit „OK“.

Funktionstest

Starten Sie in einem Browser und gehen Sie zu Apache Guacamole. Klicken Sie unten links auf SAML. Sie werden dann zum AD FS-Anmeldebildschirm weitergeleitet. An diesem Punkt kann sich jeder Benutzer anmelden (siehe Ersteinrichtung von Relying Party Trust).

Die Anmeldung hat gut geklappt – sehr cool!

Weisen Sie Verbindungen zwischen Gruppen zu

Natürlich funktioniert in Apache Guacamole alles nur, wenn die Verbindungen den entsprechenden Gruppen zugeordnet sind. Dies bedeutet, dass Benutzer bei der Anmeldung die Verbindungen erhalten, die sie benötigen.

Natürlich müssen zuerst Verbindungen hergestellt werden. In meinem Fall sind es vier Stück.

Dann erstelle ich eine neue Gruppe „test1“.

Dann noch eine neue Gruppe „test2“.

Um AD FS-Benutzern Attribute zuzuweisen, müssen natürlich Gruppen im Active Directory erstellt werden.

Hinweis: Gruppen in AD müssen nicht denselben Namen wie Guacamole in Apache haben. Hier gibt es keine Abhängigkeiten!

Nun muss in AD FS die Verbindung zwischen AD und Apache Guacamole hergestellt werden.

Hinweis: In den Regeln ist es wichtig, dass der Wert „Output Claim Value“ mit dem Namen der Gruppe übereinstimmt, die in Apache Guacamole erstellt wurde.

Fügen Sie abschließend die Domänenbenutzer der Gruppe „gg-guac-test01“ und/oder „gg-guac-test02“ hinzu. Zum Funktionstest habe ich den Benutzer zur letzten Gruppe in AD hinzugefügt.

Wie Sie sehen, sieht mein Testbenutzer nur zwei der vier Verbindungen. Dies gilt auch für die Verknüpfung von Verbindungen zu Apache Guacamole-Gruppen (siehe oben).

Fehlerbehebung/Aktivierung

Leider funktionieren solche Verbindungen und Konfigurationen nicht immer sofort. Es sind oft die Details, die den Unterschied zwischen einem Fehler und der Funktionalität ausmachen.

Protokolldateien AD FS/Apache Guacamole

AD FS protokolliert die entsprechenden Einträge in der Ereignisanzeige unter „Anwendungs- und Dienstprotokolle -> AD FS -> Admin“.

Bei Apache Guacamole ist der erste Anlaufpunkt die Tomcat- oder Catalina-Logdatei. Diese Datei befindet sich im Verzeichnis „/var/log/tomcat9“. Standardmäßig werden jedoch nur „INFO“-Meldungen aufgezeichnet.

Die Protokollierungsstufe wird über die Datei „/var/lib/tomcat9/webapps/guacamole/WEB-INF/classes/logback.xml“ konfiguriert.

Ändern Sie den Wert von „info“ in „debug“. Speichern und schließen Sie die Datei. Bitte vergessen Sie nicht, den Tomcat9-Dienst neu zu starten.

Alle Ereignisse werden in der Protokolldatei „/var/log/tomcat9/catalina.out“ protokolliert. Vergessen Sie nicht, die Änderungen rückgängig zu machen, wenn der Fehler gefunden wird. Andernfalls wird die Festplatte früher oder später wahrscheinlich voll sein.

Bewerten Sie die SAMLResponse

Wenn die Anmeldung grundsätzlich funktioniert, aber beispielsweise die Zuordnung von Active Directory zu Apache Guacamole-Gruppen falsch ist, bietet es sich an, die SAMLResponse auszuwerten.

Melden Sie sich dazu bei Apache Guacamole an. Wenn die ADFS-Anmeldeseite angezeigt wird, öffnen Sie den Entwicklermodus mit der Taste F12. Wechseln Sie dann zum Reiter „Netzwerk“.

Melden Sie sich nun mit einem Domänenbenutzer an. Sobald der Vorgang abgeschlossen ist, scrollen Sie im Bereich Netzwerk nach oben. Dort sollten Sie einen Eintrag namens „Rückruf“ sehen.

Klicken Sie auf den Eintrag und wählen Sie rechts den Reiter „Payload“ aus.

Es gibt jetzt einen SAMLResponse-Parameter mit einem zugehörigen Wert. Dies ist eine Kodierung, die base64 verwendet.

Kopieren Sie den 1:1-Wert, gehen Sie zur Website der SAML Decoder Tools und fügen Sie ihn dort in das Feld „Deflated and Encoded XML“ ein.

Bei erfolgreicher Kodierung wird im Feld „Deflated XML“ Klartext ausgegeben. Zur besseren Lesbarkeit kopiere ich den Inhalt gerne in Notepad++.

Der gelb markierte Standort enthält von AD FS übertragene Attribute.

Alles

Standardmäßig erscheint beim Besuch der Internetadresse von Guacamole nun eine Anmeldeseite zur lokalen Authentifizierung gegenüber der Datenbank.

Das Verhalten kann über den Parameter „extension-priority“ in der Datei „/etc/guacamole/guacamole.properties“ gesteuert werden. Der Wert „*, saml“ gibt die Reihenfolge der Authentifizierungsoptionen an. Wenn Sie standardmäßig immer direkt zur AD FS-Authentifizierung umleiten möchten, muss dem Parameter der Wert „saml, *“ zugewiesen werden. Im Umkehrschluss bedeutet dies, dass Sie als lokaler Administrator nicht auf die lokale Authentifizierungsseite zugreifen können, um Änderungen vorzunehmen.

Daher habe ich den Parameter unverändert gelassen und stattdessen einen anderen vHost auf dem Apache-Webserver definiert (guac.lab03.daniel.wydler.eu). Dadurch wird beim Aufruf automatisch auf „ umgeleitet. Ich habe also guac01.lab03.daniel.wydler.eu für den Administrator und guac.lab03.daniel.wydler.eu für Benutzer.