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í | Vydavatel | Dokument discovery |
|---|---|---|
| Produkce | https://app.parkour.design | https://app.parkour.design/.well-known/openid-configuration |
| Test | https://parkour-test.web.app | https://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:
| Funkce | Současná hodnota |
|---|---|
| Typ odpovědi | code |
| Typy udělení | authorization_code, refresh_token |
| Autentizace klienta | client_secret_basic, client_secret_post |
| Podpis ID tokenu | RS256 |
| Metody PKCE | S256, plain |
| Scope | openid, profile, email |
| Nároky | sub, 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
states vysokou entropií; - OIDC
nonces 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:
- odmítněte chybějící nebo neočekávaný
state; - odmítněte transakci prohlížeče, která vypršela nebo už byla použita;
- transakci spotřebujte, aby callback nešlo přehrát znovu;
- zpracujte OAuth
errorbez 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:
- načtěte klíče z
jwks_uriv dokumentu discovery; - zvolte klíč určený
kidv JWT; - vyžadujte podpis
RS256; - vyžadujte přesnou shodu vydavatele;
- vyžadujte ID klienta jako cílovou skupinu (audience);
- ověřte dobu vypršení a vydání s malou tolerancí odchylky hodin;
- vyžadujte původní
nonce; - používejte
subjako 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 | Životnost | Zacházení v klientovi |
|---|---|---|
| Autorizační kód | 5 minut | Vyměnit jednou a po použití nikdy neukládat |
| ID token | 15 minut | Ověřit jednou; nepoužívat jako bearer token pro API |
| Přístupový token | 15 minut | Držet na serveru a posílat jen do API zdrojů Parkour Design |
| Obnovovací token | 30 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_requestpři zpracování souhlasu přesměrují na callback serrora původnímstate; - 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
400v JSON.
Chyby tokenů a API zdrojů také používají kompaktní tělo JSON:
{"error": "invalid_grant"}
| Chyba | Význam |
|---|---|
invalid_client | Chybějící, neznámý, neaktivní nebo nesprávně ověřený klient |
invalid_redirect_uri | Chybějící nebo neregistrovaná URI callbacku; jde o kód specifický pro současnou implementaci Parkour Design |
invalid_scope | Prázdná nebo neschválená sada scope |
invalid_request | Chybějící pole nebo neplatná kombinace PKCE |
access_denied | Uživatel odmítl souhlas |
invalid_grant | Neplatný, vypršelý, opakovaně použitý nebo nesprávně svázaný kód či obnovovací token |
unsupported_response_type | Jiná autorizační odpověď než code |
unsupported_grant_type | Nepodporovaný typ udělení tokenu |
invalid_token | Chybě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,
stateanonceserver přijímá, ale nekontroluje; partnerští klienti je kontrolovat musí. - Discovery inzeruje PKCE
plain; partnerští klienti musí používatS256. - 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á
openidmí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.