Keycloak.X, aber sicher – ohne bekannte Sicherheitslücken!

TLDR: Wie man die bekannten CVEs (Common Vulnerabilities and Exposures) mit einer eigenen Keycloak-Distribution auf null* reduziert.

Einführung

Keycloak (s. Website) wird durch die Umstellung auf Quarkus einfacher und robuster, so das Versprechen. Wie man sich Schritt für Schritt einem produktiven Setup nähern kann, haben wir bereits im Blogpost „From Keycloak to Keycloak.X (englisch)“ mit einer früheren Version von Keycloak.X gezeigt. Inzwischen wurde Version 18.0.0 veröffentlicht und die Roadmap für das Keycloak Projekt weiter konkretisiert. Darin liest man, dass im September 2022 die letzte Wildfly-Distribution erscheinen soll – ab dann gibt es nur noch die Quarkus-basierte Keycloak-Distribution.

Der vorliegende Artikel beschreibt einen Ansatz, mit dem die Performance und die Sicherheit eines Keycloak-Systems durch eine eigene Distribution verbessert werden kann. Dazu ist die vollständige Kontrolle über die Erzeugung einer eigenen Keycloak-Distribution notwendig.

Aspekte einer eigenen Keycloak-Distribution

Durch die Erzeugung einer eigenen, auf die jeweiligen Bedürfnisse zugeschnittene, Keycloak-Distribution, kann sich die Sicherheit und/oder die Performance des laufenden Keycloak-Systems verbessern.
Als Gegenargument hören wir häufig, dass eine eigene Distribution zu unnötiger und erhöhter Komplexität führt. Außerdem scheint allgemein eine Empfehlung zur Nutzung offizieller Images zu gelten, damit dieser Teil der Verantwortung nicht selbst zu tragen ist. Wir argumentieren hier für die explizite Übernahme diese Verantwortung im Falle von Keycloak und sehen große Vorteile in diesem Schritt.

Die eigene Distribution kann in folgenden Punkten unterstützen:

1. Verwendung einer optimierten Konfiguration für schnellen Serverstart
2. Unterstützung eigener Extensions und Themes
3. Nur tatsächlich verwendete Quarkus Extensions aktiviert
4. Zusätzlich benötigte Quarkus Extensions werden unterstützt
5. Bibliotheken können auf ein aktuelles Patch-Level angehoben werden

Eigenschaften der Standard-Distribution

Zur Betrachtung der Eigenschaften der Standard-Keycloak-Distribution verwenden wir das folgende Standard Keycloak Docker-Image: quay.io/keycloak/keycloak:18.0.0.

Ein Docker-Container mit dem Image kann dann auf die folgende Weise gestartet werden:

1docker run --rm -it quay.io/keycloak/keycloak:18.0.0 start \
2   --auto-build \
3   --http-enabled=true \
4   --hostname-strict=false \
5   --hostname-strict-https=false

Über den Parameter --auto-build weisen wir Keycloak dazu an, Build-time Konfiguration anzuwenden.

Aktivierte Extensions im Standard-Image

Das vorhergehende Kommando gibt folgende Liste aktivierter Quarkus Extensions (Keycloak Features) während des Keycloak-Serverstarts aus:

12022-05-07 10:44:39,393 INFO  [io.quarkus] (main) Installed features: 
2[agroal, cdi, hibernate-orm, infinispan-client, jdbc-h2, jdbc-mariadb, 
3jdbc-mssql, jdbc-mysql, jdbc-oracle, jdbc-postgresql, keycloak, 
4narayana-jta, reactive-routes, resteasy, resteasy-jackson, 
5smallrye-context-propagation, smallrye-health, smallrye-metrics, vault, 
6vertx]

Wir sehen hier, dass Keycloak standardmäßig Unterstützung für zahlreiche Datenbanken aktiviert: MSSQL, Oracle, MySQL, MariaDB, H2 (alte 1.x-Version mit vielen CVEs). Diese möchten wir im weiteren Verlauf auf eine einzige erforderliche Datenbank begrenzen: PostgreSQL.

Fehlende Extensions im Standard Image

Quarkus bietet ein breites Spektrum an Funktionalität, die über Quarkus Extensions aktiviert werden können. In der Keycloak-Distribution ist bereits eine Vorauswahl erfolgt.

Nach einem Weg, diese Funktionen zu aktivieren, wurde bereits auf in einer Keycloak Discussion gefragt und aus der Community gab es bereits eine Lösung dazu. Das dort beschriebene Vorgehen funktioniert, aber ist nicht im Maven Build automatisiert.

Gefundene Sicherheitslücken im Standard-Image

In unserem Beispiel verwenden wir das Tool trivy von Aquasec zum Scannen von Docker Images nach bekannten CVEs. Das Tool kann man bequem als Docker Container ausführen.

Wir verwenden hier einen kleinen Java-CLI Wrapper, um den Trivy scan auszuführen:

1java bin/scanImage.java 
2--image-name=quay.io/keycloak/keycloak:18.0.0

Ergebnis des Trivy Scans mit Standard-Keycloak-Docker-Image als Gist .

1quay.io/keycloak/keycloak:18.0.0 (redhat 8.5)
2=============================================
3Total: 104 (UNKNOWN: 0, LOW: 37, MEDIUM: 65, HIGH: 2, CRITICAL: 0)
4 
5Java (jar)
6==========
7Total: 5 (UNKNOWN: 1, LOW: 0, MEDIUM: 0, HIGH: 1, CRITICAL: 3)

Hinweis: Diese Ergebnisse verändern sich mit der Zeit:

• Neue Sicherheitslücken werden gefunden
• Das allgemeine CVE-Scoring ändert sich aufgrund neuer Erkenntnisse
• Es findet ein erneutes Release des Docker-Images mit aktualisierten OS-Komponenten statt

Eine eigene Distribution bauen

Um eine eigene Keycloak-Distribution mit den oben genannten Anpassungen zu bauen, kombinieren wir Teile der Keycloak.X-Server-Distribution mit der Keycloak-Quarkus-Server-Anwendung, die vom Keycloak-Projekt auch in der eigenen Distribution verwendet wird.
Dazu erstellen wir ein eigenes Maven-Projekt.
Über das Maven Dependency Management binden wir die Keycloak-Quarkus-Distribution als .zip Archiv ein. Dieses Archiv wird dann mit dem maven-dependency-plugin in das target-Verzeichnis entpackt, wobei wir das lib Verzeichnis der Distribution explizit ausklammern. Als nächsten Schritt wird die keycloak-quarkus-server Maven Dependency inkludiert, die es uns erlaubt, die Abhängigkeiten von der Keycloak-Quarkus-Server-Applikation anzupassen.

Um in der erzeugten Keycloak-Distribution weitere Konfigurationen hinterlegen zu können, wird über das maven-resources-plugin der Inhalt des Verzeichnisses
src/main/copy-to-keycloak über die entpackte Keycloak-Distribution kopiert.

Eine eigene Distribution können wir mit dem folgenden Kommando erzeugen:

1mvn clean package

Danach finden wir im Verzeichnis target/keycloak-18.0.0 unsere eigene Keycloak-Distribution, die bereits genutzt werden kann.

Extensions und Themes

Dieser Ansatz erlaubt auch die Nutzung von eigenen Extensions und Themes.
Im Beispiel haben wir einen eigenen Event Listener Provider sowie ein einiges „Custom“ Theme eingebracht.

Testing mit Keycloak-Testcontainers

Unsere eigenen Erweiterungen können mithilfe der Keycloak-Testcontainers-Bibliothek in der Form von Integrationstests automatisiert testen.
Der Einfachheit halber verwenden wir hier für die Tests das Standard-Keycloak-Docker-Image. Mit ein wenig zusätzlicher Konfiguration und Build-Orchestrierung könnte man hier auch das zuvor erstellte Custom Image verwenden.

Eigenes Docker Image

Die eigene Keycloak.X Distribution lässt sich analog zu dem Standard-Keycloak.X-Docker-Image in ein eigenes Docker Image einbringen. In unserem Beispiel verwenden wir hierzu das Maven Docker Plugin.

Den Docker Image build starten wir dann über folgendes Kommando:

1mvn clean package docker:build 
2-Ddocker.image=thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT

Nicht benötigte Quarkus Extensions entfernen

Keycloak verwendet zahlreiche Bibliotheken, die über Quarkus Extensions eingebunden werden. Je nach Umgebung werden einige von diesen Extensions nicht benötigt, z. B. wenn nur mit einer PostgreSQL-Datenbank gearbeitet wird, dann wird z. B. die Unterstützung für Oracle und andere Datenbanken nicht benötigt. In diesem Fall können Quarkus Extensions über entsprechende Maven Dependency Exclusions entfernt werden.

Wollen wir beispielsweise die Unterstützung für die Oracle Datenbank entfernen, so können wir folgende Exclusions auf die org.keycloak:keycloak-quarkus-server:18.0.0 Maven Dependency anwenden:

1<dependency>
2        <!-- Keycloak Quarkus Server Libraries-->
3        <groupId>org.keycloak</groupId>
4        <artifactId>keycloak-quarkus-server</artifactId>
5        <version>${keycloak.version}</version>
6        <!-- Exclude unused dependencies -->
7 
8        <exclusions>
9            ...
10            <!-- Exclude unused support for: Oracle -->
11                <exclusion>
12                    <groupId>com.oracle.database.jdbc</groupId>
13                    <artifactId>ojdbc11</artifactId>
14            </exclusion>
15            <exclusion>
16                    <groupId>io.quarkus</groupId>
17                    <artifactId>quarkus-jdbc-oracle</artifactId>
18            </exclusion>
19            <exclusion>
20                    <groupId>io.quarkus</groupId>
21                    <artifactId>quarkus-jdbc-oracle-deployment</artifactId>
22            </exclusion>
23            ...
24        </exclusions>
25    </dependency>

Mit dieser Technik lassen sich auch nicht benötigte vulnerable Bibliotheken entfernen.
So verwendet Keycloak derzeit standardmäßig eine alte 1.x-Version der H2-Datenbank, die von zahlreichen CVEs betroffen ist (Hinweis: Sobald Keycloak auf die neue Quarkus Version >2.8.2 aktualisiert wird, wird auch H2 auf eine neue Version 2.x ohne bekannte CVEs angehoben). Wenn man Keycloak jedoch stattdessen nur mit einer anderen Datenbank wie PostgreSQL verwendet, kann man auch die H2 Extension entfernen.

Um die Unterstützung für die H2 Datenbank zu entfernen, können wir folgende Maven Dependency Exclusions verwenden:

1<!-- Exclude unused support for: H2 -->
2<!-- Note: by default keycloak uses the h2 database as a database for 
3     auto-build. To remove h2, one needs to configure another Database 
4     in src/main/resources/META-INF/keycloak.conf →
5    <exclusion>
6         <groupId>com.h2database</groupId>
7         <artifactId>h2</artifactId>
8      </exclusion>
9      <exclusion>
10         <groupId>io.quarkus</groupId>
11         <artifactId>quarkus-jdbc-h2</artifactId>
12      </exclusion>
13      <exclusion>
14         <groupId>io.quarkus</groupId>
15         <artifactId>quarkus-jdbc-h2-deployment</artifactId>
16      </exclusion>

Zusätzlich muss dann in der Datei src/main/resources/META-INF/keycloak.conf
noch einen Eintrag wie db=postgres ergänzt werden, da sich ansonsten der Keycloak Distribution Build über die fehlende H2-Bibliothek beschwert.

Starten wir unsere so erzeugte Distribution als Docker-Container (siehe unten) mit folgendem Kommando …

1docker run --rm -it \
2    -p 8080:8080 \
3    -e KEYCLOAK_ADMIN=keycloak \
4    -e KEYCLOAK_ADMIN_PASSWORD=keycloak \
5    thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT \
6    start \
7   --auto-build \
8   --http-enabled=true \
9   --http-relative-path=auth \
10   --hostname-strict=false \
11   --hostname-strict-https=false \
12   --db=postgres \
13   --db-url-host=172.17.0.1\
14   --db-url-database=keycloak \
15   --db-username=keycloak \
16   --db-password=keycloak

… sehen wir in der Container Log-Ausgabe, dass die nicht benötigten Datenbank-Extensions verschwunden sind und nur noch jdbc-postgresql übrig geblieben ist.

12022-05-07 14:27:09,161 INFO  [io.quarkus] (main) Installed features: 
2[agroal, cdi, hibernate-orm, jdbc-postgresql, keycloak, narayana-jta, 
3reactive-routes, resteasy, resteasy-jackson, smallrye-context-propagation, 
4smallrye-health, smallrye-metrics, vault, vertx]

Weitere Extensions aktivieren und konfigurieren

Dieser Ansatz erlaubt es uns auch, neue weitere Quarkus Extensions für Keycloak zu nutzen. Als Beispiel wollen wir Unterstützung für zentralisiertes Logging mittels GELF in Keycloak aktivieren.

Dazu fügen wir unserem Maven-Projekt folgende Abhängigkeiten hinzu:

1<!-- Additional Quarkus Extensions: Begin -->
2 
3<dependency>
4    <groupId>io.quarkus</groupId>
5    <artifactId>quarkus-logging-gelf</artifactId>
6    <version>${quarkus.version}</version>
7</dependency>
8<dependency>
9    <groupId>io.quarkus</groupId>
10    <artifactId>quarkus-logging-gelf-deployment</artifactId>
11    <version>${quarkus.version}</version>
12</dependency>
13 
14<!-- Additional Quarkus Extensions: End -->

Wenn wir unsere Distribution damit bauen, wird das neue Quarkus GELF Extensions erkannt und entsprechend aktiviert.

Diese Quarkus-spezifischen Extensions kann man dann mittels der Datei quarkus.properties im conf Verzeichnis der Keycloak-Installation konfigurieren.

Eine Beispielkonfiguration in quarkus.properties für GELF:

1# Configure log streaming via gelf
2quarkus.log.handler.gelf.enabled=true
3quarkus.log.handler.gelf.host=localhost
4quarkus.log.handler.gelf.port=12201
5quarkus.log.handler.gelf.facility=iam

Starten wir unsere so erzeugte Distribution wieder als Docker-Container …

1docker run --rm -it \
2    -p 8080:8080 \
3    -e KEYCLOAK_ADMIN=keycloak \
4    -e KEYCLOAK_ADMIN_PASSWORD=keycloak \
5    thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT \
6    start \
7   --auto-build \
8   --http-enabled=true \
9   --http-relative-path=auth \
10   --hostname-strict=false \
11   --hostname-strict-https=false \
12   --db=postgres \
13   --db-url-host=172.17.0.1\
14   --db-url-database=keycloak \
15   --db-username=keycloak \
16   --db-password=keycloak

… so sehen wir, dass die gewünschte logging-gelf Extension von der Quarkus-Laufzeit erkannt wurde.

12022-05-07 14:27:09,161 INFO  [io.quarkus] (main) Installed features: 
2[agroal, cdi, hibernate-orm, jdbc-postgresql, keycloak, logging-gelf, 
3narayana-jta, reactive-routes, resteasy, resteasy-jackson, 
4smallrye-context-propagation, smallrye-health, smallrye-metrics, vault, 
5vertx]

Verwendete Bibliotheken patchen

Wie bereits erwähnt, sind für einige von der aktuellen Keycloak-Distribution verwendeten Java-Bibliotheken CVEs bekannt. Für manche dieser Bibliotheken existieren bereits kompatible Patch-Versionen. Mit dem gezeigten Ansatz lassen sich diese Bibliotheken einfach über Maven Dependency Management aktualisieren. Die neuen Dependency Versionen werden dann bei der Auflösung der Abhängigkeiten im Build der eigenen Keycloak Distribution entsprechend aktualisiert und auf das aktuellste (kompatible) Patch-Niveau gehoben.
Keycloak 18.0.0 enthält aktuell mehrere vulnerable Bibliotheken, beispielsweise eine Version der XStream-Bibliothek (1.4.18). Diese können wir über eine überschriebene Maven Dependency entsprechend aktualisieren.

1<dependencyManagement>
2  <dependencies>
3     <!-- CVE Patch overrides: Begin -->
4     <dependency>
5        <groupId>com.thoughtworks.xstream</groupId>
6        <artifactId>xstream</artifactId>
7        <version>1.4.19</version>
8     </dependency>
9   </dependencies>
10</dependencyManagement>

Hinweis: In unserem Beispiel auf GitHub haben wir alle CVEs erfolgreich durch Dependency Upgrades mitigieren können.
Hinweis: Da mit jeder neuen Keycloak-Version wieder neue Versionen von Bibliotheken einhergehen, ist es empfehlenswert, die überschriebenen Managed Dependencies nach einem Upgrade der Keycloak-Version wieder zu entfernen und einen neuen Image-Scan laufen zu lassen. Nach einem erneuten Image-Scan erhält man dann ggf. wieder eine neue Liste von vulnerablen Bibliotheken, die man dann auf dem gezeigten Weg wieder patchen kann.

Weitere Sicherheitslücken im Basis-Image

Durch entsprechende Dependency Upgrades und Dependency Exclusions können wir alle Java-Bibliotheken auf einen derzeit sicheren Stand bringen. Es werden keine CVEs mehr für Java-Bibliotheken gemeldet. Allerdings sind im ubi8-minimal Docker Image weiterhin vulnerable Komponenten enthalten.
Mit folgendem Kommando können wir den Docker-Image-Scan durchführen:

1java bin/scanImage.java 
2--image-name=thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT

Ergebnis des Trivy Scans mit custom ubi8-minimal Image als Gist .

1thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT (redhat 8.5)
2===========================================================
3Total: 104 (UNKNOWN: 0, LOW: 37, MEDIUM: 65, HIGH: 2, CRITICAL: 0)
4 
5Java (jar)
6==========
7Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Wenn wir auch die gemeldeten CVEs aus dem Basis-Image loswerden möchten, dann ist es eine Möglichkeit, das Basis-Image gegen eines ohne CVEs auszutauschen, beispielsweise Images auf Basis von Alpine. Das Image alpine:3.15.4 enthält laut Trivy-Scan derzeit keine bekannten CVEs.

Mit folgendem Kommando können wir ein Alpine-basiertes Docker image bauen:

1mvn clean package docker:build -Ddocker.file=keycloak/Dockerfile.alpine

Ein erneuter Scan des neuen Docker Images mit Trivy liefert dann erfreuliche Ergebnisse: 0 CVEs \o/.

1java bin/scanImage.java 
2--image-name=thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT

Ergebnis des Trivy-Scans mit Alpine Docker Image als Gist .

1thomasdarimont/custom-keycloakx:1.0.0-SNAPSHOT (alpine 3.15.4)
2==============================================================
3Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)
4 
5Java (jar)
6==========
7Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Abschluss

In diesem Artikel haben wir einen Ansatz zur Erstellung von eigenen Keycloak-Distributionen vorgestellt. Dieser Ansatz ermöglicht es, eigene Erweiterungen und Themes einfach mit auszuliefern, statt dies z. B. im Deployment zur Laufzeit vorzunehmen. Weiterhin können damit auch nicht benötigten Quarkus Extensions entfernt und auch neue Quarkus Extensions in Keycloak ergänzt werden.

Eine weitere Anpassungsmöglichkeit sind feingranulare Upgrades von Bibliotheken ohne bekannte Sicherheitslücken. Durch die zusätzliche Verwendung eines anderen Docker-Basis-Images konnten wir ein Docker Image mit einer Keycloak-Distribution erzeugen, die keine bekannten CVEs enthält.

Neben der höheren Sicherheit durch eine verringerte Angriffsoberfläche ist der Fußabdruck durch die reduzierte Menge von Extensions nochmals verbessert.

Dieser Ansatz erlaubt ein dynamisches Paketierung von Keycloak Distributionen gemäß der eigenen Anforderungen. Es wäre wünschenswert, dass das Keycloak-Projekt diesen oder einen ähnlichen Ansatz von Haus aus unterstützt, um sicherere und schlankere Keycloak-Installationen zu ermöglichen.

Das Beispiel zur Erzeugung einer eignen Keycloak Distribution findet man unter folgendem Link auf Github .
Im Branch keycloak-custom-server/zero-cves ist das Beispiel für unsere Scans enthalten.

Disclaimer

Keycloak ist ein komplexes Open-Source-Softwareprodukt, das sich auf eine Vielzahl an Bibliotheken stützt. Leider bleibt es dabei nicht aus, dass dafür auch CVEs bekannt werden – aber das ist bei jedem größeren Softwareprojekt so.
Wir freuen uns sehr über das erreichte Ziel: Keycloak einsetzen und dabei keine bekannten Sicherheitslücken auszuliefern. Vorherige Ansätze mit „Suchen“ auf dem Verzeichnis und anschließendem Löschen und Ersetzen von Bibliotheken hatten das gleiche Ziel, fühlten sich aber immer sehr fragil an und waren es auch. Wir hoffen, dass es weitere Fortschritte und Verbesserungsvorschläge zu dem gezeigten Ansatz gibt und freuen uns auf Feedback.

*) Null CVEs bezieht sich auf das Ergebnis des Image Scans mit Aquasec/Trivy und ist eine Momentaufnahme zum Zeitpunkt des Experiments. Ein Scan mit anderen Tools zu einem anderen Zeitpunkt könnte wieder neue CVEs zum Vorschein bringen, wenn neue CVEs bekannt werden. Wir empfehlen die Durchführung von kontinuierlichen Vulnerability Scans erzeugter Artefakte wie eigener Bibliotheken und Docker Images.