Dit document beschrijft de flow die nu is geïmplementeerd voor een vertrouwelijke partnerapplicatie die verbinding maakt met Parkour Design. Voor de registratie van clients en productietoegang is technische en beveiligingsgoedkeuring nodig.
Huidig contract: Het protocol is in gebruik en wordt toegepast voor afgestemde integraties. Het is geen selfservice-autorisatiedienst. Parkour Design levert de client-ID, het clientgeheim, de geregistreerde redirect-URI’s en de toegestane scopes via een veilig kanaal.
Omgevingen en discovery
Gebruik OpenID Connect-discovery in plaats van endpoint-URL’s zelf samen te stellen.
| Omgeving | Issuer | Discovery-document |
|---|---|---|
| Productie | 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 |
Haal de discovery op als de applicatie start, cache die een beperkte tijd en vernieuw haar als de ondertekeningssleutels veranderen. Eis dat de teruggegeven issuer exact overeenkomt met de ingestelde issuer.
Het huidige discovery-document publiceert:
| Mogelijkheid | Huidige waarde |
|---|---|
| Response type | code |
| Grant types | authorization_code, refresh_token |
| Clientauthenticatie | client_secret_basic, client_secret_post |
| Ondertekening ID-token | RS256 |
| PKCE-methoden | S256, plain |
| Scopes | openid, profile, email |
| Claims | sub, email, email_verified, name |
Gebruik client_secret_basic en PKCE S256. Gebruik geen plain, ook al biedt de huidige server die voor compatibiliteit aan.
Voorwaarden voor registratie
Stuur Parkour Design voor de implementatie:
- de naam van de applicatie en de technisch eigenaar;
- de redirect-URI’s voor test en productie;
- de gevraagde scopes en de gebruikersflow;
- contactpersonen voor het leveren en roteren van inloggegevens;
- eisen voor uitloggen, het ontkoppelen van accounts en bewaartermijnen.
Redirect-URI’s moeten exact overeenkomen. Schema, host, poort, pad, hoofdletters en de afsluitende slash moeten gelijk zijn aan de geregistreerde waarde. Gebruik een callback zonder bestaande querystring of fragment.
De huidige dienst ondersteunt vertrouwelijke backendclients. Clients die alleen in de browser draaien en native publieke clients worden niet ondersteund, omdat elk tokenverzoek een clientgeheim vereist.
Autorisatievolgorde
1. Maak de browsertransactie aan
Genereer en bewaar op de server:
- een
state-waarde met hoge entropie voor eenmalig gebruik; - een OIDC-
noncemet hoge entropie; - een PKCE-verifier en de SHA-256-challenge ervan;
- de bedoelde bestemming na het inloggen;
- een korte vervaltijd.
Koppel deze waarden aan de browsersessie van de gebruiker. Zet het clientgeheim, de verifier of tokens nooit in een URL.
2. Stuur de gebruiker door
Bouw de autorisatie-URL op basis van authorization_endpoint uit de 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
Gebruik alleen de scopes die bij de registratie van de client zijn goedgekeurd. openid email profile is een voorbeeld als alle drie de scopes zijn goedgekeurd; het vragen van een niet-goedgekeurde scope geeft invalid_scope.
Parkour Design authenticeert de gebruiker en vraagt om toestemming. Een geslaagd antwoord geeft:
{redirect_uri}?code={authorization_code}&state={state}
Een geweigerd verzoek geeft:
{redirect_uri}?error=access_denied&state={state}
3. Valideer de callback
Voordat je de code inwisselt:
- weiger een ontbrekende of onverwachte
state; - weiger een verlopen of al gebruikte browsertransactie;
- markeer de transactie als gebruikt, zodat de callback niet opnieuw kan worden afgespeeld;
- handel een OAuth-
erroraf zonder een tokenuitwisseling te proberen.
Autorisatiecodes verlopen na vijf minuten en kunnen één keer worden gebruikt.
4. Wissel de code in op de server
Stuur vanuit de backend van de partner een form-encoded verzoek:
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}"
De redirect_uri moet identiek zijn aan de waarde uit het autorisatieverzoek.
Een geslaagd antwoord ziet er nu zo uit:
{
"access_token": "<signed JWT>",
"refresh_token": "<opaque token>",
"token_type": "Bearer",
"expires_in": 900,
"scope": "email openid profile",
"id_token": "<signed JWT>"
}
Tokenantwoorden gebruiken Cache-Control: no-store en Pragma: no-cache. Het id_token wordt alleen teruggegeven als openid is toegekend.
Valideer de identiteit
Valideer het ID-token voordat je een sessie bij de partner start:
- haal de sleutels op uit
jwks_uriin de discovery; - kies de sleutel die door de
kidvan de JWT wordt aangeduid; - eis een
RS256-handtekening; - eis dat de issuer exact gelijk is;
- eis de client-ID als audience;
- valideer de vervaltijd en het uitgiftetijdstip met een kleine marge voor klokverschil;
- eis de oorspronkelijke
nonce; - gebruik
subals stabiele identificatie van de gebruiker in Parkour Design.
Huidige claims in het 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>"
}
Koppel accounts niet alleen op e-mailadres. Bewaar iss en sub als sleutel voor de externe identiteit. Behandel e-mailadres en naam als profielgegevens die kunnen veranderen.
UserInfo is beschikbaar als het toegangstoken openid bevat:
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"
}
Toegangstokens en refresh tokens
| Token | Levensduur | Afhandeling door de client |
|---|---|---|
| Autorisatiecode | 5 minuten | Eén keer inwisselen en na gebruik nooit bewaren |
| ID-token | 15 minuten | Eén keer valideren; niet als bearer-token voor een API gebruiken |
| Toegangstoken | 15 minuten | Op de server houden en alleen naar de resource-API’s van Parkour Design sturen |
| Refresh token | 30 dagen | Versleuteld opslaan en na elke vernieuwing atomair vervangen |
Refresh tokens roteren bij elk geslaagd gebruik:
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}"
Het antwoord bevat een nieuw toegangstoken en een vervangend refresh token, maar geen nieuw ID-token. Voer vernieuwingen per gebruikers- en clientsessie na elkaar uit en vervang het opgeslagen refresh token atomair. Een hergebruikt oud token geeft invalid_grant.
Parkour Design maakt het oude refresh token ongeldig voordat het de vervanging teruggeeft. Is de uitkomst onbekend door een time-out of een verloren antwoord, probeer het dan niet blind opnieuw met het oude token. Verwijder de lokale tokenstatus en start een nieuwe autorisatieflow. Gelijktijdige vernieuwingsverzoeken voor dezelfde sessie geven hetzelfde herstelrisico.
De huidige levensduur van refresh tokens schuift mee: elke geslaagde rotatie start een nieuwe periode van 30 dagen. Parkour Design biedt nu geen endpoints voor het intrekken of inspecteren van tokens. Bij het ontkoppelen in de partnerapplicatie moeten de opgeslagen tokens worden verwijderd. Een toegangstoken kan geldig blijven tot het na 15 minuten verloopt.
API-toegangstokens gebruiken
Toegangstokens van Parkour Design hebben altijd de audience parkour-api. Ze zijn alleen inloggegevens voor de resource-API’s van Parkour Design die in Gegevensuitwisseling worden beschreven. Stuur ze nooit door naar een API van een partner of een andere derde partij; resources van een partner moeten hun eigen autorisatiemechanisme gebruiken.
ID-tokens leggen de identiteit vast en starten een sessie bij de partner. Gebruik een ID-token niet om een API aan te roepen.
Huidig gedrag van scopes
De huidige identiteitsscopes zijn openid, email en profile. De afgestemde resource-API geeft nu toegang tot evenementen en ontwerpoverzichten met openid; er zijn nog geen aparte leesscopes.
Dit is een beperking van de huidige implementatie, geen patroon voor nieuwe API’s. De gevraagde scopes en toegankelijke resources worden bij de registratie van de client bevestigd. Toekomstige resourcecontracten kunnen aparte scopes invoeren.
Huidige tokens en UserInfo bevatten e-mailadres en naam ruimer dan de afzonderlijke scopes email en profile doen vermoeden. Clients moeten toch alleen goedgekeurde scopes vragen en er niet op rekenen dat dit ruimere gedrag zo blijft.
Foutafhandeling
Het autorisatie-endpoint heeft twee kanalen voor fouten:
- nadat een redirect-URI is gevalideerd, worden een geweigerde toestemming en sommige
invalid_request-fouten bij de verwerking van toestemming naar die callback gestuurd meterroren de oorspronkelijkestate; - validatiefouten voordat er een vertrouwde callback is vastgesteld, waaronder fouten in client, redirect-URI, scope, response type en PKCE, geven direct een HTTP-
400-antwoord in JSON.
Fouten van het token-endpoint en de resource-API gebruiken ook een compacte JSON-body:
{"error": "invalid_grant"}
| Fout | Betekenis |
|---|---|
invalid_client | Ontbrekende, onbekende, inactieve of onjuist geauthenticeerde client |
invalid_redirect_uri | Ontbrekende of niet-geregistreerde callback-URI; dit is een code die specifiek is voor de huidige implementatie van Parkour Design |
invalid_scope | Lege of niet-goedgekeurde set scopes |
invalid_request | Ontbrekende velden of ongeldige combinatie voor PKCE |
access_denied | De gebruiker heeft de toestemming geweigerd |
invalid_grant | Ongeldige, verlopen, hergebruikte of onjuist gekoppelde code of refresh token |
unsupported_response_type | Ander autorisatieantwoord dan code |
unsupported_grant_type | Niet-ondersteunde token grant |
invalid_token | Ontbrekend, onjuist opgebouwd, verlopen of ongeldig bearer-token voor de API |
Toon de eindgebruiker geen ruwe tokenantwoorden of protocoldiagnostiek. Log een correlatie-ID, het endpoint, de status en een veilige foutcode, zonder codes, tokens, geheimen, nonce-waarden of persoonsgegevens te loggen.
Huidige beperkingen
- Registratie van clients en het intrekken van toestemming worden handmatig afgestemd.
- PKCE,
stateennonceworden geaccepteerd maar niet door de server afgedwongen; partnerclients moeten ze zelf afdwingen. - De discovery biedt PKCE
plainaan; partnerclients moetenS256gebruiken. - Er is geen endpoint voor het intrekken of inspecteren van tokens, geen dynamische registratie en geen standaard end-session-endpoint.
- Het opnieuw afspelen van een refresh token trekt niet de hele tokenfamilie in.
- Toegangstokens blijven na lokaal uitloggen geldig tot ze verlopen.
- De huidige autorisatie van resources gebruikt
openidin plaats van aparte resourcescopes.
Bespreek deze beperkingen tijdens de onboarding en vervang ze niet stilzwijgend door aannames uit een andere OAuth-provider.