Funktionalität

Alle neuen Applikationen werden über Keycloak abgesichert. Außerdem bietet Keycloak Nutzer- & Rollenverwaltung.

Architektur

Alle neuen Applikationen werden über Keycloak abgesichert. Damit benötigen alle neuen & teilweise auch alten Applikationen Zugriff zu Keycloak.

Keycloak benötigt eine eigene Datenbank.

Für eine möglichst einfache Umstellung empfehlen wir zunächst einen Parallelbetrieb in folgender Form:

• die bisherigen B2B (FSS) Knoten werden nicht modifiziert und kommunizieren nicht mit Keycloak. Sie dienen nur noch backendseitiger Nachrichtenverarbeitung ohne UI.
• für die NUI werden ein neuer B2B (FSS) Knoten installiert. Dieser wird auf Keycloak umgestellt. Die Applikationen der NUI kommunizieren ausschließlich mit diesem Knoten.

Es ist möglich, bestehende User aus der B2B nach Keycloak zu migrieren, oder alternativ ein bestehendes LDAP direkt an Keycloak anzubinden.

Voraussetzungen

• Docker ist einsatzbereit

Installation

docker-compose Umgebung

Das Setup der hier beschriebenen Umgebung basiert auf einem docker-compose file. Diese Konfiguration definiert einen Container.

Die docker-compose Umgebung besteht letztlich aus einer Verzeichnisstruktur, die die einzelnen im Folgenden beschriebenen Dateien enthält. Die Verzeichnisstruktur stellt sich wie folgt dar:

| base/
  |- keycloak/
  |  |- data/
  |- docker-compose.yml
  |- .env

Diese Dokumentation basiert auf der folgenden docker-compose.yml:

version: '3.7'
services:
  # Container-Definition für die keycloak-Instanz
  keycloak:
    image: ${NEXUS}/keycloak:2021-02-22
    restart: always
    hostname: keycloak
    ports:
      # Port unter dem der keycloak (auch von außen) erreichbar ist
      - ${KEYCLOAK_PORT}:8080
    environment:
      # Admin-Zugang für den keycloak
      - KEYCLOAK_USER=admin
      - KEYCLOAK_PASSWORD=admin
    volumes:
      # mount point für die keycloak DB
      - ./keycloak/data/:/opt/jboss/keycloak/standalone/data

Achten Sie beim image darauf, eine aktuelle Version gemäß unserer Kompatibilitätsübersicht anzugeben.

Die oben aufgeführte docker-compose.yml beinhaltet verschiedene Variablen “${Variable}”. Diese Variablen dienen der Auslagerung von speziellen Bedingungen. Diese Variablen sind in der Datei .env enthalten und werden während des Starts der Container via docker-compose angewendet. Für die oben aufgeführte docker-compose.yml sieht die .env wie folgt aus:

KEYCLOAK_PORT=8080
NEXUS=docker-nob-erf.next-level-apps.com

Keycloak Datenbank

Das obige Beispiel arbeitet mit einer integrierten H2-Datenbank. Diese speichert ihre Daten im Ordner data, vgl. Sie das entsprechende volume.

Wenn Sie stattdessen eine produktive Datenbank angeben möchten, können Sie die Datenbank-Zugangsdaten über Umgebungsvariablen in der docker-compose.yml konfigurieren. Für weitere Details vgl. Sie die Keycloak Image Doku. Bsp:

    environment:
      - DB_VENDOR=postgres
      - DB_ADDR=host.docker.internal
      - DB_DATABASE=keycloak
      - DB_USER=postgres
      - DB_PASSWORD=postgres

Des Weiteren muss dann der benötigte JDBC Treiber gemountet werden z.B so:

    volumes:
      - /opt/b2b/keycloak/ojdbc.jar:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver/ojdbc.jar

Falls Sie noch weitere Informationen nachlesen möchten, finden Sie hier eine detaillierte Beschreibung.

Keycloak-Konfiguration (Schnellstart)

Befolgen Sie die nachstehenden Schritte für den Schnellstart der Keycloak-Konfiguration:

Schritt 1: Laden Sie hier die Keycloak-Konfigurations-JSON-Datei herunter

Schritt 2: Importieren Sie die Keycloak-Konfigurations-JSON-Datei.

Schritt 3: Sie haben die Keycloak-Konfiguration erfolgreich eingerichtet.

HTTPS

Die Keycloak Authentifizierung erfolgt über OAuth2. Dieses Verfahren ist unbedingt über HTTPS abzusichern. Deshalb empfehlen wir, Keycloak & alle Applikationen der neuen UI mit HTTPS zu betreiben.

Start des Docker-Containers

Mit dem folgenden Kommando kann der benötigte Container im Docker gestartet werden:

:opt/docker/b2b/> docker-compose up -d

Mit folgendem Kommando kann der benötigte Container im Docker gestoppt werden:

:opt/docker/b2b/> docker-compose stop

Konfiguration in der Keycloak-Admin-Oberfläche

Konfiguration/Einrichtung des keycloak

Nachdem die Container im Docker gestartet wurden, muss nun noch der keycloak konfiguriert werden. Hier sind die folgenden Bereiche einzurichten:

• Realm
• Clients
• Roles
• Users

Diese Schritte werden im Folgenden zusammengefasst. Es sei hier auch auf die vollständige Keycloak-Konfiguration-Doku verwiesen.

Realm

Um die Kommunikation zwischen der New-UI und der B2B in Docker abzusichern, muss im keycloak zunächst ein Realm definiert werden. Hierzu ist der keycloak im Browser unter der URL “http://[keycloak-host]:8080” aufzurufen:

Nach einem Klick auf “Administration Console” kann man sich mit “admin/admin” anmelden und über “Add realm” den Realm “B2B” anlegen:

Der Realm “B2B” kennzeichnet den gesamten Applikationskontext. Dem Realm kann nun noch ein Name zugewiesen werden. Dieser Name (“Display name” bzw. “HTML Display name”) wird im Login-Formular angezeigt:

Folgende Werte können vergeben werden (frei anpassbar):

Clients

Innerhalb des neuen Realms “B2B” müssen jetzt die Applikationen angelegt werden, die sich innerhalb des Applikationskontextes authentifizieren dürfen. Diese s.g. Clients können unter der entsprechenden Menüfunktion erstellt werden:

Die Clients der jeweiligen Microservices & Frontends werden auf ihren jeweiligen Dokumentationsseiten beschrieben.

Die ClientId kann von Ihnen selbst gewählt werden, wir sprechen aber meist eine Empfehlung aus.

Die RootURL ist bei Frontends immer die Adresse des DockerHost-Servers samt Port. Bei Backends kann oft auch alternativ die interne Dockeradresse angegeben werden.

Das Client Protocol bleibt auf openid-connect gestellt.

Üblicherweise ist immer der Standardflow zu nutzen (standardmäßig aktiv).

Frontends wählen als Access Type public, Backends confidential. Manche Backends können auch auf Access Type bearer-only gestellt werden.

Als Login-Theme kann das nli Thema gewählt werden.

Roles

Die im keycloak definierten Roles werden nach einem Login an der entsprechenden Session des Nutzers gespeichert und dienen der Steuerung der zugreifbaren (B2B-Backend) bzw. anzeigbaren Inhalte (B2B-New-UI).

Alle in diesem Kapitel aufgeführten Rollen müssen wie im Folgenden dargestellt eingerichtet werden:

Eine vollständige Liste aller Rollen finden Sie hier.

Beim Anlegen der Rollen unterstützt auch das auf der nächsten Seite beschriebene Migrationstool.

Mandantenfilterung

Die neue UI unterstützt Mandantenfilterung mit Hilfe von Keycloak.

Mandanten werden innerhalb der B2B in der neuen Extension TENANTS gepflegt.

Einem User können ein oder mehrere Mandanten zugewiesen werden, indem die Mandanten innerhalb Keycloaks dem User als Attribute tenants zugewiesen werden.

Weitere Details zur Mandantenfilterung können Sie hier nachlesen.

Beim migrieren der Mandanten unterstützt auch das auf der nächsten Seite beschriebene Migrationstool.

Users

Damit man sich beim Aufruf der B2B-New-UI auch anmelden kann, muss zumindest ein Nutzer im keycloak hinterlegt werden. Dies kann unter dem Menüpunkt “Users” vorgenommen werden:

Zunächst wird wie im Folgenden dargestellt ein Testbenutzer angelegt:

Nach dem Klick auf “Save”, wird dessen Detailansicht im keycloak angezeigt. Um dem Nutzer die benötigten Rollen zuzuweisen, sind dieser unter dem entsprechenden Register auszuwählen und zuzuordnen:

Sie können dann folgende Möglichkeiten nutzen:

• sie nutzen das auf der nächsten Seite beschriebene Migrationstool um User aus der B2B-Datenbank nach Keycloak zu migrieren.
• Sie binden ihr LDAP an Keycloak an.
• Sie legen weiter manuell User in Keycloak an.

Mapper

Die Konfiguration des Keycloak-Mappers für den Client unter allen Benutzer ähnelt der des Clients b2b-function-ui und fss-ui hier.

Migration

Das auf der nächsten Seite beschriebene Migrationstool unterstützt beim Anlegen der Rollen sowie beim Migrieren der User & Mandanten.