Autentizace API pomocí tokenů a OAuth 2.0 – bezpečný přístup

Proč autentizace API pomocí tokenů a OAuth 2.0

Moderní API obsluhují webové i mobilní aplikace, integrace partnerů a automatizované služby. Tokenová autentizace v rámci 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 (provádí autentizaci, zajišťuje souhlas uživatele a aplikuje politiky).
Resource Server (RS) – chráněné API, ověřuje tokeny a vynucuje přístupová práva.
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í; Resource Server introspektuje token u Authorization Serveru	Okamžitá revokace, menší riziko úniku informací	Náklady na síťový dotaz/introspekci	Vysoce citlivá API, centrální řízení přístupu
JWT (JWS/JWE)	Sebepopisný token s digitálním podpisem nebo š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 ověřování
PASETO	Alternativa k JWT s pevně definovanými režimy a bezpečnými výchozími hodnotami	Jednodušší výběr křivek a algoritmů	Menší ekosystém a podpora	Specifická prostředí preferující „opinionated“ standard

Struktura a klíčové claimy JWT

Header: obsahuje alg, kid, typ.
Payload: standardní claimy jako iss (issuer), sub (subject), aud (audience), exp (expiration), iat (issued at), nbf (not before); aplikační claimy například scope, roles, tenant.
Signature: digitální podpis JWS (např. RS256, ES256). Pro citlivé informace použijte JWE (šifrování obsahu).

Best practice: Minimalizujte počet claimů, nikdy do JWT neukládejte tajné ani osobní údaje nad nezbytné minimum; claimy navrhujte stabilně s verzováním schématu.

Granty a toky OAuth 2.0

Grant	Scénář	Bezpečnostní poznámky
Authorization Code + PKCE	Webové aplikace, SPA a mobilní aplikace s přesměrováním a souhlasem uživatele	PKCE je povinné i u důvěryhodných klientů; kontrola `state` a `nonce`, striktní validace redirect URI
Client Credentials	Server-to-server (strojové integrace bez uživatele)	Silná autentizace klienta (mTLS, privátní klíče), scopes pro strojová oprávnění
Device Code	Zařízení bez prohlížeče nebo klávesnice (např. TV, IoT)	Omezit životnost kódu, detekovat podvodný polling, interakce přes sekundární zařízení
Refresh Token	Obnova access tokenu bez potřeby opětovné autentizace	Rotace refresh tokenů, sender-constrained (mTLS/DPoP), krátká životnost access tokenů
Resource Owner Password	Historický tok (uživatel předává heslo přímo klientovi)	Nedoporučuje se; nahrazujte Authorization Code + PKCE

OAuth 2.0 vs. OpenID Connect (OIDC)

OAuth řeší autorizaci (přístup k API), zatímco OpenID Connect přidává autentizaci uživatele a poskytuje ID token s uživatelskými claimy. ID token však není oprávněním k API; API by mělo ověřovat access token v rámci vlastního aud a scope.

Bezpečnostní zpevnění: moderní rozšíření

PKCE: ochrana proti zachycení autorizačního kódu.
Sender-constrained tokeny: vazba tokenu na klientský certifikát (mTLS) nebo na klíč a HTTP metodu/URL (DPoP) zabraňuje zneužití ukradeného tokenu.
PAR (Pushed Authorization Requests): klient odesílá autorizační parametry přímo autorizačnímu serveru přes autentizované spojení, což snižuje riziko manipulace v prohlížeči.
JAR/JARM: podepsané a š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 schopností API (např. invoices.read, invoices.write), nikoli podle uživatelského rozhraní.
Role (RBAC) mapujte interně na scopes; případně použijte ABAC (atributové řízení přístupu) přes claimy jako tenant, region či department.
Ověřujte aud a iss v API, nikdy nepřijímejte tokeny určené jinému publiku.

Životní cyklus tokenů: expirace, rotace, revokace

Access token má krátkou životnost (řádově minuty); minimalizuje dopad případného úniku.
Refresh token rotujte: při jeho použití vydávejte nový a současně starý invalidujte (detekce token replay).
Revokace: poskytujte endpoint pro odvolání tokenů; u JWT tokenů doplňujte denylist v případech vysokého rizika, jinak spoléhejte na krátkou životnost.
Introspekce: vyžaduje se u opaque tokenů; u JWT tokenů preferujte ověření podpisu a kontrolu exp a nbf.

API Gateway a enforcement politiky

API Gateway (nebo sidecar proxy) centralizuje ověřování tokenů, kontrolu scope a aud, postupy jako rate limiting, kvóty (quota), WAF, mTLS a cache introspekce. Výsledek rozhodnutí přenášejte do HTTP hlaviček pro downstream služby (např. X-Principal, X-Scopes) s patřičnou opatrností.

Prohlížečové a mobilní aplikace: specifika

SPA: vyhněte se ukládání tokenů do localStorage nebo sessionStorage; preferujte BFF (Backend for Frontend) s httpOnly cookies a serverovým držákem tokenu.
Mobilní aplikace: používejte knihovny AppAuth, PKCE, custom URI scheme versus App Links/Universal Links; bezpečné ukládání klíčů v Keychain/Keystore.
Desktopové aplikace: preferujte systémový prohlížeč místo embedded webview, izolujte proces přihlašování.

Více tenantů a delegování

Tenant-bound tokeny: claimy tenant a azp (authorized party) pro audit delegace přístupů.
On-behalf-of (OBO): backendová služba volá jiné API jménem uživatele – vyměňuje získaný token za token pro downstreem API s odpovídajícím aud a scope.

Transport a ochrana kanálu

Používejte TLS 1.2 a vyšší s vhodnými kryptografickými sadami; u strojových integrací zvažte mTLS.
Omezujte CORS pouze na důvěryhodné originy; nepovolujte wildcard * u Authorization hlaviček.
Zaveďte rate limiting, politiky na IP/ASN a detekci anomálií provozu.

Protokolové chyby a jejich prevence

Chybějící kontrola aud a iss: API přijímá tokeny pro jiná publika – vždy validujte obojí.
Ukládání tokenů v prohlížeči: riziko úniku přes XSS; preferujte BFF a httpOnly cookies.
Příliš dlouhá životnost access tokenu: zvyšte závislost na refresh toky s rotací tokenů.
Neschválené redirect URI: povolujte pouze přesné shody, ne wildcards.
Nesprávné použití ID tokenu k volání API: API by mělo požadovat access token.

Model chyb a odpovědi API

401 Unauthorized: chybějící nebo expirovaný token; odpověď s hlavičkou WWW-Authenticate: Bearer error="invalid_token".
403 Forbidden: token je platný, ale má nedostatečný scope nebo role.
Neprozrazujte v odpovědích interní detaily; využívejte logování s korelačními ID požadavků.

Observabilita, audit a detekce zneužití

Logujte informace jako iss, sub, aud, jti, scope, rozhodnutí o autorizaci a korelační ID; citlivé hodnoty maskujte.
Detekujte token replay pomocí jti a mechanismů proof-of-possession (DPoP nebo mTLS).
Exportujte metriky o úspěšných a zamítnutých požadavcích, expiracích tokenů, chybách introspekce a latencích autorizačního serveru.

Migrace a kompatibilita

Pro přechod z API klíčů instalujte Client Credentials s granularitou scopes.
Při migraci z dlouhodobých JWT tokenů na krátkodobé + refresh token připravte grace period a pozvolnou rotaci klíčů (kid).
Udržujte verze claimů (např. roles_v2) a deklarujte ukončení podpory starých verzí.

Checklist pro bezpečné API

Authorization Server vydává krátké access tokeny, rotuje refresh tokeny a vyžaduje PKCE.
API validuje podpis, aud, iss, exp, nbf a scope.
Používá sender-constrained tokeny (mTLS/DPoP) pro vysoce rizikové toky.
Implementuje PAR/JAR pro citlivé požadavky, JWKS s rotací klíčů.
BFF architektura pro SPA, httpOnly cookies, striktní CORS.
Rate limiting, WAF, detekce replay, korelační logování 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, omezení CORS
Server-to-server integrace	Client Credentials	Opaque nebo JWT	mTLS, IP restrikce, krátká životnost access tokenů
IoT/TV bez klávesnice	Device Code	Krátký JWT	DPoP, omezená životnost, regionální audience
Vysoce citlivé API (finanční)	Authorization Code + PKCE	Opaque	Introspekce, JWE, mTLS, PAR/JAR