Zum Inhalt

Corewire

Keycloak-Setup

Schulungsumgebung und Keycloak-Setup

Ziel

In dieser Aufgabe lernen Sie den Umgang mit der Schulungsumgebung und erste Konfigurationsschritte in Keycloak. Sie verbinden sich mit dem über den Browser bereitgestellten VSCode, starten eine Keycloak-Instanz und konfigurieren diese. Am Ende legen Sie einen Realm an, erstellen einen Nutzer und überprüfen, ob sich der Nutzer in der Account-Konsole anmelden kann.

Hilfsmittel

Versuchen Sie, die unten stehenden Aufgaben mit Hilfe der Folien eigenständig zu lösen.
Sollten Sie dabei Probleme haben, finden Sie bei jeder Aufgabe einen ausklappbaren Block, in dem der Lösungsweg beschrieben wird.

Aufgabe 1 - Schulungsmaschine einrichten

Die Schulungsmaschinen sind unter code-{ZAHL}.labs.corewire.de zu erreichen. Ersetzen Sie {ZAHL} mit der Ihnen zugewiesenen Zahl.
Beispiel für die Zahl 5: code-5.labs.corewire.de.
Beispiel für die Zahl 11: code-11.labs.corewire.de.
Geben Sie danach das Ihnen zugewiesene Passwort ein.
Sie haben nun Zugriff auf die Schulungsmaschine.

Aufgabe 2 - Keycloak-Instanz starten

2.1: Direkter Start via docker run

In dieser Aufgabe möchten wir zunächst eine Keycloak-Instanz über docker run starten. Aufgrund der Schulungsumgebung im Browser sind dafür zusätzliche Schritte notwendig.

Legen Sie im Workspace eine Datei labels.txt mit folgendem Inhalt an:

traefik.enable=true
traefik.http.routers.keycloak.rule=Host(`keycloak.code-{ZAHL}.labs.corewire.de`)
traefik.http.services.keycloak.loadbalancer.server.port=8080

Ersetzen Sie {ZAHL}.
Diese Datei weist den Reverse-Proxy Traefik an alle Requests, die bei keycloak.code-{ZAHL}.labs.corewire.de eingehen an den Port 8080 weiterzuleiten. Im nächsten Schritt starten wir einen Keycloak-Container mit den Labels, sodass diese Instanz dann über die Domain erreichbar sein wird.

Starten Sie im Terminal eine Keycloak-Instanz mit folgendem Befehl:

docker run --name keycloak --rm --network=proxy --label-file labels.txt -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

Öffnen Sie einen neuen Tab im Browser und navigieren Sie zur URL Ihrer Keycloak-Instanz. Was passiert?

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

Keycloak ist über den Port erreichbar, die Seite läd jedoch nicht richtig.

Stoppen Sie den Container wieder mit Strg + C
Lösen Sie das Problem, sodass Sie sich in der Admin-Oberfläche anmelden können

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

Der Hostname ist nicht gesetzt, sodass Keycloak Resourcen über HTTP und nicht HTTPS einbindet. Der Browser verweigert üblicherweise das Laden von Resourcen im Mixed-Mode (HTTP+HTTPS gemischt).

Fügen Sie --hostname=<url> und --proxy-headers=xforwarded dem Command hinzu und starten Sie den Keycloak-Server erneut.

2.2: Docker Compose mit Postgres-Datenbank

Als nächstes sollen Sie die Keycloak-Instanz mit einer Postgres-Datenbank via Docker Compose starten.

Erstellen Sie im Workspace eine Datei docker-compose.yml
Fügen Sie eine Postgres-Datenbank mit User, Passwort und Datenbankschema hinzu

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

services:
    postgres:
        image: postgres
        environment:
            POSTGRES_USER: keycloak
            POSTGRES_PASSWORD: secret
            POSTGRES_DB: keycloak

Erweitern Sie die Datei mit der Keycloak-Instanz. Die zusätzlichen Angaben bzgl des Reverse-Proxy können Sie wie folgt einfügen:

services:
    keycloak:
        [...]
        labels:
        - "traefik.enable=true"
        - "traefik.http.routers.keycloak.rule=Host(`keycloak.code-{ZAHL}.labs.corewire.de`)"
        - "traefik.http.services.keycloak.loadbalancer.server.port=8080"
        networks:
        - default
        - proxy

networks:
    proxy:
        external: true

Starten (docker-compose up -d) und testen Sie die Keycloak-Instanz.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

services:
    postgres:
        image: postgres
        environment:
            POSTGRES_USER: keycloak
            POSTGRES_PASSWORD: secret
            POSTGRES_DB: keycloak
    keycloak:
        image: quay.io/keycloak/keycloak:latest
        environment:
            KC_BOOTSTRAP_ADMIN_USERNAME: admin
            KC_BOOTSTRAP_ADMIN_PASSWORD: admin
            KC_DB: postgres
            KC_DB_URL_HOST: postgres
            KC_DB_USERNAME: keycloak
            KC_DB_PASSWORD: secret
        command:
        - start-dev
        - "--hostname=https://keycloak.code-{ZAHL}.labs.corewire.de"
        - "--proxy-headers=xforwarded"
        depends_on: [ "postgres" ]
        labels:
        - "traefik.enable=true"
        - "traefik.http.routers.keycloak.rule=Host(`keycloak.code-{ZAHL}.labs.corewire.de`)"
        - "traefik.http.services.keycloak.loadbalancer.server.port=8080"
        networks:
        - default
        - proxy

networks:
    proxy:
        external: true

Aufgabe 3 - Realm und Nutzer konfigurieren

Nachdem Sie Keycloak erfolgreich gestartet haben, loggen Sie sich im Keycloak-Admin-Interface (Admin-Benutzer: admin / admin) ein und führen folgende Schritte durch:

Realm anlegen: Erstellen Sie einen neuen Realm, beispielsweise Schulung.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

Einen Realm können Sie in der Admin-Konsole links üben über die Realm-Auswahl erstellen.
Stellen Sie sicher, dass Sie nach Erstellung des Realms auch den neuen Realm ausgewählt haben.

Nutzer erstellen: Legen Sie in diesem Realm einen neuen Nutzer an, z. B. user, und definieren Sie ein Passwort.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

Im Menü-Punkt User können Sie neue Nutzer händisch anlegen.
Es ist nur der Username notwendig. Alle weiteren Angaben sind optional.
Wenn der Nutzer erstellt ist, müssen Sie über den Tab Credentials noch ein Passwort setzen.

Account-Konsole testen: Wechseln Sie in die Account-Konsole des neu erstellten Nutzers und melden Sie sich an, um die Funktion zu überprüfen.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)

Den Link zur Account-Konsole finden Sie in der Client-Liste.
Kopieren Sie den Link und öffnen Ihn in einem privaten Browser-Tab, sodass Sie im Admin-Menü als Admin eingeloggt bleiben können.

(Optional) Aufgabe 4 - Admin-Account

Falls Sie noch Zeit übrig haben, können Sie sich optional an folgender Aufgabe versuchen:

Wechseln Sie zurück in den Master-Realm.
Erstellen Sie einen neuen User mit Passwort.
Geben Sie diesem User Admin-Berechtigungen.
Loggen Sie sich mit dem neuen User ein
Löschen Sie den Bootstrap-Admin Account

Cleanup

Mit docker compose down können Sie die Datenbank und den Keycloak-Server stoppen. Dabei werden die Container aber auch gelöscht, sodass angelegte Realms und Nutzer verloren gehen.