Autentizace — přehled

Atrea User API podporuje čtyři JWT providery pro autentizaci klientů a používá 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
Microsoft	OAuth2/OIDC (Azure AD)	Microsoft účty
Google	OAuth2/OIDC	Google účty

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 (Microsoft)
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 (internal API key volitelný)
POST /api/check/bulk	Bulk permission check
POST /api/check/effective	Effective permissions
POST /api/zitadel/webhook	Zitadel webhook (x-webhook-secret)
GET /api/zitadel/login	OIDC login start
GET /api/zitadel/callback	OIDC callback

Viz také

• JWT Provideři — konfigurace Zitadel, MS, Google
• Autorizace & Role — admin hierarchie, middleware stack