Det här dokumentet beskriver det nu implementerade flödet för ett konfidentiellt partnerprogram som ansluter till Parkour Design. Klientregistrering och produktionsåtkomst kräver tekniskt godkännande och säkerhetsgodkännande.
Nuvarande kontrakt: Protokollet är driftsatt och används för samordnade integrationer. Det är ingen auktoriseringstjänst på egen hand. Parkour Design tillhandahåller klient-ID, klienthemlighet, registrerade omdirigerings-URI:er och tillåtna scope via en säker kanal.
Miljöer och discovery
Använd OpenID Connect discovery i stället för att bygga slutpunkternas URL:er själv.
| Miljö | Utfärdare | Discovery-dokument |
|---|---|---|
| Produktion | 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 |
Hämta discovery när programmet startar, cacha det under en begränsad tid och uppdatera det när signeringsnycklarna ändras. Kräv att den returnerade issuer exakt stämmer med den konfigurerade utfärdaren.
Det nuvarande discovery-dokumentet publicerar:
| Funktion | Nuvarande värde |
|---|---|
| Svarstyp | code |
| Beviljandetyper | authorization_code, refresh_token |
| Klientautentisering | client_secret_basic, client_secret_post |
| Signering av ID-token | RS256 |
| PKCE-metoder | S256, plain |
| Scope | openid, profile, email |
| Anspråk | sub, email, email_verified, name |
Använd client_secret_basic och PKCE S256. Använd inte plain, även om den nuvarande servern annonserar det av kompatibilitetsskäl.
Förutsättningar för registrering
Skicka följande till Parkour Design före implementeringen:
- programmets namn och tekniskt ansvarig;
- omdirigerings-URI:er för test och produktion;
- begärda scope och användarresa;
- kontakter för leverans och rotation av inloggningsuppgifter;
- krav på utloggning, frånkoppling av konton och lagring.
Omdirigerings-URI:er matchas exakt. Schema, värd, port, sökväg, skiftläge och avslutande snedstreck måste stämma med det registrerade värdet. Använd en callback utan befintlig frågesträng eller fragment.
Den nuvarande tjänsten stöder konfidentiella backend-klienter. Klienter som bara körs i webbläsaren och publika nativa klienter stöds inte, eftersom varje begäran om token kräver en klienthemlighet.
Auktoriseringssekvens
1. Skapa webbläsartransaktionen
Skapa och lagra på servern:
- ett engångsvärde
statemed hög entropi; - en OIDC-
noncemed hög entropi; - en PKCE-verifierare och dess SHA-256-utmaning;
- målet efter inloggningen;
- en kort utgångstid.
Bind värdena till användarens webbläsarsession. Lägg aldrig klienthemligheten, verifieraren eller token i en URL.
2. Omdirigera användaren
Bygg auktoriserings-URL:en från authorization_endpoint i 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
Använd bara de scope som godkändes vid klientregistreringen. openid email profile är ett exempel när alla tre scope har godkänts; begäran om ett scope som inte är godkänt returnerar invalid_scope.
Parkour Design autentiserar användaren och ber om samtycke. Ett lyckat svar returnerar:
{redirect_uri}?code={authorization_code}&state={state}
En nekad begäran returnerar:
{redirect_uri}?error=access_denied&state={state}
3. Validera callbacken
Innan koden byts ut:
- avvisa ett saknat eller oväntat
state; - avvisa en webbläsartransaktion som har gått ut eller redan använts;
- förbruka transaktionen så att callbacken inte kan spelas upp igen;
- hantera ett OAuth-
errorutan att försöka byta token.
Auktoriseringskoder går ut efter fem minuter och kan användas en gång.
4. Byt koden på servern
Skicka en formulärkodad begäran från partnerns backend:
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 måste vara identisk med värdet i auktoriseringsbegäran.
Ett lyckat svar har för närvarande den här formen:
{
"access_token": "<signed JWT>",
"refresh_token": "<opaque token>",
"token_type": "Bearer",
"expires_in": 900,
"scope": "email openid profile",
"id_token": "<signed JWT>"
}
Svar med token använder Cache-Control: no-store och Pragma: no-cache. id_token returneras bara när openid har beviljats.
Validera identiteten
Validera ID-token innan du skapar en partnersession:
- hämta nycklar från
jwks_urii discovery; - välj nyckeln som anges av JWT:ns
kid; - kräv en
RS256-signatur; - kräv exakt överensstämmelse med utfärdaren;
- kräv klient-ID:t som målgrupp;
- validera utgångstid och utfärdandetid med en liten marginal för klockavvikelse;
- kräv den ursprungliga
nonce; - använd
subsom den stabila identifieraren för användaren i Parkour Design.
Nuvarande anspråk i ID-token:
{
"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>"
}
Koppla inte konton enbart via e-post. Lagra iss och sub som nyckel för den externa identiteten. Behandla e-post och namn som profilattribut som kan ändras.
UserInfo är tillgängligt när åtkomsttoken innehåller 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"
}
Åtkomst- och förnyelsetoken
| Token | Livslängd | Hantering i klienten |
|---|---|---|
| Auktoriseringskod | 5 minuter | Byt en gång och spara aldrig efter användning |
| ID-token | 15 minuter | Validera en gång; använd inte som bearer-token för API |
| Åtkomsttoken | 15 minuter | Behåll på servern och skicka bara till Parkour Designs resurs-API:er |
| Förnyelsetoken | 30 dagar | Kryptera vid lagring och ersätt atomärt efter varje förnyelse |
Förnyelsetoken roteras vid varje lyckad användning:
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}"
Svaret innehåller en ny åtkomsttoken och en ersättande förnyelsetoken. Det innehåller ingen ny ID-token. Kör förnyelser i tur och ordning för varje användare och klientsession och ersätt sedan den lagrade förnyelsetoken atomärt. En gammal token som återanvänds returnerar invalid_grant.
Parkour Design förbrukar den gamla förnyelsetoken innan ersättaren returneras. Om en timeout eller ett förlorat svar gör resultatet okänt, försök inte igen blint med den gamla token. Ta bort det lokala tokentillståndet och starta ett nytt auktoriseringsflöde. Samtidiga förnyelser för samma session skapar samma återställningsrisk.
Den nuvarande livslängden för förnyelse är glidande: varje lyckad rotation startar en ny livslängd på 30 dagar. Parkour Design har för närvarande inga slutpunkter för återkallande eller introspektion av token. Frånkoppling i partnerprogrammet måste ta bort dess lagrade token. En åtkomsttoken kan vara giltig tills den går ut efter 15 minuter.
Använda åtkomsttoken för API
Parkour Designs åtkomsttoken har alltid målgruppen parkour-api. De är inloggningsuppgifter bara för Parkour Designs resurs-API:er som beskrivs i Datautbyte. Skicka dem aldrig vidare till ett partner-API eller någon annan tredje part; resurser som partnern driver måste använda sin egen auktoriseringsmekanism.
ID-token fastställer identiteten och en partnersession. Använd inte en ID-token för att anropa något API.
Nuvarande beteende för scope
De nuvarande identitetsscopen är openid, email och profile. Det samordnade resurs-API:et auktoriserar för närvarande åtkomst till evenemang och sammanfattningar av projekt med openid; det har ännu inga särskilda lässcope.
Det här är en begränsning i den nuvarande implementeringen, inte ett mönster för nya API:er. Begärda scope och tillgängliga resurser bekräftas vid klientregistreringen. Framtida resurskontrakt kan införa särskilda scope.
Nuvarande token och UserInfo innehåller e-post och namn i större utsträckning än de enskilda scopen email och profile anger. Klienter ska ändå bara begära godkända scope och får inte förlita sig på att det bredare beteendet förblir oförändrat.
Felhantering
Auktoriseringsslutpunkten har två kanaler för fel:
- efter att en omdirigerings-URI har validerats omdirigeras nekat samtycke och vissa
invalid_request-fel vid behandling av samtycke till callbacken mederroroch det ursprungligastate; - valideringsfel innan en betrodd callback har fastställts, bland annat fel för klient, omdirigerings-URI, scope, svarstyp och PKCE, returnerar ett direkt HTTP
400-svar i JSON.
Fel från token- och resurs-API:er använder också en kompakt JSON-kropp:
{"error": "invalid_grant"}
| Fel | Betydelse |
|---|---|
invalid_client | Saknad, okänd, inaktiv eller felaktigt autentiserad klient |
invalid_redirect_uri | Saknad eller oregistrerad callback-URI; det här är en kod som är specifik för Parkour Designs nuvarande implementering |
invalid_scope | Tom eller icke godkänd uppsättning scope |
invalid_request | Saknade fält eller ogiltig kombination för PKCE |
access_denied | Användaren nekade samtycke |
invalid_grant | Ogiltig, utgången, återanvänd eller felaktigt bunden kod eller förnyelsetoken |
unsupported_response_type | Annat auktoriseringssvar än code |
unsupported_grant_type | Beviljandetyp för token som inte stöds |
invalid_token | Saknad, felformaterad, utgången eller ogiltig bearer-token för API |
Visa inte råa tokensvar eller protokolldiagnostik för slutanvändaren. Logga ett korrelations-ID, slutpunkt, status och en säker felkod utan att logga koder, token, hemligheter, nonce-värden eller personuppgifter.
Nuvarande begränsningar
- Klientregistrering och återkallande av samtycke samordnas manuellt.
- PKCE,
stateochnonceaccepteras men kontrolleras inte av servern; partnerklienterna måste kontrollera dem. - Discovery annonserar PKCE
plain; partnerklienterna måste användaS256. - Det finns inga slutpunkter för återkallande, introspektion, dynamisk registrering eller standardiserad avslutning av session.
- Återanvändning av förnyelsetoken återkallar inte hela tokenfamiljen.
- Åtkomsttoken förblir giltiga tills de går ut efter lokal utloggning.
- Den nuvarande auktoriseringen av resurser använder
openidi stället för särskilda resursscope.
Gå igenom begränsningarna under introduktionen och ersätt dem inte i tysthet med antaganden från en annan OAuth-leverantör.