Keycloak - ein Authentication-Server für alle Fälle

Achtung: Dieser Beitrag ist nur bis Version 17 aktuell, danach wird auf Quarkus gesetzt und damit ist der Customization-Part und Konfiguration komplett verändert worden!

Heute geht es um Keycloak - ein Authentication-Server von JBoss. Warum gerade Keycloak der Authentication Server meiner Wahl ist, und warum er so flexibel ist erfährst du im folgenden Blog-Post. Grundsätzlich bist du hier richtig wenn du auf der Suche nach einem OAuth2 oder SAML-Provider bist und dich hierbei nicht auf die großen Anbieter verlassen, oder eine eigene Zwischenschicht errichten willst.

Hierbei gibt es auch einen kleinen Quick Start Guide für das Customizing, sowie das Getting Started für die ersten Schritte mit Keycloak.

Architektur und grober Überblick

Keycloak ist unter der Haube eine Web-Application die auf einem WildFly Application Server deployt wird. Als Persistence Layer kommt dann Postgres, MySQL oder seit Neuestem Oracle zum Einsatz. Hierbei bietet Keycloak OIDC-Konformität, aber auch die Unterstützung von SAML. Das ermöglicht die bereits genannte Nutzung für OAuth2 oder eben SAML.

Benutzeroberfläche und -erfahrung

Keycloak bringt von Haus aus eine Benutzeroberfläche mit, die sehr übersichtlich und aufgeräumt wirkt. Im Folgenden gebe ich kurz einen Überblick über die wichtigsten Features und die entsprechende Oberfläche.

Realm konfigurieren

Keycloak arbeitet mit sogennanten Realms, das sind Namespaces in denen jeweils Konfigurationen, Themes etc. koexistieren können. Standardmäßig gibt es den master, dieser ist der Standard Realm, den auch Keycloak für die Admin-UI etc. nutzt.

Hier lässt sich wie im Screenshot zu sehen auch der Anzeigename von Keycloak anpassen. Die Endpoints für die Selbstkonfiguration für SAML und OIDC befinden sich unterhalb, diese lassen sich anklicken und führen direkt zur Konfiguratons-URL.

Themes und Sprachen

Um das Aussehen und die unterstützten Sprachen anzupassen, einfach zu Themes wechseln, dort lassen sich eigene Themes auswählen und die Sprachen anpassen.

Clients

Clients sind ein zentrales Element für Keycloak. Clients sind gleichzusetzen mit Anwendungen, die Rechte vom Nutzer verlangen. Diese lassen sich ziemlich komfortabel über den Reiter Clients verwalten.

Clients anlegen

Egal welchen Typ von Client man anlegen möchte, die Startmakse ist immer die Gleiche. Dazu einfach in der Übersicht oben Rechts auf Erstellen oder Create klicken. Dann gelangt man zu folgender Maske:

Hier den Namen der Anwendung bei Client-ID eintragen und auf Speichern|Save klicken.

Quittiert wird das mit dem Sprung zum fertig erstellten Client:

Ich gehe im Folgenden kurz auf alle unterstützen Typen von Clients und deren Basiskonfiguration ein. Hierbei kümmere ich mich nur um OIDC und nicht um SAML.

public

Ein Public-Client findet meistens in Webanwendungen Verwendung, er benötigt keine Secrets etc., sondern dient nur dazu den Consent des Users entgegenzunehmen. Dieser unterstützt den typischen OAuth2-Flow.

Hierbei sind folgende Konfigurationen wichtig:

• Valid Redirect URIs: Hier trägst du alle URLs ein, auf denen deine Webanwendung verfügbar ist. Wenn du alles zulassen willst, trägst du hier ein Asterisk ein. Aber Vorsicht: Wenn jemand deinen Client bei sich einbindet, kann er alle Nutzer abfangen und ihre Token abgreifen! Überlege dir also sehr gut, was du hier zulässt!
• Web Origins: Hier trägst du am besten die selben URLs ein wie bei Valid Redirect URIs, diese legen fest von welchen Adressen du z. B. auf die Benutzerinfos zugreifen darfst, um Username, Email etc. anzuzeigen.

Wenn das alles passiert ist, kannst du Keycloak an deine Web-App anbinden, das geht mit keycloak-js oder jso.

bearer-only

Ein Client mit bearer-only stellt einen Webservice bzw. eine Rest-API dar, er hat keine Benutzerinteraktion und erwartet JWTs. Diesen Token validiert er entsprechend beim Request gegen den Keycloak um sicher zu stellen, dass der ausgestellte Token auch zulässig und ordungsgemäßg signiert ist.

Dafür stellst du den Acess Type auf bearer-only. Das genügt bereits, jetzt musst du nur noch die Anbindung an dein Backend realisieren. Hierfür gibt es diverse Integrationen, welche in der Doku zu finden sind.

confidential

Ein Client der mit confidential markiert ist, benötigt keinerlei Benutzerinteraktion. Das kann z. B. ein Batch-Job oder eine Anwendung sein die via Authentication Proxy wie z. B. keycloak-gatekeeper abgesichert ist.

Auch hier müssen wieder die Valid Redirect URIs und die Web Origins ausgefüllt werden.

Nachdem wir ja ohne Benutzerinteraktion arbeiten benötigen wir ein Secret, das nur Keycloak und die Anwendung weiß, dieses wird nach einem Klick auf Speichern|Save sichtbar. Zu finden unter dem Reiter Passwörter|Secrets:

Dieses Secret sollte NIEMALS öffentlich sichtbar sein und ist wie ein Passwort zu behandeln. Eine Rollierung des Secrets ist an der Stelle auch sehr zu empfehlen.

Berechtigungen

Um den Benutzern entsprechend Rollen zuweisen zu können, die sie an bestimmten Clients haben, müssen wir diese erst anlegen. Gehe dazu auf einen Client deiner Wahl und gehe unter den Reiter Rollen. Hier findest du eine Übersicht an Rollen zu deinem Client.

Dann auf Rolle hinzufügen oben rechts.

Anschliessend kannst du den Namen der Rolle sowie eine kurze, menschenlesbare Beschreibung eintragen:

Fertig! - Dein Client hat eine Rolle!

Gruppen

Um verschiende Rollen von Clients zu bündeln nutzt Keycloak Gruppen, sie sind eine Sammlung von Client-Roles. Zu finden unter dem Tab Gruppen, dort wieder analog wie bei den Clients anlegen. Hier wird nur ein Name abgefragt:

Unter dem Reiter Rollenzuweisungen kannst du entsprechend deinen Client auswählen und der Rolle die Client-Roles zuweisen:

Benutzer

Um Benutzer anzulegen navigiere einfach zu Benutzer. Die Steuerung folgt wieder dem selben Schema analog zu den Clients und Roles.

Um Benutzern Gruppen zuzuweisen gehst du zum Tab Gruppen:

Hier siehst du die Gruppen in denen der Nutzer Mitglied ist, in diesem Falle Entwickler. Hier könntest du z. B. noch die Gruppe Test zuweisen, dazu die Gruppe rechts anklicken und auf Beitreten klicken.

Um Benutzern Rollen zuzweisen funktioniert das ganze analog zu den Gruppen, nur unter dem Tab Rollenzuweisungen.

Anbindung von externen Identity Providern wie GitHub, Twitter etc.

Wenn du deinen Keycloak nutzen möchtest, aber z. B. immer bei GitHub sowieso schon angemeldet bist, kannst du die Anmeldung kombinieren. Dann musst du dich nicht mehr explizit mit deinen Zugangsdaten bei Keycloak anmelden, ein Klick auf den Identity Provider genügt.

Das Anlegen funktioniert hierbei unter dem Tab Identity Providers

Die Auswahl geht hier von bekannten Anbietern, die vorkonfiguriert sind, bis hin zu anderen OIDC oder SAML kompatiblen Anbietern. Nachdem diese konfiguriert sind, findest du sie auf der Login-Seite der entsprechenden Anwendung:

Das ist natürlich nicht alles

Keycloak ist viel mächtiger und kann gerade "zu Tode" konfiguriert werden. Da die Möglichkeiten der Konfiguration genauso komplex und vielfälig sind, wie die Konfiguration selbst spare ich das an dieser Stelle aus.

Solltest du jedoch hier Hilfe benötigen, kann ich jedoch gerne untersützten. Schreib dazu einfach einen Kommentar oder eine Mail! :)

Customizing

Wie bereits angesprochen lässt sich Keycloak mehr oder weniger einfach customizen.

Themes

Keycloak lässt sich mit Themes erweitern. Am besten nutzt man hierfür die bestehenden Themes als Basis, diese finden sich in /opt/jboss/keycloak/themes.

An dieser Stelle ist Vorsicht geboten: Durch das ein oder andere Upgrade kann das Theme inkompatibel werden und so die Login-Seite in eine 500 - Internal Server Error Page verwandeln. Also unbedingt vorab lokal oder auf einem Testsystem ausprobieren, bevor es zu bösen Überraschungen kommt.

Plugins

Ein Plugin kann bei Keycloak die Interna erweitern. Eine wirklich gute Dokumentation hierzu habe ich bislang noch nicht gefunden. An dieser Stelle hilft der Server Developer Guide zwar um die Konzepte zu verstehen, jedoch fehlt der Zusammenhang zu konkreten Beispielen bzw. Example Projekten. Das mag für EE-Developer anders sein, ich bin jedoch ein ziemlicher Verfechter des ganzen EE-Ökosystem und fühle mich deshalb hier auch nicht sonderlich zuhause.

Aus eigener Erfahrung kann ich jedoch sagen, dass Keycloak hier extrem auf das Java Service Provider Interface setzt. So muss für jedes Interface bzw. Service der implementiert wird, entsprechend spezifiziert werden, welche Klasse welchen Service bereitstellt.

Interne Abhängigkeiten werden hierbei mit der XML-File jboss-deployment-structure.xml modelliert:

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.keycloak.keycloak-services"/>
            <module name="org.apache.httpcomponents"/>
            <module name="org.glassfish.javax.json" />
            <module name="org.apache.commons.lang" />
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Wie im Beispiel oberhalb werden so alle Abhängigkeiten entsprechend aufgelistet. Passiert das nicht, hat man auch keinen Zugriff auf diese Pakete.

Bei der Entwicklung von Plugins kann Hot-Reload verwendet werden, das ganze wird automatisiert von WildFly gehandelt und sorgt für einen sehr angenehmen Entwicklungszyklus.

An dieser Stelle ist es auch noch hilfreich, zu erwähnen, dass es Möglichkeiten gibt via Remote-Debugging auch Plugins in Keycloak zu debuggen. Hierzu muss, via Docker an den Entrypoint das Argument --debug angehängt werden, sowie der Port 8787 für den Debugger freigegeben werden.

Betrieb

Es gibt unterschiedliche Möglichkeiten Keycloak zu betreiben. Im Folgenden ein kurzer Überblick.

Nativ auf dem OS

Grundsätzlich lässt sich Keycloak als Archiv einfach auf der Download-Page runterladen, entpacken und ausführen. Das heißt Keycloak läuft ohne Seperierung vom Host direkt auf der entsprechenden Maschine.

Die Konfiguration erfolgt in diesem Falle über die XML-Files. Die Plugins, Themes usw. werden hier direkt in die entsprechenden Ordner kopiert.

Docker

Keycloak lässt sich auch sehr bequem via Docker betreiben. Hierfür gibt es ein entsprechendes Docker-Image (jboss/keycloak). Dieses beinhaltet einen WildFly, sowie das entsprechende Keycloak-Deployment. Der große Vorteil ist in diesem Fall, dass sich ein Upgrade relativ simpel durchführen lässt, indem einfach die neue Version des Image verwendet wird, die entsprechenden Datenbankmigrationen übernimmt hierbei die Anwendung selbst. Keycloak ist hierbei in seinem isolierten Docker-Container und hat keinen direkten Zugriff auf den Host bzw. das darunterliegende OS.

Die grundlegende Konfiguration erfolgt über Umgebungsvariablen. Themes, Plugins usw. können entsprechend bequem mit Volumes in den Container gebracht werden.

Kubernetes

Wenn Keycloak hochverfügbar sein soll, lohnt sich ein Blick auf Kubernetes. Dieses bietet uns bereits sehr fortgeschrittene Features, wie Checks auf Verfügbarkeit und Health der Anwendung, sowie die automatische Verteilung von verschiedenen Keycloak-Instanzen auf verschiedene Knoten. Hierfür gibt es ein Helm-Chart von codecentric, welches exzellent funktioniert, und bereits alles enthält was Keycloak benötigt.

Die Konfiguration des Deployments etc. erfolgt dabei wie bei Helm üblich durch die values.yaml Datei, diese enthält alle Konfigurationen. Der große Vorteil ist hierbei, dass bereits Postgres sowie die Healthchecks etc. integriert sind. Das Monitoring lässt sich so relativ leicht mit Kubernetes-Boardmitteln und dem Ökosystem lösen.

Kurzes Résumé

Ich empfehle Docker für kleine Installationen die keine HA benötigen via docker-compose zu launchen. Sobald Keycloak hochverfügbar sein soll kommt man um Kubernetes kaum herum. Eine Beispiel docker-compose.yml findest du auch in diesem gist.

Backup

Ein Aspekt den man bei solchen Systemen gerne vergisst, ist das Backup.

Keycloak bietet hier die Möglichkeit Realms als JSON-File zu exportieren, davon rate ich als Backup allerdings sehr dringend ab. Aus eigener Erfahrung gehen hier bei Service Accounts Secrets verloren oder manche Daten werden gar nicht richtig zurückgespielt.

Der sicherste Weg um Keycloak zu sichern ist die Datenbank, die Keycloak nutzt zu sichern. In Kombination mit Docker oder Kubernetes ist das eine gut bewährte Strategie. Auch für Upgrades lohnt es sich den Dump zu ziehen, in eine neue Datenbank zu schieben und mit dieser Keycloak in einer zweiten Instanz hochzufahren und zu betreiben.

Persönliche Erfahrungen

Ich setze nun privat schon seit gut 2 Jahren Keycloak ein, beruflich setzen wir nun schon seit gut mehr als 3 Jahren auf Keycloak. An sich bietet die Plattform alles, was man sich von einem Authentication Server wünscht.

Kritikpunkte sind jedoch die fehlenden Beispiele für Extensions und die doch relativ kleine Community. Oft muss man sich durch Maillisten hangeln um seine Lösung zu finden. Das Upgrade von Keycloak gestaltet sich relativ stressfrei, jedoch empfehle ich in jedem Falle eine neue Version immer komplett getrennt zu starten und zu verifizieren. Ein gutes Stichwort an der Stelle ist hier das Blue-Green-Deployment.

Keycloak ist ein sehr mächtiges Tool, das so im selbstgehosteten Bereich nach seines gleichen Sucht. Auch wenn es zum Aufsetzen und Verstehen hin und wieder eine Diva ist, läuft es doch ziemlich stabil und zuverlässig.