init

ai-context/AI-auth-vorgaben.md

@@ -0,0 +1,138 @@
+# Zitadel-Einrichtung – Schritt-für-Schritt
+
+Zitadel-Instanz: **https://id.vmlx.de**
+
+Ziel dieser Anleitung: Das OIDC-Projekt **kbcrm** anlegen, drei Testrollen definieren,
+drei Testnutzer erstellen, ihnen Rollen zuweisen und die Zitadel-User-IDs
+(`sub`-Werte) für das DB-Seeding ermitteln.
+
+---
+
+## Schritt 1 – Zitadel-Projekt anlegen
+
+1. Login unter https://id.vmlx.de
+2. Linke Navigation → **Projekte** → **Neu anlegen**
+3. Name: `kbcrm` → Speichern
+4. Im Projekt-Detail unter **Einstellungen** folgende Optionen aktivieren:
+   - ☑ **Assert Roles on Authentication** (Rollen werden in Token geschrieben)
+   - ☑ **Check Authorization on Authentication** (Zugriff nur für zugewiesene Nutzer)
+
+---
+
+## Schritt 2 – Rollen anlegen
+
+Im Projekt → Tab **Rollen** → drei Rollen anlegen:
+
+| Anzeigename | Schlüssel (Key) |
+|---|---|
+| Admin | `Admin` |
+| Mitarbeiter | `Mitarbeiter` |
+| Kunde | `Kunde` |
+
+> Der Schlüssel (Key) muss **exakt** so geschrieben sein – er erscheint so im Token-Claim.
+
+---
+
+## Schritt 3 – OIDC-Anwendung anlegen
+
+Im Projekt → Tab **Anwendungen** → **Neu anlegen**
+
+| Feld | Wert |
+|---|---|
+| Name | `kbcrm-web` |
+| Typ | **Web** |
+| Auth-Methode | **Code** (Authorization Code mit Client Secret) |
+
+Nach dem Erstellen:
+- **Client-ID** und **Client-Secret** notieren → kommen in die `.env`
+- Unter **Redirect-URIs** eintragen:
+  - `http://localhost:5000/auth/callback` (Lokal)
+  - `https://<deine-domain>/auth/callback` (Prod, falls zutreffend)
+- Unter **Post-Logout-Redirect-URIs** eintragen:
+  - `http://localhost:5000/`
+
+---
+
+## Schritt 4 – Testnutzer anlegen
+
+Navigation: **Nutzer** (oberste Ebene, nicht innerhalb eines Projekts) → **Neu anlegen**
+
+Drei Nutzer erstellen:
+
+| Name | E-Mail | Passwort | Zitadel-Rolle |
+|---|---|---|---|
+| Admin Test | admin@test.local | (eigenes PW) | Admin |
+| Mitarbeiter Test | ma@test.local | (eigenes PW) | Mitarbeiter |
+| Kunde Test | kunde@test.local | (eigenes PW) | Kunde |
+
+> Bei der Erstellung: **Passwort beim ersten Login ändern** deaktivieren empfohlen, damit Tests flüssig laufen.
+
+---
+
+## Schritt 5 – Rollen an Nutzer vergeben
+
+Für jeden Nutzer:
+
+1. **Nutzer** → Nutzer auswählen → Tab **Autorisierungen**
+2. → **Neu** → Projekt `kbcrm` wählen → entsprechende Rolle wählen → Speichern
+
+---
+
+## Schritt 6 – User-IDs (sub) ermitteln
+
+Die User-ID (Zitadel-`sub`) ist die interne Zitadel-Nutzer-ID, **nicht** die E-Mail.
+
+**Methode A – Zitadel-Konsole:**
+Nutzer auswählen → oben in der Detailansicht steht die **User-ID** (z. B. `236968807784841234`)
+
+**Methode B – Aus dem App-Log (nach Schritt 7):**
+Nach dem ersten Login loggt die App in stdout:
+```
+OIDC Login – sub: 236968807784841234 | email: admin@test.local | roles: ['Admin']
+```
+
+Alle drei Sub-Werte notieren für den nächsten Schritt.
+
+---
+
+## Schritt 7 – .env befüllen und DB seeden
+
+`.env` aus `.env.example` kopieren und befüllen:
+
+```bash
+cp .env.example .env
+```
+
+```env
+ZITADEL_CLIENT_ID=<Client-ID aus Schritt 3>
+ZITADEL_CLIENT_SECRET=<Client-Secret aus Schritt 3>
+ZITADEL_DISCOVERY_URL=https://id.vmlx.de/.well-known/openid-configuration
+SECRET_KEY=<zufälliger langer String>
+```
+
+Dann in `app/__init__.py` die Platzhalter in `seed_db()` mit den echten Sub-Werten ersetzen:
+
+```python
+ADMIN_ID       = "236968807784841234"   # <-- echte Zitadel-User-ID
+MITARBEITER_ID = "..."
+KUNDE_ID       = "..."
+```
+
+Anschließend seeden:
+
+```bash
+source venv/bin/activate
+flask seed-db
+```
+
+---
+
+## Discovery-URL verifizieren
+
+```bash
+curl https://id.vmlx.de/.well-known/openid-configuration | python3 -m json.tool
+```
+
+Wenn die Antwort ein JSON mit `issuer`, `authorization_endpoint` usw. ist, ist die URL korrekt.
+Sollte die URL nicht funktionieren, alternative probieren:
+`https://id.vmlx.de/oauth/v2/.well-known/openid-configuration`