Autentizace — přehled

Jabcore Platform API používá Zitadel jako JWT provider pro autentizaci klientů a interní API klíč pro service-to-service komunikaci. Každý účet patří do user poolu — API ho identifikuje dvojicí pool + e-mail.

Jak to funguje

Každý chráněný endpoint vyžaduje platný JWT Bearer token:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Při příchodu requestu:

1. JWTService načte veřejné klíče od všech nakonfigurovaných providerů (JWKS)
2. Vyzkouší verifikaci tokenu každým providerem, dokud jeden neuspěje
3. Extrahuje email uživatele z JWT claims
4. Nastaví req.token s daty z tokenu

Podporovaní provideři

Provider	Typ	Primární použití
Zitadel	Self-hosted OIDC	Jediný provider pro všechny aplikace Jabcore

Google / Microsoft účty

Login přes Google nebo Microsoft není samostatný JWT provider — uživatelé se přihlašují přes Zitadel, který má Google a Microsoft nakonfigurované jako federované identity providery (IdP). Token, který API přijímá, je vždy Zitadel JWT.

Viz JWT Provideři pro detailní konfiguraci.

Pro volbu brandu bez omezení organizace přihlašovaného účtu viz Multi-brand přihlášení napříč organizacemi.

Typy autentizace

1. JWT Bearer Token (frontend / uživatelé)

Pro endpointy profile, users, applications, roles, permissions:

curl /api/profile/me \
  -H "Authorization: Bearer <token>"

2. Interní API klíč (backend / service-to-service)

Pro endpointy /api/check a /api/internal/*:

curl -X POST /api/check \
  -H "x-internal-api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "...", "app": "...", "permission": "..."}'

Hodnota klíče: config.internalApiKey (viz Konfigurace).

3. Webhook secret (Zitadel)

Pro Zitadel webhooky:

POST /api/zitadel/webhook
X-Webhook-Secret: <webhook-secret>

Email jako identita

Po úspěšné verifikaci JWT je email uživatele extrahován z těchto claims (v pořadí priority):

1. email
2. preferred_username
3. upn (federovaní Microsoft uživatelé)
4. sub (fallback)

Email pak slouží jako primární identifikátor ve všech operacích.

Refresh klíčů

JWKS klíče se načítají při startu a automaticky refreshují každých 60 minut. Interval je konfigurovatelný přes config.token.keyRefreshIntervalMinutes.

Endpointy bez autentizace

Tyto endpointy nevyžadují žádný token:

Endpoint	Popis
GET /api/test	Health check
GET /api/version	Verze API
POST /api/check	Permission check
POST /api/check/bulk	Bulk permission check
POST /api/check/effective	Effective permissions
POST /api/check/cache/clear	Manuální invalidace cache
POST /api/zitadel/webhook	Zitadel webhook (x-webhook-secret)
GET /api/zitadel/health	Zitadel health probe
GET /api/zitadel/discovery	OIDC discovery dokument
GET /api/zitadel/login	OIDC login start (dev)
GET /api/zitadel/callback	OIDC callback (dev)

Swagger (/api/docs, /api/docs.json) a VitePress (/docs/) jsou v produkci chráněné samostatnou dokumentační session. Člověk se přihlašuje přes existující OIDC aplikaci auth; coding AI používá pouze 24hodinový token se scope docs:read. Podrobnosti viz Přístup k dokumentaci.

Viz také

• JWT Provideři — konfigurace Zitadelu
• Multi-brand login — oddělení brandu od organizace účtu
• Autorizace & Role — admin hierarchie, middleware stack
• Přístup k dokumentaci — login a tokeny pro AI