Dokumentationsmenu
Partnerspecifik Senest opdateret: 27. juli 2026

Autentificering

Implementér flowet med autorisationskode, validér Parkour Designs ID-tokens, og håndtér refresh tokens, der roteres.

Dette dokument beskriver det aktuelt implementerede flow for et fortroligt partnerprogram, der forbinder sig med Parkour Design. Klientregistrering og produktionsadgang kræver teknisk godkendelse og sikkerhedsgodkendelse.

Nuværende kontrakt: Protokollen er i drift og bruges til koordinerede integrationer. Det er ikke en selvbetjent autorisationstjeneste. Parkour Design leverer klient-ID, client secret, registrerede redirect-URI’er og tilladte scopes via en sikker kanal.

Miljøer og discovery

Brug OpenID Connect discovery i stedet for selv at opbygge endpoints’ URL’er.

MiljøUdstederDiscovery-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

Hent discovery, når programmet starter, cache det i en begrænset periode, og opdater det, når signeringsnøglerne ændres. Kræv, at den returnerede issuer stemmer præcist med den konfigurerede udsteder.

Det nuværende discovery-dokument offentliggør:

FunktionNuværende værdi
Svartypecode
Grant-typerauthorization_code, refresh_token
Klientautentificeringclient_secret_basic, client_secret_post
Signering af ID-tokenRS256
PKCE-metoderS256, plain
Scopesopenid, profile, email
Claimssub, email, email_verified, name

Brug client_secret_basic og PKCE S256. Brug ikke plain, selv om den nuværende server annoncerer det af kompatibilitetshensyn.

Forudsætninger for registrering

Send følgende til Parkour Design før implementeringen:

  • programmets navn og teknisk ansvarlig;
  • redirect-URI’er til test og produktion;
  • ønskede scopes og brugerrejse;
  • kontakter til levering og rotation af loginoplysninger;
  • krav til logud, frakobling af konti og opbevaring.

Redirect-URI’er matches præcist. Skema, vært, port, sti, store og små bogstaver og afsluttende skråstreg skal stemme med den registrerede værdi. Brug en callback uden eksisterende forespørgselsstreng eller fragment.

Den nuværende tjeneste understøtter fortrolige backend-klienter. Klienter, der kun kører i browseren, og offentlige native klienter understøttes ikke, fordi hver tokenanmodning kræver en client secret.

Autorisationsforløb

1. Opret browsertransaktionen

Opret og gem på serveren:

  • en engangsværdi state med høj entropi;
  • en OIDC-nonce med høj entropi;
  • en PKCE-verifier og dens SHA-256-challenge;
  • destinationen efter login;
  • en kort udløbstid.

Bind værdierne til brugerens browsersession. Læg aldrig client secret, verifier eller tokens i en URL.

2. Omdiriger brugeren

Opbyg autorisations-URL’en ud fra 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

Brug kun de scopes, der blev godkendt ved klientregistreringen. openid email profile er et eksempel, når alle tre scopes er godkendt; en anmodning om et scope, der ikke er godkendt, returnerer invalid_scope.

Parkour Design autentificerer brugeren og beder om samtykke. Et vellykket svar returnerer:

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

En afvist anmodning returnerer:

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

3. Validér callbacken

Før koden udveksles:

  1. afvis et manglende eller uventet state;
  2. afvis en browsertransaktion, der er udløbet eller allerede brugt;
  3. forbrug transaktionen, så callbacken ikke kan afspilles igen;
  4. håndtér en OAuth-error uden at forsøge at udveksle token.

Autorisationskoder udløber efter fem minutter og kan bruges én gang.

4. Udveksl koden på serveren

Send en formularkodet anmodning fra partnerens 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 skal være identisk med værdien i autorisationsanmodningen.

Et vellykket svar har i øjeblikket denne form:

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

Svar med tokens bruger Cache-Control: no-store og Pragma: no-cache. id_token returneres kun, når openid er givet.

Validér identiteten

Validér ID-tokenet, før du opretter en partnersession:

  1. hent nøgler fra jwks_uri i discovery;
  2. vælg den nøgle, der angives af JWT’ens kid;
  3. kræv en RS256-signatur;
  4. kræv præcis overensstemmelse med udstederen;
  5. kræv klient-ID’et som audience;
  6. validér udløbstid og udstedelsestid med en lille margen for urforskydning;
  7. kræv den oprindelige nonce;
  8. brug sub som den stabile identifikator for brugeren i Parkour Design.

Nuværende claims i ID-tokenet:

{
  "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>"
}

Forbind ikke konti kun via e-mail. Gem iss og sub som nøgle for den eksterne identitet. Behandl e-mail og navn som profilattributter, der kan ændres.

UserInfo er tilgængeligt, når adgangstokenet indeholder 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"
}

Adgangstokens og refresh tokens

TokenLevetidHåndtering i klienten
Autorisationskode5 minutterUdveksl én gang, og gem aldrig efter brug
ID-token15 minutterValidér én gang; brug ikke som bearer token til API
Adgangstoken15 minutterBehold på serveren, og send kun til Parkour Designs ressource-API’er
Refresh token30 dageKryptér ved lagring, og erstat atomisk efter hver fornyelse

Refresh tokens roteres ved hver vellykket brug:

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 indeholder et nyt adgangstoken og et erstattende refresh token. Det indeholder ikke et nyt ID-token. Kør fornyelser efter hinanden for hver bruger og klientsession, og erstat derefter det gemte refresh token atomisk. Et gammelt token, der genbruges, returnerer invalid_grant.

Parkour Design forbruger det gamle refresh token, før erstatningen returneres. Hvis en timeout eller et mistet svar gør resultatet usikkert, så prøv ikke blindt igen med det gamle token. Slet den lokale tokentilstand, og start et nyt autorisationsflow. Samtidige fornyelser for den samme session skaber den samme genoprettelsesrisiko.

Den nuværende levetid for fornyelse er glidende: hver vellykket rotation starter en ny levetid på 30 dage. Parkour Design har i øjeblikket ingen endpoints til tilbagekaldelse eller introspektion af tokens. Frakobling i partnerprogrammet skal slette dets gemte tokens. Et adgangstoken kan være gyldigt, indtil det udløber efter 15 minutter.

Brug adgangstokens til API

Parkour Designs adgangstokens har altid audience parkour-api. De er kun loginoplysninger til Parkour Designs ressource-API’er, der beskrives i Dataudveksling. Send dem aldrig videre til et partner-API eller en anden tredjepart; ressourcer, som partneren driver, skal bruge deres egen autorisationsmekanisme.

ID-tokenet fastslår identiteten og en partnersession. Brug ikke et ID-token til at kalde et API.

Nuværende adfærd for scopes

De nuværende identitetsscopes er openid, email og profile. Det koordinerede ressource-API autoriserer i øjeblikket adgang til stævner og projektoversigter med openid; det har endnu ingen særlige læsescopes.

Det er en begrænsning i den nuværende implementering, ikke et mønster for nye API’er. Ønskede scopes og tilgængelige ressourcer bekræftes ved klientregistreringen. Fremtidige ressourcekontrakter kan indføre særlige scopes.

Nuværende tokens og UserInfo indeholder e-mail og navn i større omfang, end de enkelte scopes email og profile angiver. Klienter skal alligevel kun anmode om godkendte scopes og må ikke regne med, at den bredere adfærd forbliver uændret.

Fejlhåndtering

Autorisations-endpointet har to kanaler for fejl:

  • efter at en redirect-URI er valideret, omdirigeres afvist samtykke og nogle invalid_request-fejl ved behandling af samtykke til callbacken med error og det oprindelige state;
  • valideringsfejl, før en betroet callback er fastslået, bl.a. fejl for klient, redirect-URI, scope, svartype og PKCE, returnerer et direkte HTTP 400-svar i JSON.

Fejl fra token- og ressource-API’er bruger også en kompakt JSON-krop:

{"error": "invalid_grant"}
FejlBetydning
invalid_clientManglende, ukendt, inaktiv eller forkert autentificeret klient
invalid_redirect_uriManglende eller uregistreret callback-URI; det er en kode, der er specifik for Parkour Designs nuværende implementering
invalid_scopeTomt eller ikke godkendt sæt scopes
invalid_requestManglende felter eller ugyldig kombination for PKCE
access_deniedBrugeren afviste samtykke
invalid_grantUgyldig, udløbet, genbrugt eller forkert bundet kode eller refresh token
unsupported_response_typeAndet autorisationssvar end code
unsupported_grant_typeGrant-type for token, der ikke understøttes
invalid_tokenManglende, forkert formateret, udløbet eller ugyldigt bearer token til API

Vis ikke rå tokensvar eller protokoldiagnostik for slutbrugeren. Log et korrelations-ID, endpoint, status og en sikker fejlkode uden at logge koder, tokens, hemmeligheder, nonce-værdier eller personoplysninger.

Nuværende begrænsninger

  • Klientregistrering og tilbagekaldelse af samtykke koordineres manuelt.
  • PKCE, state og nonce accepteres, men kontrolleres ikke af serveren; partnerklienterne skal kontrollere dem.
  • Discovery annoncerer PKCE plain; partnerklienterne skal bruge S256.
  • Der er ingen endpoints til tilbagekaldelse, introspektion, dynamisk registrering eller standardiseret afslutning af session.
  • Genbrug af refresh tokens tilbagekalder ikke hele tokenfamilien.
  • Adgangstokens forbliver gyldige, indtil de udløber efter lokal logud.
  • Den nuværende autorisation af ressourcer bruger openid i stedet for særlige ressourcescopes.

Gennemgå disse begrænsninger under onboardingen, og erstat dem ikke stiltiende med antagelser fra en anden OAuth-udbyder.