Dokumentationsmeny
Partnerspecifik Senast uppdaterad: 27 juli 2026

Autentisering

Implementera flödet med auktoriseringskod, validera Parkour Designs identitetstoken och hantera förnyelsetoken som roteras.

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ärdareDiscovery-dokument
Produktionhttps://app.parkour.designhttps://app.parkour.design/.well-known/openid-configuration
Testhttps://parkour-test.web.apphttps://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:

FunktionNuvarande värde
Svarstypcode
Beviljandetyperauthorization_code, refresh_token
Klientautentiseringclient_secret_basic, client_secret_post
Signering av ID-tokenRS256
PKCE-metoderS256, plain
Scopeopenid, profile, email
Anspråksub, 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 state med hög entropi;
  • en OIDC-nonce med 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:

  1. avvisa ett saknat eller oväntat state;
  2. avvisa en webbläsartransaktion som har gått ut eller redan använts;
  3. förbruka transaktionen så att callbacken inte kan spelas upp igen;
  4. hantera ett OAuth-error utan 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:

  1. hämta nycklar från jwks_uri i discovery;
  2. välj nyckeln som anges av JWT:ns kid;
  3. kräv en RS256-signatur;
  4. kräv exakt överensstämmelse med utfärdaren;
  5. kräv klient-ID:t som målgrupp;
  6. validera utgångstid och utfärdandetid med en liten marginal för klockavvikelse;
  7. kräv den ursprungliga nonce;
  8. använd sub som 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

TokenLivslängdHantering i klienten
Auktoriseringskod5 minuterByt en gång och spara aldrig efter användning
ID-token15 minuterValidera en gång; använd inte som bearer-token för API
Åtkomsttoken15 minuterBehåll på servern och skicka bara till Parkour Designs resurs-API:er
Förnyelsetoken30 dagarKryptera 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 med error och det ursprungliga state;
  • 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"}
FelBetydelse
invalid_clientSaknad, okänd, inaktiv eller felaktigt autentiserad klient
invalid_redirect_uriSaknad eller oregistrerad callback-URI; det här är en kod som är specifik för Parkour Designs nuvarande implementering
invalid_scopeTom eller icke godkänd uppsättning scope
invalid_requestSaknade fält eller ogiltig kombination för PKCE
access_deniedAnvändaren nekade samtycke
invalid_grantOgiltig, utgången, återanvänd eller felaktigt bunden kod eller förnyelsetoken
unsupported_response_typeAnnat auktoriseringssvar än code
unsupported_grant_typeBeviljandetyp för token som inte stöds
invalid_tokenSaknad, 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, state och nonce accepteras men kontrolleras inte av servern; partnerklienterna måste kontrollera dem.
  • Discovery annonserar PKCE plain; partnerklienterna måste använda S256.
  • 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 openid i 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.