Nabídka dokumentace
Pro konkrétního partnera Naposledy aktualizováno: 27. července 2026

Autentizace

Implementujte tok s autorizačním kódem, ověřujte tokeny identity Parkour Design a spravujte rotované obnovovací tokeny.

Tento dokument popisuje aktuálně implementovaný tok pro důvěrnou partnerskou aplikaci, která se připojuje k Parkour Design. Registrace klienta a produkční přístup vyžadují technické a bezpečnostní schválení.

Současný kontrakt: Protokol je nasazený a používá se pro koordinované integrace. Nejde o samoobslužnou autorizační službu. Parkour Design poskytne ID klienta, tajný klíč klienta, registrované URI přesměrování a povolené scope zabezpečeným kanálem.

Prostředí a discovery

Místo ručního sestavování URL endpointů použijte OpenID Connect discovery.

ProstředíVydavatelDokument discovery
Produkcehttps://app.parkour.designhttps://app.parkour.design/.well-known/openid-configuration
Testhttps://parkour-test.web.apphttps://parkour-test.web.app/.well-known/openid-configuration

Dokument discovery načtěte při spuštění aplikace, uložte ho do mezipaměti na omezenou dobu a obnovte ho při změně podpisových klíčů. Vyžadujte, aby vrácený issuer přesně odpovídal nakonfigurovanému vydavateli.

Současný dokument discovery zveřejňuje:

FunkceSoučasná hodnota
Typ odpovědicode
Typy uděleníauthorization_code, refresh_token
Autentizace klientaclient_secret_basic, client_secret_post
Podpis ID tokenuRS256
Metody PKCES256, plain
Scopeopenid, profile, email
Nárokysub, email, email_verified, name

Používejte client_secret_basic a PKCE S256. Nepoužívejte plain, i když ho současný server z důvodů kompatibility inzeruje.

Předpoklady registrace

Před implementací pošlete Parkour Design:

  • název aplikace a technického vedoucího;
  • testovací a produkční URI přesměrování;
  • požadované scope a uživatelskou cestu;
  • kontakty pro předání a rotaci přihlašovacích údajů;
  • požadavky na odhlášení, odpojení účtů a uchovávání dat.

URI přesměrování se porovnávají přesně. Schéma, hostitel, port, cesta, velikost písmen i koncové lomítko musí odpovídat registrované hodnotě. Použijte callback bez existujícího řetězce dotazu nebo fragmentu.

Současná služba podporuje důvěrné backendové klienty. Klienti běžící jen v prohlížeči a veřejné nativní klienty podporováni nejsou, protože každý požadavek na token vyžaduje tajný klíč klienta.

Autorizační sekvence

1. Vytvoření transakce prohlížeče

Vytvořte a uložte na serveru:

  • jednorázovou hodnotu state s vysokou entropií;
  • OIDC nonce s vysokou entropií;
  • ověřovač PKCE a jeho výzvu SHA-256;
  • cíl po přihlášení;
  • krátkou dobu platnosti.

Hodnoty svažte s relací prohlížeče uživatele. Tajný klíč klienta, ověřovač ani tokeny nikdy nevkládejte do URL.

2. Přesměrování uživatele

Autorizační URL sestavte z authorization_endpoint v dokumentu discovery:

GET {authorization_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={url_encoded_registered_redirect_uri}
  &scope={url_encoded_approved_scopes}
  &state={state}
  &nonce={nonce}
  &code_challenge={base64url_sha256_verifier}
  &code_challenge_method=S256

Používejte jen scope schválené při registraci klienta. openid email profile je příklad pro případ, kdy byly schváleny všechny tři scope; požadavek na neschválený scope vrátí invalid_scope.

Parkour Design uživatele ověří a požádá o souhlas. Úspěšná odpověď vrátí:

{redirect_uri}?code={authorization_code}&state={state}

Zamítnutý požadavek vrátí:

{redirect_uri}?error=access_denied&state={state}

3. Ověření callbacku

Před výměnou kódu:

  1. odmítněte chybějící nebo neočekávaný state;
  2. odmítněte transakci prohlížeče, která vypršela nebo už byla použita;
  3. transakci spotřebujte, aby callback nešlo přehrát znovu;
  4. zpracujte OAuth error bez pokusu o výměnu tokenu.

Autorizační kódy vyprší po pěti minutách a lze je použít jednou.

4. Výměna kódu na serveru

Pošlete z backendu partnera formulářově kódovaný požadavek:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

redirect_uri musí být shodné s hodnotou v autorizačním požadavku.

Úspěšná odpověď má v současnosti tento tvar:

{
  "access_token": "<signed JWT>",
  "refresh_token": "<opaque token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "email openid profile",
  "id_token": "<signed JWT>"
}

Odpovědi s tokeny používají Cache-Control: no-store a Pragma: no-cache. id_token se vrací jen tehdy, když byl udělen openid.

Ověření identity

Před vytvořením partnerské relace ověřte ID token:

  1. načtěte klíče z jwks_uri v dokumentu discovery;
  2. zvolte klíč určený kid v JWT;
  3. vyžadujte podpis RS256;
  4. vyžadujte přesnou shodu vydavatele;
  5. vyžadujte ID klienta jako cílovou skupinu (audience);
  6. ověřte dobu vypršení a vydání s malou tolerancí odchylky hodin;
  7. vyžadujte původní nonce;
  8. používejte sub jako stabilní identifikátor uživatele v Parkour Design.

Současné nároky v ID tokenu:

{
  "iss": "https://app.parkour.design",
  "sub": "<opaque Parkour Design user ID>",
  "aud": "<client ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User",
  "token_use": "id_token",
  "iat": 0,
  "exp": 0,
  "nonce": "<authorization nonce>"
}

Nepropojujte účty jen podle e-mailu. Jako klíč externí identity ukládejte iss a sub. E-mail a jméno považujte za proměnlivé atributy profilu.

UserInfo je dostupné, když přístupový token obsahuje openid:

curl "${USERINFO_ENDPOINT}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"
{
  "sub": "<opaque Parkour Design user ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User"
}

Přístupové a obnovovací tokeny

TokenŽivotnostZacházení v klientovi
Autorizační kód5 minutVyměnit jednou a po použití nikdy neukládat
ID token15 minutOvěřit jednou; nepoužívat jako bearer token pro API
Přístupový token15 minutDržet na serveru a posílat jen do API zdrojů Parkour Design
Obnovovací token30 dníŠifrovat při uložení a po každém obnovení atomicky nahradit

Obnovovací tokeny se rotují při každém úspěšném použití:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

Odpověď obsahuje nový přístupový token a náhradní obnovovací token. Neobsahuje nový ID token. Obnovení pro každého uživatele a relaci klienta provádějte postupně a uložený obnovovací token pak atomicky nahraďte. Opětovné použití starého tokenu vrátí invalid_grant.

Parkour Design starý obnovovací token spotřebuje dřív, než vrátí náhradu. Pokud je výsledek kvůli vypršení času nebo ztracené odpovědi neznámý, neopakujte požadavek naslepo se starým tokenem. Smažte místní stav tokenů a zahajte nový autorizační tok. Souběžná obnovení pro stejnou relaci vytvářejí stejné riziko pro obnovu.

Současná životnost obnovení je klouzavá: každá úspěšná rotace zahájí novou 30denní životnost. Parkour Design v současnosti nemá endpointy pro odvolání ani introspekci tokenů. Odpojení v partnerské aplikaci musí smazat její uložené tokeny. Přístupový token může zůstat platný až do vypršení po 15 minutách.

Použití přístupových tokenů pro API

Přístupové tokeny Parkour Design mají vždy cílovou skupinu parkour-api. Jsou přihlašovacími údaji jen pro API zdrojů Parkour Design popsaná v části Výměna dat. Nikdy je nepředávejte do API partnera ani žádné jiné třetí straně; zdroje provozované partnerem musí používat vlastní autorizační mechanismus.

ID token stanoví identitu a partnerskou relaci. K volání žádného API ID token nepoužívejte.

Současné chování scope

Současné scope identity jsou openid, email a profile. Koordinované API zdrojů v současnosti autorizuje přístup k akcím a souhrnům projektů pomocí openid; zatím nemá vyhrazené scope pro čtení.

Jde o omezení současné implementace, ne o vzor pro nová API. Požadované scope a dostupné zdroje se potvrzují při registraci klienta. Budoucí kontrakty zdrojů mohou zavést vyhrazené scope.

Současné tokeny a UserInfo obsahují e-mail a jméno v širším rozsahu, než naznačují jednotlivé scope email a profile. Klienti přesto mají žádat jen schválené scope a nesmějí spoléhat na to, že širší chování zůstane beze změny.

Zpracování chyb

Autorizační endpoint má dva kanály chyb:

  • po ověření URI přesměrování se zamítnutý souhlas a některé chyby invalid_request při zpracování souhlasu přesměrují na callback s error a původním state;
  • chyby ověření dřív, než je stanoven důvěryhodný callback, včetně chyb klienta, URI přesměrování, scope, typu odpovědi a PKCE, vrátí přímou odpověď HTTP 400 v JSON.

Chyby tokenů a API zdrojů také používají kompaktní tělo JSON:

{"error": "invalid_grant"}
ChybaVýznam
invalid_clientChybějící, neznámý, neaktivní nebo nesprávně ověřený klient
invalid_redirect_uriChybějící nebo neregistrovaná URI callbacku; jde o kód specifický pro současnou implementaci Parkour Design
invalid_scopePrázdná nebo neschválená sada scope
invalid_requestChybějící pole nebo neplatná kombinace PKCE
access_deniedUživatel odmítl souhlas
invalid_grantNeplatný, vypršelý, opakovaně použitý nebo nesprávně svázaný kód či obnovovací token
unsupported_response_typeJiná autorizační odpověď než code
unsupported_grant_typeNepodporovaný typ udělení tokenu
invalid_tokenChybějící, chybně formátovaný, vypršelý nebo neplatný bearer token pro API

Nezobrazujte koncovým uživatelům surové odpovědi s tokeny ani diagnostiku protokolu. Logujte ID korelace, endpoint, stav a bezpečný kód chyby, aniž byste logovali kódy, tokeny, tajné klíče, hodnoty nonce nebo osobní údaje.

Současná omezení

  • Registrace klientů a odvolání souhlasu se koordinují ručně.
  • PKCE, state a nonce server přijímá, ale nekontroluje; partnerští klienti je kontrolovat musí.
  • Discovery inzeruje PKCE plain; partnerští klienti musí používat S256.
  • Neexistují endpointy pro odvolání, introspekci, dynamickou registraci ani standardizované ukončení relace.
  • Opětovné použití obnovovacího tokenu neodvolá celou rodinu tokenů.
  • Přístupové tokeny zůstávají po místním odhlášení platné až do vypršení.
  • Současná autorizace zdrojů používá openid místo vyhrazených scope zdrojů.

Omezení projděte během zavádění a tiše je nenahrazujte předpoklady z jiného poskytovatele OAuth.