iqb-berlin · jurei733 · Oct 2, 2025 · Oct 9, 2025 · Nov 19, 2025 · Nov 19, 2025
diff --git a/.env b/.env
@@ -0,0 +1,51 @@
+## Version
+TAG=latest
+
+## Image Registry Path
+# Docker Hub:       (aka registry-1.docker.io/) leave REGISTRY_PATH value empty!
+# Docker Hub Proxy: scm.cms.hu-berlin.de:443/iqb/dependency_proxy/containers/
+# GitLab:           scm.cms.hu-berlin.de:4567/iqb/coding-box/
+REGISTRY_PATH=scm.cms.hu-berlin.de:443/iqb/dependency_proxy/containers/
+
+## Redis
+REDIS_PORT=6379
+
+## Database
+POSTGRES_PORT=5432
+POSTGRES_USER=root
+POSTGRES_PASSWORD=root-password
+POSTGRES_DB=coding-box
+
+## Backend
+API_PORT=3333
+JWT_SECRET=random_string
+AUTH_MODE=dev
+
+## Frontend
+HTTP_PORT=4200
+
+## Infrastructure
+SERVER_NAME=localhost
+
+# OpenID Connect (OIDC)
+OIDC_PROVIDER_URL=https://keycloak.kodierbox.iqb.hu-berlin.de
+OIDC_ISSUER=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box
+OIDC_ACCOUNT_ENDPOINT=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/account
+OIDC_AUTHORIZATION_ENDPOINT=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/protocol/openid-connect/auth
+OIDC_TOKEN_ENDPOINT=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/protocol/openid-connect/token
+OIDC_USERINFO_ENDPOINT=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/protocol/openid-connect/userinfo
+OIDC_END_SESSION_ENDPOINT=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/protocol/openid-connect/logout
+OIDC_JWKS_URI=https://keycloak.kodierbox.iqb.hu-berlin.de/realms/coding-box/protocol/openid-connect/certs
+OAUTH2_CLIENT_ID=coding-box
+OAUTH2_CLIENT_SECRET=
+OAUTH2_REDIRECT_URL=//localhost:3333/api/auth/callback
+
+# Keycloak
+## Realm Admin
+ADMIN_NAME=admin
+ADMIN_PASSWORD=change_me
+
+# Keycloak DB
+KEYCLOAK_DB_USER=keycloak
+KEYCLOAK_DB_PASSWORD=change_me
+KEYCLOAK_DB_NAME=keycloak
diff --git a/.env.coding-box.template b/.env.coding-box.template
@@ -9,7 +9,7 @@ REGISTRY_PATH=
 
 ## Database
 POSTGRES_USER=root
-POSTGRES_PASSWORD=root-password
+POSTGRES_PASSWORD=change_me
 POSTGRES_DB=coding-box
 
 ## Backend
@@ -20,3 +20,16 @@ JWT_SECRET=random_string
 ## Infrastructure
 SERVER_NAME=hostname.de
 TRAEFIK_DIR=
+
+# OpenID Connect (OIDC)
+OIDC_PROVIDER_URL=https://keycloak.${SERVER_NAME}
+OIDC_ISSUER=https://keycloak.${SERVER_NAME}/auth/realms/iqb
+OIDC_ACCOUNT_ENDPOINT=https://keycloak.${SERVER_NAME}/auth/realms/iqb/account
+OIDC_AUTHORIZATION_ENDPOINT=https://keycloak.${SERVER_NAME}/auth/realms/iqb/protocol/openid-connect/auth
+OIDC_TOKEN_ENDPOINT=https://keycloak.${SERVER_NAME}/auth/realms/iqb/protocol/openid-connect/token
+OIDC_USERINFO_ENDPOINT=https://keycloak.${SERVER_NAME}/auth/realms/iqb/protocol/openid-connect/userinfo
+OIDC_END_SESSION_ENDPOINT=https://keycloak.${SERVER_NAME}/auth/realms/iqb/protocol/openid-connect/logout
+OIDC_JWKS_URI=https://keycloak.${SERVER_NAME}/auth/realms/iqb/protocol/openid-connect/certs
+OAUTH2_CLIENT_ID=coding-box
+OAUTH2_CLIENT_SECRET=change_me
+OAUTH2_REDIRECT_URL=//${SERVER_NAME}/api/auth/callback
diff --git a/.env.dev.template b/.env.dev.template
@@ -19,6 +19,7 @@ POSTGRES_DB=coding-box
 ## Backend
 API_PORT=3333
 JWT_SECRET=random_string
+AUTH_MODE=dev
 # Optional override if GeoGebra changes the public bundle URL.
 # GEOGEBRA_BUNDLE_DOWNLOAD_URL=https://download.geogebra.org/package/geogebra-math-apps-bundle
 
@@ -27,3 +28,32 @@ HTTP_PORT=4200
 
 ## Infrastructure
 SERVER_NAME=localhost
+
+# OpenID Connect (OIDC)
+OIDC_PROVIDER_URL=http://${SERVER_NAME}:8080
+OIDC_ISSUER=http://${SERVER_NAME}:8080/realms/coding-box
+OIDC_ACCOUNT_ENDPOINT=http://${SERVER_NAME}:8080/realms/coding-box/account
+OIDC_AUTHORIZATION_ENDPOINT=http://${SERVER_NAME}:8080/realms/coding-box/protocol/openid-connect/auth
+OIDC_TOKEN_ENDPOINT=http://keycloak:8080/realms/coding-box/protocol/openid-connect/token
+OIDC_USERINFO_ENDPOINT=http://keycloak:8080/realms/coding-box/protocol/openid-connect/userinfo
+OIDC_END_SESSION_ENDPOINT=http://keycloak:8080/realms/coding-box/protocol/openid-connect/logout
+OIDC_JWKS_URI=http://keycloak:8080/realms/coding-box/protocol/openid-connect/certs
+OAUTH2_CLIENT_ID=coding-box
+OAUTH2_CLIENT_SECRET=change_me
+OAUTH2_REDIRECT_URL=//${SERVER_NAME}:${API_PORT}/api/auth/callback
+
+# Keycloak
+## Realm Admin
+ADMIN_NAME=admin
+ADMIN_PASSWORD=change_me
+
+# Keycloak DB
+KEYCLOAK_DB_USER=keycloak
+KEYCLOAK_DB_PASSWORD=change_me
+KEYCLOAK_DB_NAME=keycloak
+
+# Keycloak Backend Configuration
+KEYCLOAK_URL=http://${SERVER_NAME}:8080/
+KEYCLOAK_REALM=coding-box
+KEYCLOAK_CLIENT_ID=coding-box
+KEYCLOAK_CLIENT_SECRET=change_me
diff --git a/.gitignore b/.gitignore
@@ -49,6 +49,9 @@ docker.env
 .DS_Store
 Thumbs.db
 
+# Keycloak files
+config/keycloak/realm/coding-box-realm.config
+
 # Backend files
 auth.constants.ts
 database.constants.ts

diff --git a/README.md b/README.md
@@ -51,12 +51,39 @@ Stellen Sie sicher, dass die folgenden Tools auf Ihrem System installiert sind:
    cp .env.dev.template .env.dev
    ```
 
-2. Installieren Sie die Abhängigkeiten:
+2. Kopieren Sie die Vorlage der Keycloak-Realm-Konfiguration:
+
+   ```
+   cp config/keycloak/realm/coding-box-realm.config.template config/keycloak/realm/coding-box-realm.config
+   ```
+
+3. Ersetzen Sie den Shell-Befehl für den Timestamp durch einen numerischen Wert:
+
+   Öffnen Sie die Datei `config/keycloak/realm/coding-box-realm.config` und ersetzen Sie
+   `CODING_BOX_ADMIN_CREATED_TIMESTAMP=date --utc +"%s%3N"`
+   durch einen aktuellen Timestamp in Millisekunden, z.B.:
+   `CODING_BOX_ADMIN_CREATED_TIMESTAMP=1775907461877`
+
+4. Installieren Sie die Abhängigkeiten:
 
    ```
    npm install
    ```
 
+5. **Standard-Anmeldedaten für die Entwicklung**
+
+   Nach dem Start der Umgebung sind folgende Standard-Anmeldedaten verfügbar:
+
+   - **Keycloak Admin Console** (http://localhost:8080/admin):
+     - Benutzername: `admin`
+     - Passwort: `change_me`
+
+   - **Kodierbox Realm** (http://localhost:8080/realms/coding-box):
+     - Benutzername: `coding-box-admin`
+     - Passwort: `change_me`
+
+   **Wichtig:** Ändern Sie diese Passwörter nach dem ersten Login aus Sicherheitsgründen.
+
 ---
 
 ## Entwicklungsprozess
@@ -214,6 +241,30 @@ und geben Sie danach folgenden Befehl zum Hochfahren der Webanwendung ein:
 make coding-box-up
 ```
 
+## Authentication
+
+### Keycloak Auth Flow (OIDC + PKCE)
+
+Die Anwendung nutzt **Keycloak** als Identity Provider mit dem **OAuth2 Authorization Code Flow** und **PKCE**:
+
+1. **Login starten** (`GET /api/auth/login`): Backend erzeugt `state` und PKCE (`code_verifier`, `code_challenge`) und leitet zum Keycloak‑Login weiter.
+2. **Benutzer‑Login**: Nutzer meldet sich bei Keycloak an (Passwort, SSO, etc.).
+3. **Callback** (`GET /api/auth/callback`): Keycloak liefert `code` und `state` zurück.
+4. **Token‑Exchange**: Backend tauscht `code` gegen Tokens am Keycloak‑Token‑Endpoint, mit PKCE `code_verifier` (ohne Client‑Secret).
+5. **Userinfo**: Backend ruft User‑Profil via `userinfo`‑Endpoint ab.
+6. **User‑Persistenz**: Nutzer wird in der lokalen DB gespeichert (Identität über `sub`).
+7. **Token‑Weitergabe**: Backend leitet den Nutzer zur Frontend‑URL zurück und hängt `token`, `id_token`, `refresh_token` als Query‑Params an.
+8. **Frontend‑Session**: Frontend speichert Tokens in `localStorage` und lädt `auth-data` (Arbeitsbereiche).
+
+Details:
+- `state` enthält optional die Ziel‑URL (`redirect_uri`) und wird serverseitig geprüft.
+- PKCE‑Verifier wird serverseitig kurzzeitig gespeichert (TTL 5 Minuten).
+- API‑Requests senden den Access‑Token als `Authorization: Bearer <token>`.
+- Logout nutzt `POST /api/auth/logout` und invalidiert die SSO‑Session bei Keycloak.
+
+---
+
+## Additional Information
 Nachdem die Prozesse dieser Befehle beendet sind, ist der Edge-Router und das Monitoring aktiv, die Kodierbox
 Datenbank eingerichtet, die Kodierbox API und Web-Site ansprechbar.
 Ein Zugriff auf den Server über einen Browser sollte dann sofort möglich sein.