Proč autentizace API pomocí tokenů a OAuth 2.0
Moderní API obsluhují webové i mobilní aplikace, integrace partnerů a automatizované služby. Tokenová autentizace s rámcem OAuth 2.0 umožňuje bezpečně svěřit přístup třetím stranám, oddělit identitu od přístupu a aplikovat princip zero trust. Klíčové je správně navrhnout životní cyklus tokenů, model oprávnění, bezpečnostní kontroly a observabilitu napříč celým tokem – od klienta přes autorizační server až po resource server (API).
Základní pojmy a role v OAuth 2.0
- Resource Owner – vlastník dat (koncový uživatel nebo organizace).
- Client – aplikace žádající o přístup (veřejný či důvěryhodný klient).
- Authorization Server (AS) – vydává tokeny (autentizace, consent, politiky).
- Resource Server (RS) – chráněné API, ověřuje tokeny a vynucuje přístup.
- Scope – rozsah přístupu (granularita oprávnění pro token).
- Audience (aud) – zamýšlený příjemce tokenu (konkrétní API).
Typy tokenů: Opaque, JWT a PASETO
| Typ | Popis | Výhody | Nevýhody | Využití |
|---|---|---|---|---|
| Opaque | Netvoří samostatný nosič informací; RS introspektuje u AS | Okamžitá revokace, menší únik informací | Náklady na síťový dotaz/introspekci | Vysoce citlivá API, centralizované řízení |
| JWT (JWS/JWE) | Sebepopisný token s podpisem/šifrováním | Offline ověření, rychlé škálování | Revokace obtížnější, riziko přenosu citlivých claimů | Distribuovaná API, nízká latence |
| PASETO | Alternativa k JWT s definovanými režimy a bezpečnými defaulty | Jednodušší volba křivek/algoritmů | Menší ekosystém | Specifické prostředí s preferencí „opinionated“ standardu |
Struktura a klíčové claimy JWT
- Header:
alg,kid,typ. - Payload: standardní claimy
iss,sub,aud,exp,iat,nbf; aplikační claimy (např.scope,roles,tenant). - Signature: JWS (např. RS256/ES256). Pro citlivé informace použijte JWE (šifrování).
Best practice: Minimalizujte množství claimů, nikdy do JWT neukládejte tajemství ani osobní údaje nad nezbytné minimum; claimy navrhujte stabilně (verzování schématu).
Granty a toky OAuth 2.0
| Grant | Scénář | Bezpečnostní poznámky |
|---|---|---|
| Authorization Code + PKCE | Web/SPAs/Mobilní aplikace s přesměrováním a uživatelským souhlasem | PKCE povinně i pro důvěryhodné klienty; kontrola state/nonce, striktní redirect URI |
| Client Credentials | Server-to-server (strojové integrace, bez uživatele) | Silná autentizace klienta (mTLS, privátní klíč), scopes pro strojová oprávnění |
| Device Code | Zařízení bez prohlížeče/klávesnice (TV, IoT) | Omezení lifetime kódu, detekce podvodného pollingu, interakce na sekundárním zařízení |
| Refresh Token | Obnova access tokenu bez opětovné autentizace | Rotace RT, sender-constrained (mTLS/DPoP), krátké access tokeny |
| Resource Owner Password | Historický tok (uživatel zadává heslo klientovi) | Nedoporučeno; nahrazujte Authorization Code + PKCE |
OAuth 2.0 vs. OpenID Connect (OIDC)
OAuth řeší autorizaci (přístup k API), zatímco OIDC přidává autentizaci uživatele a ID token s uživatelskými claimy. ID token není vstupenka k API; API má ověřovat access token pro své aud a scope.
Bezpečnostní zpevnění: moderní rozšíření
- PKCE: ochrana proti interceptu autorizačního kódu.
- Sender-constrained tokeny: mTLS (vazba na klientský certifikát) nebo DPoP (vazba na klíč a HTTP metodu/URL) zabraňuje zneužití ukradeného tokenu.
- PAR (Pushed Authorization Requests): klient předává autorizační parametry přímo AS přes autentizované spojení – snižuje riziko manipulace v prohlížeči.
- JAR/JARM: podepsané/šifrované žádosti a odpovědi autorizačního serveru.
- JWK(S) a rotace klíčů: publikujte JWKS, používejte
kid, plánujte rotaci a odvolání klíčů.
Návrh oprávnění: scopes, claims, role a atributy
- Scopes modelujte podle API schopností (např.
invoices.read,invoices.write), nikoli podle UI. - Role (RBAC) mapujte interně na scopes; případně ABAC (atributové) přes claimy jako
tenant,region,department. - Ověřujte aud a iss v API; nepřijímejte tokeny určené jinému publiku.
Životní cyklus tokenů: expirace, rotace, revokace
- Access token krátký (minuty); minimalizuje dopad úniku.
- Refresh token rotujte: při použití vydat nový, starý invalidovat (detekce token replay).
- Revokace: endpoint pro odvolání; u JWT doplňujte denylist pro vysoké riziko, jinak spoléhejte na krátký život.
- Introspekce: pro opaque tokeny; pro JWT preferujte podpis + kontrolu
exp/nbf.
API Gateway a enforcement politik
Gateway (nebo sidecar) centralizuje ověřování tokenu, kontrolu scope/aud, rate-limit, quota, WAF, mTLS a caching introspekce. Výsledek rozhodnutí propisujte do hlaviček pro downstream služby (např. X-Principal, X-Scopes) s opatrností.
Prohlížečové a mobilní aplikace: specifika
- SPA: vyhněte se ukládání tokenů do localStorage/sessionStorage; preferujte BFF (Backend for Frontend) s httpOnly cookie a serverovým držákem tokenu.
- Mobilní: AppAuth knihovny, PKCE, custom URI scheme vs. App Links/Universal Links; bezpečné uložení klíčů (Keychain/Keystore).
- Desktop: system browser místo embedded webview, izolace přihlašování.
Více tenantů a delegování
- Tenant-bound tokeny: claim
tenantaazp(authorized party) pro audit delegace. - On-behalf-of (OBO): backend volá jiné API jménem uživatele – vyměňuje získaný token za downstream token s odpovídající
aud/scope.
Transport a ochrana kanálu
- Používejte TLS 1.2+ se silnými sadami; u strojových integrací zvažte mTLS.
- Omezte CORS pouze na důvěryhodné originy; nepovolujte
*proAuthorizationhlavičky. - Implementujte rate limiting, IP/ASN politiky a detekci anomálií.
Protokolové chyby a jejich prevence
- Chybějící kontrola
aud/iss: API přijímá cizí tokeny – vždy validujte obojí. - Úložiště tokenů v prohlížeči: únik přes XSS. Preferujte BFF a httpOnly cookies.
- Příliš dlouhá životnost access tokenu: zvyšte závislost na refresh toku s rotací.
- Neschválené redirect URI: povolujte pouze přesné shody, bez wildcardů.
- Nesprávné použití ID tokenu k volání API: API musí vyžadovat access token.
Model chyb a odpovědi API
- 401 Unauthorized: chybějící/expirující token; hlavička
WWW-Authenticate: Bearer error="invalid_token". - 403 Forbidden: token validní, ale nedostatečný
scope/role. - V odpovědích neprozrazujte interní detaily; logujte korelované ID požadavku.
Observabilita, audit a detekce zneužití
- Logujte iss, sub, aud, jti, scope, rozhodnutí autorizace, korelační ID; maskujte citlivé hodnoty.
- Detekujte token replay přes
jtia proof-of-possession (DPoP/mTLS). - Exportujte metriky: allow/deny rate, expirace, chyby introspekce, latence AS.
Migrace a kompatibilita
- Pro přechod z API klíčů zaveďte Client Credentials s granularitou scopes.
- Při migraci z dlouho žijících JWT na krátké + RT připravte grace period a pozvolnou rotaci klíčů (
kid). - Udržujte verze claimů (např.
roles_v2) a deklarujte EOL starých.
Checklist pro bezpečné API
- AS vydává krátké access tokeny, rotuje refresh tokeny, vynucuje PKCE.
- API validuje podpis/aud/iss/exp/nbf a scope.
- Sender-constrained tokeny (mTLS/DPoP) pro vysoce rizikové toky.
- PAR/JAR pro citlivé požadavky, JWKS s rotací klíčů.
- BFF pro SPA, httpOnly cookies, striktní CORS.
- Rate limiting, WAF, detekce replay, korelační logy a audit.
Příklad rozhodovací matice
| Scénář | Doporučený tok | Token | Dodatečná ochrana |
|---|---|---|---|
| Veřejná SPA pro koncové uživatele | Authorization Code + PKCE (přes BFF) | Krátký JWT | BFF, httpOnly cookie, CORS restrikce |
| Server-to-server integrace | Client Credentials | Opaque nebo JWT | mTLS, IP restrikce, krátké AT |
| IoT/TV bez klávesnice | Device Code | Krátký JWT | DPoP, omezená lifetime, regionální aud |
| Vysoce citlivé API (finanční) | Authorization Code + PKCE | Opaque | Introspekce, JWE, mTLS, PAR/JAR |
Souhrn nejlepších postupů
- Preferujte Authorization Code + PKCE pro aplikace s uživatelem; Client Credentials pro strojové toky.
- Vydávejte krátké access tokeny a rotujte refresh tokeny; pro citlivé toky použijte sender-constrained přístup (mTLS/DPoP).
- Tokeny navrhujte s minimem claimů; vždy validujte aud a iss na API.
- U SPA využijte BFF architekturu a httpOnly cookies; vyhněte se ukládání tokenů v localStorage.
- Zaveďte PAR/JAR, JWKS rotaci, rate limiting, audit a detekci anomálií.
Závěr
Autentizace API pomocí tokenů a OAuth 2.0 poskytuje škálovatelný a interoperabilní rámec řízení přístupu. Bezpečnost i uživatelská zkušenost stojí na správné volbě toku, pečlivé validaci tokenů, krátkých expiracích a důsledné observabilitě. Kombinací moderních rozšíření (PKCE, mTLS/DPoP, PAR/JAR) a rozumného návrhu scopes/claimů lze dosáhnout vysoké úrovně ochrany dat i efektivní integrace napříč systémy.
