keycloak

temp/KEYCLOAK_CLIENT_ANLEGEN.md

@@ -0,0 +1,158 @@
+# Keycloak Client Anlegen
+
+Diese Schritte legen den Client fuer `desktop.kusche.berlin` in Keycloak an.
+
+## Ziel
+
+Wir brauchen einen eigenen OpenID-Client fuer die Desktop-Shell, damit:
+
+- der Login ueber Keycloak laeuft
+- der Ruecksprung sauber auf `desktop.kusche.berlin` erfolgt
+- spaeter ein eigenes Login-Theme fuer diesen Client genutzt werden kann
+
+## Vorab benoetigte Daten
+
+Vor dem Anlegen solltest du diese Werte kennen:
+
+- Keycloak Basis-URL
+  - Beispiel: `https://auth.kusche.berlin`
+- Realm-Name
+  - Beispiel: `kusche-berlin`
+- Staging-Domain
+  - Beispiel: `https://desktop-staging.kusche.berlin`
+- Live-Domain
+  - Beispiel: `https://desktop.kusche.berlin`
+
+## Client anlegen
+
+1. In Keycloak einloggen.
+2. Den passenden Realm auswaehlen.
+3. `Clients` aufrufen.
+4. `Create client` klicken.
+
+## Grunddaten
+
+Diese Werte setzen:
+
+- `Client type`: `OpenID Connect`
+- `Client ID`: `desktop-kusche-berlin`
+- `Name`: `Desktop Kusche Berlin`
+- `Description`: `Desktop Shell Login fuer Kusche.Berlin`
+
+Dann `Next`.
+
+## Capability config
+
+Diese Werte setzen:
+
+- `Client authentication`: `On`
+- `Authorization`: `Off`
+- `Standard flow`: `On`
+- `Direct access grants`: `Off`
+- `Implicit flow`: `Off`
+- `Service accounts roles`: `Off`
+
+Dann `Next`.
+
+## Login config
+
+Diese Werte setzen:
+
+- `Root URL`:
+  - Staging zuerst: `https://desktop-staging.kusche.berlin`
+- `Home URL`:
+  - `https://desktop-staging.kusche.berlin/`
+- `Valid redirect URIs`:
+  - `https://desktop-staging.kusche.berlin/auth/callback`
+  - spaeter zusaetzlich live:
+  - `https://desktop.kusche.berlin/auth/callback`
+- `Valid post logout redirect URIs`:
+  - `https://desktop-staging.kusche.berlin/`
+  - spaeter zusaetzlich live:
+  - `https://desktop.kusche.berlin/`
+- `Web origins`:
+  - `https://desktop-staging.kusche.berlin`
+  - spaeter zusaetzlich live:
+  - `https://desktop.kusche.berlin`
+
+Dann `Save`.
+
+## Client Secret holen
+
+Nach dem Speichern:
+
+1. Den neuen Client oeffnen.
+2. Auf `Credentials` gehen.
+3. Das generierte Secret kopieren.
+
+Dieses Secret bitte noch nicht ins Repo schreiben.
+
+## Optional aber sinnvoll
+
+Diese Einstellungen danach noch pruefen:
+
+- `Login theme`
+  - spaeter auf das eigene Desktop-Theme setzen
+- `Consent required`
+  - `Off`
+- `Display on consent screen`
+  - `Off`
+
+## Werte fuer unser Projekt
+
+Nach dem Anlegen brauchen wir diese finalen Werte:
+
+- `base_url`
+  - Beispiel: `https://auth.kusche.berlin`
+- `realm`
+  - Beispiel: `kusche-berlin`
+- `client_id`
+  - `desktop-kusche-berlin`
+- `client_secret`
+  - aus `Credentials`
+
+## Danach im Projekt eintragen
+
+Die Werte kommen danach in eine Umgebungsdatei, nicht in die allgemeine Basisdatei.
+
+Geplant ist:
+
+- `config/staging/keycloak.php`
+- `config/prod/keycloak.php`
+
+Beispielstruktur:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+return [
+    'enabled' => true,
+    'enforce_login' => true,
+    'allow_desktop_preview' => false,
+    'base_url' => 'https://auth.kusche.berlin',
+    'realm' => 'kusche-berlin',
+    'client_id' => 'desktop-kusche-berlin',
+    'client_secret' => 'HIER_DAS_SECRET',
+    'redirect_path' => '/auth/callback',
+    'scopes' => ['openid', 'profile', 'email'],
+];
+```
+
+## Wichtig
+
+- `client_secret` gehoert nicht in `config/keycloak.php`
+- nur in `config/staging/keycloak.php` bzw. `config/prod/keycloak.php`
+- wenn Staging und Live unterschiedliche Keycloak-Clients bekommen sollen, dann je Umgebung eigene `client_id` und eigenes Secret nutzen
+
+## Rueckmeldung an Codex
+
+Wenn der Client angelegt ist, brauche ich von dir nur:
+
+- `base_url`
+- `realm`
+- `client_id`
+- ob Staging und Live denselben Client nutzen sollen oder getrennte Clients
+
+Das Secret musst du mir nicht im Chat schicken, wenn du es lieber direkt lokal in die Env-Datei eintragen willst.