Keycloak Setup

IFS-Logo Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Die Referenzimplementierung 'Security' benötigt einen externen IAM-Service (IAM: Identity & Access Management), der die OIDC-konforme Authentifizierung und Autorisierung der in den Tests verwendeten Nutzer übernimmt. Zur Vereinfachung und Verfügbarkeit wird hierfür KeyCloak verwendet.

Dieses Dokument beschreibt die Installation eines lokalen KeyCloak und dessen Konfiguration für die Verwendung im IsyFact-Standard Baustein 'Security' allgemein und speziell für die Referenzimplementierung 'Security'.
Es richtet sich an Architekten und Entwickler von IsyFact-Anwendungen, die verstehen wollen, wie sie den IsyFact-Standard Baustein 'Security' in ihrer Anwendung verwenden und einbauen können.

1. Voraussetzungen

Bevor mit der Installation von KeyCloak begonnen wird, sind einige Voraussetzungen zu erfüllen:

1.1. Installation von Java

  • Java SDK: KeyCloak und die Referenzimplementierung benötigen beide Java 17. Wir empfehlen die Verwendung von Temurin-17 als JDK.

  • Language Level: Stellen Sie sicher, dass das Language Level passend zu den verwendeten IsyFact Standard Libraries (in diesem Fall 8) gesetzt ist. Dies ist möglich in IntelliJ unter Project Structure > Project Settings > Modules > Language Level.

1.2. Einrichten der Umgebungsvariablen unter Windows

  1. JAVA_HOME setzen:

    • Navigieren Sie zu der Systemsteuerung > Umgebungsvariablen für dieses Konto bearbeiten.

    • Erstellen Sie eine neue Systemvariable mit dem Namen JAVA_HOME und setzen Sie den Wert auf den Pfad Ihres JDK (zum Beispiel C:\Program Files\Eclipse_Adoptium\jdk-17).

  2. Path-Variable aktualisieren:

    • In den Umgebungsvariablen für dieses Konto, wählen Sie die Path-Variable und klicken Sie auf Bearbeiten.

    • Fügen Sie den Pfad zur bin-Direktory des JDK hinzu (zum Beispiel C:\Program Files\Java\jdk-17\bin).

Diese Schritte stellen sicher, dass Ihr System korrekt für die Ausführung von KeyCloak und die Verwendung der Referenzimplementierung vorbereitet ist.

2. KeyCloak-Setup

Dieser Abschnitt richtet sich an Architekten und Entwickler von IsyFact-Anwendungen, die KeyCloak in ihrer Entwicklungsumgebung installieren wollen - entweder, um die Referenzimplementierung 'Security' laufen zu lassen oder zur Einbindung in ihre Anwendung.

2.1. Download und Installation der KeyCloak-Software

Die aktuelle Version (und ältere) zum freien Download sowie Guides und Dokumentation findet sich unter https://www.keycloak.org/. Zur Erstellung der Referenzimplementierung 'Security' und des Konfigurations-Exports wurde die Version 24.0.3 von KeyCloak verwendet.

Zur Installation von KeyCloak reicht es, die heruntergeladene Datei (*.zip für Windows beziehungsweise *.tar.gz für Linux) in ein beliebiges Verzeichnis auszupacken. Darin sollte dann das Installationsverzeichnis 'keycloak-<Version zum Beispiel 24.0.3>' vorhanden sein.

2.2. Vorbereitung der Konfiguration für die Referenzimplementierung 'Security'

  1. Erstellen des 'tmp'-Verzeichnisses:

    • Im KeyCloak-Installationsverzeichnis (zum Beispiel C:\keycloak-24.0.3) erstellen Sie ein neues Verzeichnis zum Beispiel mit dem Namen tmp.

  2. Kopieren der Konfigurationsdatei:

    • Kopieren Sie die Datei ref-impl-isy-security.json, die unter dem Pfad isyfact-standards-referenzimplementierung-doc/resources/security/ref-impl-isy-security.json zu finden ist, in das soeben erstellte tmp-Verzeichnis.

2.3. Import der Konfiguration der Referenzimplementierung 'Security'

Die für die Referenzimplementierung 'Security' notwendige Konfiguration mit den verwendeten Nutzern, Clients und Rollen steht als Importdatei 'ref-impl-isy-security.json' zur Verfügung. Sie kann mit folgender Prozedur importiert werden:

  1. Bei einem Import über die Kommandozeile darf die KeyCloak-Instanz NICHT laufen! Siehe Starten und Stoppen des KeyCloak-Servers

  2. Windows-Terminal (zum Beispiel PowerShell, cmd) aufrufen und in das Verzeichnis der KeyCloak-Installation wechseln: cd <KeyCloak-Installationsverzeichnis>

  3. Die kopierte Konfigurationsdatei (*.json) aus dem 'tmp'-Verzeichnis importieren: .\bin\kc.bat import --file=.\tmp\ref-impl-isy-security.json
    ⇒ Überprüfen Sie die Log-Ausgabe auf mögliche Fehler. Beim Import wird ein eventuell existierendes gleichnamiges Realm überschrieben. Daher sollte ein solches Realm vorher gelöscht werden.

2.4. Export einer KeyCloak-Konfiguration (realm)

Die oben erwähnte Importdatei wurde nach folgender Prozedur erstellt (getestet mit KeyCloak Version 24.0.3):

Nachdem die Keycloak Anwendung gestartet wurde, kann die aktuelle KeyCloak-Konfiguration im Keycloak Client http://localhost:8989/ modifiziert werden. Diese Konfiguration kann dann exportiert werden.

  1. Bei einem Export über die Kommandozeile darf KeyCloak-Instanz NICHT laufen! Siehe Starten und Stoppen des KeyCloak-Servers

  2. Windows-Terminal aufrufen (zum Beispiel Powershell, cmd) und Wechsel in Verzeichnis der KeyCloak-Installation:
    cd <KeyCloak-Installationsverzeichnis>

  3. Realm 'ref-impl-isy-security' exportieren (als JSON-Datei, mit usern in derselben Datei):
    .\bin\kc.bat export --dir=.\tmp --realm=ref-impl-isy-security --users=realm_file
    ⇒ Im Verzeichnis 'tmp' wird die Datei 'ref-impl-isy-security-realm.json' erzeugt, die die Konfiguration des realm 'ref-impl-isy-security' enthält, sowie die darin angelegten User.

  4. Clean JSON export file:
    Wie in zum Beispiel https://howtodoinjava.com/devops/keycloak-script-upload-is-disabled/ beschrieben, kann die eben erzeugte Exportdatei nicht direkt zum Import verwendet werden, da darin enthaltene Javascript-Elemente seit KeyCloak-Version 18 nicht mehr importiert werden können, sondern der Import mit dem Fehler “Script upload is disabled” abbricht. Deshalb muss die Exportdatei bereinigt werden:

    1. IsyFactStandards-realm.json in Texteditor öffnen (zum Beispiel Editor, Notepad++)

    2. Alle Vorkommnisse von ‘authorizationSettings‘ suchen und kompletten Abschnitt löschen

      • inklusive vorher stehendes Komma (in der Zeile davor)

      • bis einschließlich schließender geschweifter Klammer.

    3. 'Gesäuberte' Exportdatei speichern (evtl. unter neuem Namen, mit Endung: .json)

    4. Die Exportdatei kann dann wie oben beschrieben importiert werden (mit angepassten Pfad zur Datei).

2.5. Starten und Stoppen des KeyCloak-Servers

Für den nicht-produktiven Einsatz, also zum Ausprobieren, Testen und zur Verwendung in der Anwendungsentwicklung, kann KeyCloak im sogenannten 'Development Mode' gestartet werden. In diesem Modus muss KeyCloak nicht weiter für die Umgebung konfiguriert werden, sondern läuft 'Out of the Box' mit einer integrierten H2-Datenbank.

Die Referenzimplementierung 'Security' erwartet, dass KeyCloak den HTTP-Port 8989 verwendet. Daher wird KeyCloak aus dem Installationsverzeichnis über die Kommandozeile gestartet mit dem Befehl: .\bin\kc.bat start-dev --http-port=8989

Beim ersten Start von KeyCloak werden finale Installations- und Konfigurationsschritte durchgeführt. Danach kann der Keycloak Client im Internet-Browser über die URL http://localhost:8989/ aufgerufen und die Keycloak Konfiguration angepasst werden. Beim ersten Start werden Sie aufgefordert einen Admin-Benutzer anzulegen (mit Name und Passwort). Weitere Details finden sich auch im 'Getting Started Guide' von keycloak.org.

Zum Stoppen von KeyCloak brechen Sie den laufenden Kommandozeilenprozess mit <Ctrl-C> (Windows) ab. Andernfalls kann es passieren, dass KeyCloak nicht sauber herunterfährt und nicht wieder gestartet werden kann. Es wurde festgestellt, dass sporadisch das Starten von KeyCloak Fehlermeldungen auftreten, falls eine VPN-Verbindung aktiv ist. Gegenfalls darum bitte die VPN-Verbindung trennen.

3. IsyFact-spezifische Konfiguration von KeyCloak

IsyFact Security erwartet einige Informationen an bestimmten Stellen in Access-Token:

Die IsyFact-Rollen (von IsyFact-Anwendungen) werden abgebildet als Realm roles. Wie im Konzept und den Nutzungsvorgaben des Bausteins 'Security' beschrieben, werden die IsyFact-Rollen in der jeweiligen IsyFact-Anwendung auf anwendungsspezifische und feingranulare Rechte abgebildet.

  • Die an den Benutzer (User / Client) vergebenen Rollen werden im (IsyFact-) Token Claim Name 'isyfact_roles' erwartet. Dafür muss in KeyCloak ein Client scope ('isyfact-roles') mit einem role mapper angelegt werden, der die Rollen des Benutzers auf den Token Claim Name 'isyfact_roles' des Access-Tokens abbildet.

Zur Vervollständigung des OpenID Connect Protokolls müssen im ID-Token und Access-Token bestimmte Informationen hinterlegt werden:

  • Die Spring-Security Implementierung eines OIDC-Clients prüft bei Erhalt eines Tokens, ob es auf ihn ausgestellt ist:
    Der Name des Clients, der das Token angefordert hat und auf den es ausgestellt ist, muss im Claim 'Audience' des Tokens stehen. Dafür muss in KeyCloak für jeden Client ein Client scope mit einem audience mapper angelegt werden, der den Namen / ID des (confidential- / service-) Client dort hinterlegt.

Diese Konfigurationen sind bereits in der Importdatei 'ref-impl-isy-security.json' enthalten. Es muss nichts weiter gemacht werden, wenn sie in KeyCloak importiert wurde.
Wenn jedoch KeyCloak und der IsyFact-Baustein 'Security' in eigenen Anwendungen verwendet wird, müssen die oben angegebenen Anpassungen an KeyCloak gemacht werden.