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ø | Udsteder | 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 |
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:
| Funktion | Nuværende værdi |
|---|---|
| Svartype | code |
| Grant-typer | authorization_code, refresh_token |
| Klientautentificering | client_secret_basic, client_secret_post |
| Signering af ID-token | RS256 |
| PKCE-metoder | S256, plain |
| Scopes | openid, profile, email |
| Claims | sub, 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
statemed høj entropi; - en OIDC-
noncemed 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:
- afvis et manglende eller uventet
state; - afvis en browsertransaktion, der er udløbet eller allerede brugt;
- forbrug transaktionen, så callbacken ikke kan afspilles igen;
- håndtér en OAuth-
erroruden 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:
- hent nøgler fra
jwks_urii discovery; - vælg den nøgle, der angives af JWT’ens
kid; - kræv en
RS256-signatur; - kræv præcis overensstemmelse med udstederen;
- kræv klient-ID’et som audience;
- validér udløbstid og udstedelsestid med en lille margen for urforskydning;
- kræv den oprindelige
nonce; - brug
subsom 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
| Token | Levetid | Håndtering i klienten |
|---|---|---|
| Autorisationskode | 5 minutter | Udveksl én gang, og gem aldrig efter brug |
| ID-token | 15 minutter | Validér én gang; brug ikke som bearer token til API |
| Adgangstoken | 15 minutter | Behold på serveren, og send kun til Parkour Designs ressource-API’er |
| Refresh token | 30 dage | Krypté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 mederrorog det oprindeligestate; - 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"}
| Fejl | Betydning |
|---|---|
invalid_client | Manglende, ukendt, inaktiv eller forkert autentificeret klient |
invalid_redirect_uri | Manglende eller uregistreret callback-URI; det er en kode, der er specifik for Parkour Designs nuværende implementering |
invalid_scope | Tomt eller ikke godkendt sæt scopes |
invalid_request | Manglende felter eller ugyldig kombination for PKCE |
access_denied | Brugeren afviste samtykke |
invalid_grant | Ugyldig, udløbet, genbrugt eller forkert bundet kode eller refresh token |
unsupported_response_type | Andet autorisationssvar end code |
unsupported_grant_type | Grant-type for token, der ikke understøttes |
invalid_token | Manglende, 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,
stateognonceaccepteres, men kontrolleres ikke af serveren; partnerklienterne skal kontrollere dem. - Discovery annoncerer PKCE
plain; partnerklienterne skal brugeS256. - 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
openidi stedet for særlige ressourcescopes.
Gennemgå disse begrænsninger under onboardingen, og erstat dem ikke stiltiende med antagelser fra en anden OAuth-udbyder.