Autentizace — přehled

Atrea User API používá Zitadel jako primární JWT provider pro autentizaci klientů (s Amotion jako alternativním auth serverem) a interní API klíč pro service-to-service komunikaci.

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	Hlavní provider pro všechny Atrea aplikace
Amotion	OAuth2/OIDC	Alternativní auth server

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
GET /api/docs	Swagger UI
GET /docs/	Tato dokumentace
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)

Viz také

• JWT Provideři — konfigurace Zitadel a Amotion
• Multi-brand login — oddělení brandu od organizace účtu
• Autorizace & Role — admin hierarchie, middleware stack