Zitadel (/zitadel)

Endpointy pro integraci se Zitadel OIDC providerem — webhooky, OIDC login flow a správu organizací.

---

Webhooky

POST /zitadel/webhook — Zitadel Action webhook

Přijímá webhooky od Zitadelu při událostech uživatele. Autentizace pomocí X-Webhook-Secret headeru.

POST /api/zitadel/webhook
X-Webhook-Secret: <webhook-secret>
Content-Type: application/json

Podporované události

Událost	Akce
user.created	Vytvoří uživatele v DB (pokud neexistuje)
user.deactivated	Nastaví active = false
user.reactivated	Nastaví active = true
user.removed	Smaže uživatele z DB

Request body (od Zitadelu)

{
  "event": "user.created",
  "data": {
    "email": "novy.uzivatel@firma.cz",
    "firstName": "Jan",
    "lastName": "Novák"
  }
}

Konfigurace v Zitadelu

V Zitadelu nakonfigurujte Action:

1. Přejděte do Actions → Flows → External Authentication
2. Přidejte Action pro každou událost
3. Nastavte Target URL: https://api.atrea.eu/api/zitadel/webhook
4. Nastavte X-Webhook-Secret na hodnotu z config.zitadel.webhookSecret

---

Health & Discovery

GET /zitadel/health

Ověří dostupnost Zitadel instance.

GET /api/zitadel/health

Response

{
  "success": true,
  "data": {
    "zitadelUrl": "https://admin.kagb.cloud",
    "status": "ok"
  }
}

GET /zitadel/discovery

Vrátí OIDC discovery dokument ze Zitadelu.

GET /api/zitadel/discovery

---

OIDC Login Flow (PKCE)

Plný OIDC Authorization Code Flow s PKCE pro bezpečné přihlášení.

GET /zitadel/login — start login

Přesměruje uživatele na Zitadel login stránku.

GET /api/zitadel/login?client_id=portal-app

Parametr	Povinné	Popis
client_id	✓	OIDC client ID aplikace v Zitadelu

Odpověď: 302 Redirect na Zitadel login stránku s PKCE parametry.

GET /zitadel/callback — OIDC callback

Zpracuje callback od Zitadelu, vymění auth code za token.

GET /api/zitadel/callback?code=<authCode>&state=<state>

Po úspěšné výměně přesměruje na frontend s tokenem.

Login flow — diagram

Uživatel klikne "Přihlásit"
    │
    ▼
GET /api/zitadel/login?client_id=portal-app
    │
    ├─ Generuje PKCE (code_verifier + code_challenge)
    ├─ Uloží state + verifier do session
    └─ Redirect → Zitadel login stránka
                      │
                      ▼
             Uživatel se přihlásí
                      │
                      ▼
GET /api/zitadel/callback?code=xyz&state=abc
    │
    ├─ Ověří state (CSRF ochrana)
    ├─ Vymění code za access_token (PKCE verifier)
    └─ Redirect na frontend s tokenem

---

Správa organizací (SuperAdmin)

Viz Admin endpointy pro detaily.

Stručný přehled:

# Seznam organizací
GET /api/zitadel/admin/orgs

# Vytvoření organizace
POST /api/zitadel/admin/orgs
{ "name": "Firma s.r.o.", "domain": "firma.cz" }

# Nastavení brandingu
PUT /api/zitadel/admin/orgs/:orgId/branding
{ "primaryColor": "#E91E63", "logoUrl": "..." }

# Kompletní setup (projekt + OIDC app)
POST /api/zitadel/admin/orgs/:orgId/setup
{
  "projectName": "Firma Portal",
  "appName": "Portal",
  "redirectUris": ["https://portal.firma.cz/callback"],
  "userApiAppCode": "firma-portal"
}

---

Konfigurace

V config/default.yaml:

zitadel:
  apiUrl: http://zitadel:8080        # Interní URL (Docker)
  publicUrl: http://localhost:8080   # Veřejná URL (pro redirect)
  serviceAccountToken: ""            # Service account token pro API volání
  webhookSecret: "change-me"         # Secret pro ověřování webhooků
  orgToApp: {}                       # Mapování orgId → appCode

orgToApp mapování

Mapuje Zitadel organizaci na aplikaci v User API:

zitadel:
  orgToApp:
    "org_abc123": "crm"
    "org_def456": "vallox-panel"

Toto mapování se používá při webhook událostech a Zitadel setup flowu.