Autentizace API: tokeny a OAuth 2.0 pro 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 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 uplatňovat 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ý nebo důvěrný klient).
Authorization Server (AS) – vydává tokeny (autentizace, souhlas, 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	Neobsahuje informace, které by bylo možné samostatně přečíst; RS provádí introspekci u AS	Okamžité odvolání, 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	Ověření bez připojení, rychlé škálování	Odvolání je 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 výchozími nastaveními	Jednodušší výběr křivek/algoritmů	Menší ekosystém	Specifické prostředí s preferencí standardu s pevně stanovenými pravidly

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í).

Osvědčený postup: Minimalizujte množství claimů, nikdy do JWT neukládejte tajemství ani více osobních údajů, než je nezbytné; claimy navrhujte stabilně (verzování 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 pro důvěrné klienty; kontrola `state`/`nonce`, striktní redirect URI
Client Credentials	Komunikace server-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í platnosti kódu, detekce podvodného opakovaného dotazování, interakce na sekundárním zařízení
Refresh Token	Obnova access tokenu bez opětovné autentizace	Rotace RT, omezení použití na držitele (mTLS/DPoP), krátkodobé access tokeny
Resource Owner Password	Historický tok (uživatel zadává heslo klientovi)	Nedoporučuje se; nahrazujte tokem 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í vstupenkou k API; API má ověřovat access token určený pro jeho aud a scope.

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

PKCE: ochrana proti zachycení autorizačního kódu.
Tokeny vázané na odesílatele: mTLS (vazba na klientský certifikát) nebo DPoP (vazba na klíč a metodu/URL HTTP) zabraňují 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, claimy, 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 (řízení přístupu na základě atributů) prostřednictvím claimů jako tenant, region, department.
V API ověřujte aud a iss; nepřijímejte tokeny určené jinému publiku.

Životní cyklus tokenů: expirace, rotace, odvolání

Access token má krátkou platnost (minuty); tím se minimalizuje dopad úniku.
Refresh token rotujte: při použití vydejte nový a starý zneplatněte (detekce opakovaného použití tokenu).
Odvolání: endpoint pro odvolání; u JWT doplňte denylist pro vysoce rizikové případy, jinak se spoléhejte na krátkou dobu platnosti.
Introspekce: pro opaque tokeny; u JWT upřednostněte ověření podpisu a kontrolu exp/nbf.

API Gateway a vynucování politik

Gateway (nebo sidecar) centralizuje ověřování tokenu, kontrolu scope/aud, omezení počtu požadavků, kvóty, WAF, mTLS a ukládání výsledků introspekce do mezipaměti. Výsledek rozhodnutí předávejte downstream službám v hlavičkách (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; upřednostněte BFF (Backend for Frontend) s cookie httpOnly a tokenem uloženým na serveru.
Mobilní aplikace: knihovny AppAuth, PKCE, vlastní schéma URI vs. App Links/Universal Links; bezpečné ukládání klíčů (Keychain/Keystore).
Desktopové aplikace: systémový prohlížeč místo vloženého webového zobrazení, izolace přihlašování.

Více tenantů a delegování

Tokeny vázané na tenanta: claim tenant a azp (autorizovaná strana) pro audit delegování.
On-behalf-of (OBO): backend volá jiné API jménem uživatele – získaný token vymění za token pro downstream službu s odpovídajícím aud/scope.

Transport a ochrana kanálu

Používejte TLS 1.2+ se silnými sadami šifer; u strojových integrací zvažte mTLS.
Omezte CORS pouze na důvěryhodné originy; nepovolujte * pro hlavičky Authorization.
Implementujte omezení počtu požadavků, politiky IP/ASN a detekci anomálií.

Chyby protokolu a jejich prevence

Chybějící kontrola aud/iss: API přijímá cizí tokeny – vždy ověřujte obě hodnoty.
Ukládání tokenů v prohlížeči: únik prostřednictvím XSS. Upřednostněte BFF a cookie httpOnly.
Příliš dlouhá platnost access tokenu: omezte jeho platnost a spoléhejte se více na tok obnovy s rotací.
Neschválené redirect URI: povolujte pouze přesné shody, bez zástupných znaků.
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í nebo expirovaný token; hlavička WWW-Authenticate: Bearer error="invalid_token".
403 Forbidden: token je platný, ale nemá dostatečný scope/roli.
V odpovědích neprozrazujte interní podrobnosti; zaznamenávejte korelační ID požadavku.

Observabilita, audit a detekce zneužití

Zaznamenávejte iss, sub, aud, jti, scope, rozhodnutí o autorizaci a korelační ID; citlivé hodnoty maskujte.
Detekujte opakované použití tokenu pomocí jti a proof-of-possession (DPoP/mTLS).
Exportujte metriky: poměr povolených a zamítnutých požadavků, expirace, chyby introspekce, latence AS.

Migrace a kompatibilita

Při přechodu z API klíčů zaveďte Client Credentials s granularitou scopes.
Při migraci z dlouhodobých JWT na krátkodobé tokeny a RT připravte přechodné období a postupnou rotaci klíčů (kid).
Udržujte verze claimů (např. roles_v2) a deklarujte konec životnosti starých verzí.

Kontrolní seznam pro zabezpečení API

AS vydává krátkodobé access tokeny, rotuje refresh tokeny a vynucuje PKCE.
API ověřuje podpis/aud/iss/exp/nbf a scope.
Pro vysoce rizikové toky používejte tokeny vázané na odesílatele (mTLS/DPoP).
Pro citlivé požadavky používejte PAR/JAR a JWKS s rotací klíčů.
Pro SPA používejte BFF, cookies httpOnly a přísná omezení CORS.
Omezení počtu požadavků, WAF, detekce opakovaného použití tokenu, 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átkodobý JWT	BFF, cookie httpOnly, omezení CORS
Integrace server-server	Client Credentials	Opaque nebo JWT	mTLS, omezení podle IP, krátkodobé AT
IoT/TV bez klávesnice	Device Code	Krátkodobý JWT	DPoP, omezená doba platnosti, regionální aud
Vysoce citlivé API (finanční)	Authorization Code + PKCE	Opaque	Introspekce, JWE, mTLS, PAR/JAR

Souhrn osvědčených postupů

Pro aplikace s uživatelem upřednostňujte Authorization Code + PKCE; pro strojové toky používejte Client Credentials.
Vydávejte krátkodobé access tokeny a rotujte refresh tokeny; pro citlivé toky použijte přístup s tokeny vázanými na odesílatele (mTLS/DPoP).
Navrhujte tokeny s minimem claimů; v API vždy ověřujte aud a iss.
U SPA využívejte architekturu BFF a cookies httpOnly; vyhněte se ukládání tokenů do localStorage.
Zaveďte PAR/JAR, rotaci JWKS, omezení počtu požadavků, audit a detekci anomálií.

Závěr

Autentizace API pomocí tokenů a OAuth 2.0 poskytuje škálovatelný a interoperabilní rámec pro řízení přístupu. Bezpečnost i uživatelská zkušenost stojí na správné volbě toku, pečlivém ověřování tokenů, krátké době platnosti a důsledné observabilitě. Kombinací moderních rozšíření (PKCE, mTLS/DPoP, PAR/JAR) a promyšleného návrhu scopes/claimů lze dosáhnout vysoké úrovně ochrany dat i efektivní integrace napříč systémy.