# 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`