OpenID Configuration: Kompletní průvodce a vysvětlení

Ve světě moderních webových a mobilních aplikací se neustále potýkáme s požadavky na bezpečné přihlašování a ověřování identity uživatelů. Pravděpodobně jste se už někdy setkali s pojmy jako OpenID Connect, OIDC nebo OAuth 2.0. Jedním z nejdůležitějších prvků celého procesu autentizace je takzvaný dokument .well-known/openid-configuration. Co to vlastně je, jak to funguje a proč byste tomu měli jako vývojáři věnovat zvýšenou pozornost?

Když se vaše aplikace snaží připojit k Identity Provideru (poskytovateli identity, jako je Google, Microsoft, Okta nebo Keycloak), potřebuje vědět, kam má poslat uživatele k přihlášení, kde může získat přístupové tokeny, a pomocí jakých klíčů má ověřit jejich platnost. Právě zde nastupuje na scénu OpenID Configuration, známá také jako OIDC Discovery. V tomto rozsáhlém průvodci se podíváme na každý detail této konfigurace a proč je její dynamické zpracování nutností pro bezpečný a škálovatelný vývoj.

Co je to OpenID Configuration?

OpenID Configuration je standardizovaný proces objevování (Discovery), který umožňuje aplikacím (klientům) dynamicky získat veškeré potřebné informace k interakci s OpenID Connect serverem. Místo toho, abyste v kódu své aplikace měli natvrdo (hardcoded) nastavené URL adresy pro různé fáze ověřovacího procesu, vaše aplikace zašle jednoduchý HTTP dotaz na specifický koncový bod (endpoint) a jako odpověď obdrží strukturovaný JSON dokument.

Tento přístup, který definuje specifikace OpenID Connect Discovery 1.0, přináší obrovskou flexibilitu a výrazně snižuje riziko lidské chyby. Pokud se na straně Issuera (vydavatele tokenů) cokoliv změní – například se vytvoří nový pár kryptografických klíčů pro podepisování tokenů nebo dojde k migraci endpointů – klient si tuto změnu automaticky načte z konfiguračního souboru a nedojde k žádnému výpadku služby.

Je to svým způsobem podobné, jako když se snažíte zjistit optimální provozní podmínky. Například pokud chcete jezdit s autem bezpečně, potřebujete znát přesná data pro údržbu, jako je správný tlak v pneumatikách na kolo či auto. Správné hodnoty, doporučené výrobcem a uvedené v technickém průvodci, vám zaručí bezproblémovou a bezpečnou jízdu, předcházejí defektům a prodlužují životnost materiálu. OpenID Configuration dělá pro vaši aplikaci přesně totéž – dává vám okamžité, přesné a aktuální „provozní specifikace“, abyste komunikovali s Identity Providerem naprosto bezpečně, v rámci stanovených protokolů a s garancí bezpečného výkonu.

Kde najdete .well-known/openid-configuration dokument?

Dokument s konfigurací se vždy nachází na standardizované cestě, což zásadně zjednodušuje objevitelnost. Podle specifikace se tento endpoint skládá z kořenové adresy (URL) vydavatele (Issuer) a pevně daného příponového řetězce /.well-known/openid-configuration.

Pokud je například adresa vašeho vydavatele (Identity Providera) https://auth.vasefirma.cz, konfigurační soubor bude vždy bezpečně dostupný na této URL:

https://auth.vasefirma.cz/.well-known/openid-configuration

Složka .well-known je navržena organizací IETF (Internet Engineering Task Force) jako standardní úložiště pro meta-informace o doméně a službách na ní běžících. Díky tomu není nutné si pamatovat složité a často se měnící cesty k API dokumentaci – klienti (Vaše webové či mobilní aplikace) přesně vědí, kam se mají podívat, aby získaly „mapu“ ke službě. Ať už se připojujete k jakémukoli OIDC providerovi, tento princip je absolutně univerzální a konzistentní napříč celým odvětvím a platformami.

Co všechno obsahuje tento JSON dokument?

Tělo HTTP odpovědi je formátováno jako strukturovaný JSON objekt. Obvykle se skládá z desítek možných vlastností (klíčů), které precizně popisují schopnosti daného Identity serveru. Níže si rozebereme ty naprosto nejkritičtější, které jsou přímo vyžadovány k úspěšnému dokončení standardních OAuth 2.0 a OIDC toků:

• issuer: Jednoznačný HTTPS identifikátor (URL) poskytovatele identity. Hodnota v tomto poli se musí naprosto přesně shodovat s tím, jakou službu se snažíte kontaktovat. Zároveň veškeré tokeny, které vám server později vydá, musí obsahovat identickou hodnotu ve svém poli (claimu) iss. Rozdíl byť i v jediném znaku (nebo chybějícím koncovém lomítku) znamená, že by klient měl token z bezpečnostních důvodů striktně odmítnout.
• authorization_endpoint: Místo (URL), na které vaše aplikace přesměruje samotného uživatele prostřednictvím jeho prohlížeče, když je vyžadováno přihlášení a udělení souhlasu se sdílením osobních údajů. Právě zde zadává uživatel své přihlašovací údaje (jméno a heslo, nebo využívá hardwarový klíč, biometrii, případně jinou formu 2FA). Zde aplikace nemá k datům přístup, dokud uživatel akci neodsouhlasí.
• token_endpoint: Klíčové místo, kam si vaše aplikace (převážně na svém backendu) posílá tzv. autorizační kód (authorization code) a výměnou za něj dostává konkrétní JWT tokeny – nejčastěji ID token, Access token a pro dlouhodobější relace také Refresh token. Tato komunikace probíhá z bezpečnostních důvodů téměř vždy výlučně mezi servery (server-to-server) a neúčastní se jí uživatelský prohlížeč.
• userinfo_endpoint: Volitelný, ale vysoce využívaný endpoint pro získání dalších dodatečných informací (claims) o aktuálně přihlášeném uživateli. Můžete zde získat jeho křestní jméno, příjmení, kontaktní e-mail či dokonce odkaz na profilovou fotografii. Podmínkou je se v HTTP hlavičce prokázat dříve získaným platným Access tokenem, který obsahuje příslušná oprávnění (scopes).
• jwks_uri: Mimořádně kritický odkaz na takzvaný JSON Web Key Set (sadu veřejných klíčů). Poskytuje veřejné kryptografické klíče, pomocí kterých může klient zcela samostatně a lokálně matematicky ověřit, že předložené tokeny (ve formátu JWT) skutečně vydal váš důvěryhodný poskytovatel a že nikdo po cestě nijak nezměnil jejich obsah. Zajišťuje plnou integritu identity uživatele.
• scopes_supported: Seznam scope (rozsahů oprávnění a přístupů), o které si klient může teoreticky zažádat, pokud na ně má nastavené právo. Základní je scope openid, bez kterého se celá transakce vůbec neřadí pod OpenID Connect protokol. Mezi další časté patří profile nebo email.
• response_types_supported: Definuje, do jakých flow (toků) může klient vůbec vstupovat (zda server podporuje vracení samotného kódu code pro tradiční backendové aplikace, anebo id_token token pro dříve oblíbený, avšak dnes již spíše opouštěný Implicit flow vhodný pro čistě frontendové single-page aplikace).
• subject_types_supported: Specifikuje, jakým způsobem jsou generovány unikátní identifikátory uživatelů (claim sub). Nejčastěji vidíme podporu pro public (identifikátor uživatele je shodný pro všechny klienty), ale u specifických architektur lze narazit na pairwise, kde každý klient dostane unikátní maskované ID uživatele.

Proč je OpenID Connect Discovery tak důležité pro bezpečnost?

Základním stavebním kamenem a nezbytnou nutností bezpečnosti v moderních systémech s federovanou identitou je vysoká flexibilita v rotaci kryptografických klíčů. Dlouhodobé používání byť i silného, ovšem jednoho stálého asymetrického šifrovacího klíče významně zvyšuje riziko jeho úniku, kompromitace a zneužití. Díky mechanismu dynamického discovery a zmiňovanému odkazovanému jwks_uri může Identity Provider periodicky generovat zbrusu nové podepisovací klíče, zneplatňovat ty staré a publikovat jejich veřejné části online, a to aniž by jakkoliv způsobil pád nebo zablokování přihlašování u tisíců připojených klientských aplikací.

Jakmile celý tento mechanismus implementujete, začne fungovat následující postup: Když vám od uživatele dorazí podepsaný JWT (JSON Web Token), vaše aplikační logika se v první řadě podívá do jeho nezabezpečené hlavičky na identifikátor klíče (zkratka „kid“ – Key ID). Vaše lokální implementace pak načte seznam aktuálních důvěryhodných klíčů z vašeho cachovaného JSON Web Key Setu a najde ten správný s odpovídajícím identifikátorem. Tímto veřejným klíčem následně ověříte krypto-matematický podpis na konci tokenu a získáte 100% jistotu, že jeho obsah je autentický a nezměněný.

Zabezpečení a správná funkční konfigurace v moderním digitálním vývojovém prostředí zkrátka vyžaduje pečlivost a pozornost k nejmenším detailům. Je to velmi podobné logice a postupu, jako když se rozhodujete u zásadních technických prvků pro váš hmotný majetek. Pokud například vybíráte výbavu na zimu pro svůj vůz, musíte si pečlivě promyslet parametry a důkladně si zjistit, jak vybrat plechové disky (tipy pro správnou volbu) pro optimální fitment, odolnost v drsném zimním prostředí a maximální možnou výdrž. Kdo sáhne po prvním náhodném řešení bez přemýšlení nad parametry, roztečí šroubů nebo průměrem středové díry, riskuje problémy s kompatibilitou a obrovské bezpečnostní ohrožení sebe i ostatních v provozu. U OIDC je technická konfigurace naštěstí vysoce automatizovaná a mnohem méně náchylná na lidskou chybu, pokud správně a dynamicky čtete data ze stanoveného koncového bodu.

Příklady z praxe: Google, Microsoft a další OIDC poskytovatelé

Zajímá vás, jak taková reálná a produkční data vypadají? Pokud chcete nahlédnout „pod pokličku“, můžete si jednoduše otevřít ve svém oblíbeném webovém prohlížeči následující adresy. Okamžitě zjistíte, že i ti největší technologičtí giganti na trhu s identitami naprosto striktně dodržují tuto standardizovanou architekturu:

• Google: Navštivte https://accounts.google.com/.well-known/openid-configuration. Z tohoto neustále aktualizovaného místa čerpají data úplně všechny známé knihovny z ekosystému, které aplikacím implementují oblíbené „Sign in with Google“ tlačítko.
• Microsoft Entra ID (dříve známé jako Azure Active Directory): Zkuste se podívat na https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Zde naopak naleznete zcela základní technický kámen jakékoli firemní korporátní autentizace směřující do M365 prostředí a interních firemních B2B aplikací.
• Služby jako Auth0 či Okta: Každý zákazník dostane k dispozici unikátní URL ve formátu https://{název-vašeho-tenanta}.auth0.com/.well-known/openid-configuration.

Každý z těchto vypsaných konfiguračních souborů se může v detailech drobně lišit (například celkovým počtem podporovaných dedikovaných claimů, rozsahem povolených kryptografických podepisovacích algoritmů jako je RS256 versus ES256 a podobně), ale fundamentální JSON struktura pečlivě definovaná v oficiální specifikaci OpenID Connect zůstává za všech okolností naprosto neměnná a konzistentní. Tato pevná standardizace je alfou i omegou v zajišťování úžasné interoperability mezi systémy pocházejícími od zcela různých dodavatelů z různých koutů světa.

Jak správně implementovat zjišťování OpenID do vaší aplikace

Většina moderních frameworků, backendových jazyků a pokročilých autentizačních knihoven (například Passport.js v ekosystému Node.js, populární NextAuth.js pro reactí webovky, robustní Spring Security v Javě nebo ASP.NET Core Identity od Microsoftu) již dnes naštěstí disponuje nativní podporou pro parsování OIDC Discovery. Tyto procesy jsou plně integrovány do jádra. Jako vývojář tak v ideálním scénáři zadáváte pouze kořenovou URL doménu vašeho zvoleného poskytovatele (plus patřičné tajné Client ID a Client Secret), přičemž o veškerý ten neviditelný „zbytek komunikace na pozadí“ se postará knihovna sama zcela automaticky.

Pokud byste se však z jakýchkoliv specifických studijních či architektonických důvodů rozhodli psát si integraci kompletně od nuly „na koleně“ (což nicméně pro produkční aplikace z ryze bezpečnostních důvodů opravdu silně nedoporučujeme), logický proces získání a ověření identity by vypadal zhruba následovně krok za krokem:

1. Záhy po samotném startu vaší aplikace (nebo opakovaně s logicky nastavenou dobou platnosti uchovávání v cache paměti) se provede zabezpečený asynchronní HTTP GET dotaz přesně na cestu /.well-known/openid-configuration vašeho předem definovaného Issuera.
2. Stažený JSON dokument se programaticky a bezpečně naparsuje a do globálních proměnných či interní paměti se načtou a uloží stěžejní hodnoty, primárně authorization_endpoint, token_endpoint a samozřejmě URI se seznamem klíčů.
3. Následně se z téže zjištěné bezpečné adresy uložené v klíči jwks_uri stáhne aktuálně platná sada distribuovaných veřejných klíčů dodavatele.
4. Kdykoli ve vaší aplikaci nastane okamžik, že potřebujete ověřit a přihlásit nového i stávajícího uživatele, vaše aplikace dynamicky složí URL adresu a provede bezpečné přesměrování uživatelova prohlížeče na stažený autorizační endpoint s mnoha důležitými příslušnými parametry (client_id, zvolený response_type a vyžadované scopes atd.).
5. V okamžiku, kdy vaše backendové API následně obdrží zažádaný ID Token, dojde k detailní technické kontrole hlavičky obsahující pole kid. Algoritmus následně z databáze cachovaných klíčů vybere ten správný veřejný klíč a kryptografický podpis tokenu pečlivě zvaliduje. Nastane-li situace, že klíč s takovým ID v mezipaměti aktuálně fyzicky nemáte (dodavatel např. provedl před okamžikem rotaci a nasadil nový), kód vyvolá obnovovací dotaz na jwks_uri s pokusem stáhnout ihned jeho nejnovější verzi.

Často je v komerčním softwarovém vývoji mnohem moudřejší a daleko bezpečnější sáhnout po široce podporované komunitní knihovně, která efektivně představuje jakýsi otestovaný hotový „all-in-one“ balíček. Je to v praxi podobně praktické jako onen široce oblíbený kompromisní a univerzální přístup, který motoristům na vozovce nabízí moderní celoroční pneu a užitečné informace, jak je poznat a proč si je vůbec vybrat. Místo toho, abyste na aplikaci neustále ručně a pracně „přezouvali kód“ a zbytečně psali a udržovali nesmírně komplexní vlastní validátory závislé na aktuální revizi internetového standardu, zkrátka úspěšně nasadíte mnoha audity prověřené univerzální řešení. Taková knihovna poté nepozorovaně a na pozadí hladce zvládne obstarat naprostou většinu veškerých myslitelných bezpečnostních situací a edge cases spolehlivě a hlavně maximálně bezpečně. Navíc si poté můžete v naprostém klidu, a díky využití moderních frontendových frameworků velmi snadno, graficky přizpůsobit vizuální vzhled přihlašovací i registrační stránky dokonale k obrazu svému firemnímu brandu – je to stejné svobodné vyjádření designu a kreativity, jako když například řešíte pro svého plechového miláčka dilema, jakou barvu na plechové disky (inspirace) finálně zvolit pro ten nejvíce jedinečný a osobitý vzhled sportovního vozidla.

Časté chyby a problémy s OpenID konfigurací

I přesto, že se zdá být celý OIDC mechanismus na první pohled plně automatický a v podstatě bezproblémový, programátoři a DevOps inženýři mohou během implementace do systémů velice snadno narazit na několik kritických bezpečnostních a konfiguračních úskalí. Zde uvádíme ty vůbec nejzávažnější a nejčastější omyly:

• Tvrdé kódování a vypisování adres (Hardcoding): Občas se nezkušení vývojáři podívají do dodaného JSON dokumentu ve svém prohlížeči pouze jedinkrát. Cesty a URL parametry, které potřebují (zejména například samotné odkazované URL pro onen jwks_uri certifikátový koncový bod, případně token_endpoint URL), si zkopírují jako holý text „natvrdo“ hluboko do interního zdrojového kódu dané platformy. Toto je naprostý anti-pattern! Pokud Identity Provider (např. v rámci interního přechodu či z mnoha jiných oprávněných důvodů) tyto dlouhé a složité síťové cesty v dohledné i vzdálené budoucnu jakkoliv změní, vaše aplikace z minuty na minutu náhle zcela selže a absolutně přestane fungovat pro přihlašování tisíců zákazníků. Vždy se vyvarujte pevných adres a aktivně a pravidelně využívejte dynamické automatické načítání přes základní kořenový Discovery dokument.
• Nesprávný a opomíjený Issuer: Velice obrovské, až alarmující procento vážných bezpečnostních a implementačních chyb při zpracování JWT validace reálně v praxi vzniká právě kvůli nedokonalé neshodě a opomenutí v claimu iss. Tento jednoznačný stringový identifikátor daného vydavatele a samotného serveru se musí za všech myslitelných okolností naprosto strojově přesně a naprosto znakově shodovat s definovanou hodnotou nacházející se v JSON poli issuer zjištěného zevnitř centrálního konfiguračního OpenID souboru. A pozor na past – na tomto místě to platí včetně mnohokrát zrádných obyčejných koncových lomítek na úplném konci samotné URL domény! Pokud se liší, knihovny token z bezpečnostních důvodů nekompromisně a potichu zahodí.
• Až příliš agresivní a neodpovídající ukládání do cachovací paměti: Vhodné softwarové cachování je bezpochyby pro celkový výkon a optimalizaci rychlosti aplikace absolutně klíčové, snižuje též obří nápor na servery. Veliké nebezpečí ale spočívá v momentě, kdy systém naprosto špatně nastaví platnost a aplikace cachuje načtenou datovou odpověď získanou z koncového bodu jwks_uri navždy a zcela „na věčné časy“. Jakmile poté samotný poskytovatel zcela standardně a plánovaně z jakéhokoliv oprávněného důvodu zarotuje nové asymetrické podpisové klíče (často automatizovaně, například z důvodu vypršení starých certifikátů), v ten samý okamžik okamžitě začnou v masovém měřítku nevratně selhávat všechny kryptografické verifikace certifikačních podpisů u všech nově pořízených tokenů pro veškeré uživatele. Musíte vždy prozíravě nastavit nějakou konkrétní, technicky smysluplnou a omezenou životnost ukládané interní paměti (Time To Live mezipaměti). Pro zachování plně bezpečného stavu ideálně doporučujeme nekompromisně naimplementovat stahování nových klíčů reaktivně a s ohledem na chyby – tedy stahovat okamžitě ve chvíli selhání nebo když ve vráceném tokenu zničehonic poprvé narazíte na pro vás zcela neznámé identifikační kid!
• Zcela nepochopitelné ignorování mikrovýpadků a síťových komunikačních chybových stavů: První fáze a inicializace stažení celkové OIDC konfigurace nekompromisně a ve vší parádě striktně vyžaduje rychlou a navazující bezproblémovou komunikaci s externími poskytovateli po venkovní síti a celosvětovém internetu. Pokud má celá integrace dlouhodobě přežít, vaše robustní serverová aplikace musí disponovat kódem, jenž bude ze samotného principu plně připravený a dokonale odolný proti mnoha potenciálním a naprosto občasným lokálním či infrastrukturním výpadkům internetové konektivity a směrování (ať už během ranního ostrého startu dané služby či při náhodných opožděných dotazech na snahu opětovně aktualizovat a stáhnout starší certifikační rotované asymetrické sady a podobně). Profesionální a proaktivní nasazení funkčního mechanismu s implementovaným „retry patterns“ (logikou vícenásobného inteligentního opakování dotazů pro opětovné spojení chytře ošetřeného s pomocí patřičného, postupně rostoucího algoritmického časového zpoždění – takzvaný exponenciální síťový backoff a jitter mechanismy) je z celosvětových best practices pro OIDC vysoce doporučováno pro co nejlepší uživatelský UX standard aplikací.

Shrneme-li výše probrané, zcela suverénním závěrem tak logicky zůstává ten fakt, že samotný textový soubor umístěný na stabilním endpointu .well-known/openid-configuration na všech webech je jednoznačně zcela stěžejním, fundamentálním a jednoduše neocenitelným nástrojem pro dnešní rutinní budování zcela robustních a propracovaných distribuovaných dynamických systémů správy centrálních identit uživatelů. Jeho hluboké programátorské pochopení a následně bezchybná technická kódová implementace vás ušetří bezpočtu zbytečných infarktových vteřin, frustrace, desítek zahozených hodin ladění komplikovaných chyb za běhu a zcela na maximum především razantně, bez kompromisů a s jistotou posílí celkovou bezpečnostní identitní architekturu vašich budoucích moderních digitálních byznysových i komunitních projektů.