Menu van de documentatie
Per partner Laatst bijgewerkt: 27 juli 2026

Authenticatie

Registratie van clients, autorisatiecode met PKCE, validatie van tokens en rotatie van refresh tokens voor partnerapplicaties die met Parkour Design verbinden.

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.

OmgevingIssuerDiscovery-document
Productiehttps://app.parkour.designhttps://app.parkour.design/.well-known/openid-configuration
Testhttps://parkour-test.web.apphttps://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:

MogelijkheidHuidige waarde
Response typecode
Grant typesauthorization_code, refresh_token
Clientauthenticatieclient_secret_basic, client_secret_post
Ondertekening ID-tokenRS256
PKCE-methodenS256, plain
Scopesopenid, profile, email
Claimssub, 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-nonce met 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:

  1. weiger een ontbrekende of onverwachte state;
  2. weiger een verlopen of al gebruikte browsertransactie;
  3. markeer de transactie als gebruikt, zodat de callback niet opnieuw kan worden afgespeeld;
  4. handel een OAuth-error af 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:

  1. haal de sleutels op uit jwks_uri in de discovery;
  2. kies de sleutel die door de kid van de JWT wordt aangeduid;
  3. eis een RS256-handtekening;
  4. eis dat de issuer exact gelijk is;
  5. eis de client-ID als audience;
  6. valideer de vervaltijd en het uitgiftetijdstip met een kleine marge voor klokverschil;
  7. eis de oorspronkelijke nonce;
  8. gebruik sub als 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

TokenLevensduurAfhandeling door de client
Autorisatiecode5 minutenEén keer inwisselen en na gebruik nooit bewaren
ID-token15 minutenEén keer valideren; niet als bearer-token voor een API gebruiken
Toegangstoken15 minutenOp de server houden en alleen naar de resource-API’s van Parkour Design sturen
Refresh token30 dagenVersleuteld 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 met error en de oorspronkelijke state;
  • 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"}
FoutBetekenis
invalid_clientOntbrekende, onbekende, inactieve of onjuist geauthenticeerde client
invalid_redirect_uriOntbrekende of niet-geregistreerde callback-URI; dit is een code die specifiek is voor de huidige implementatie van Parkour Design
invalid_scopeLege of niet-goedgekeurde set scopes
invalid_requestOntbrekende velden of ongeldige combinatie voor PKCE
access_deniedDe gebruiker heeft de toestemming geweigerd
invalid_grantOngeldige, verlopen, hergebruikte of onjuist gekoppelde code of refresh token
unsupported_response_typeAnder autorisatieantwoord dan code
unsupported_grant_typeNiet-ondersteunde token grant
invalid_tokenOntbrekend, 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, state en nonce worden geaccepteerd maar niet door de server afgedwongen; partnerclients moeten ze zelf afdwingen.
  • De discovery biedt PKCE plain aan; partnerclients moeten S256 gebruiken.
  • 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 openid in plaats van aparte resourcescopes.

Bespreek deze beperkingen tijdens de onboarding en vervang ze niet stilzwijgend door aannames uit een andere OAuth-provider.