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.

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
• Autorizace & Role — admin hierarchie, middleware stack