Ce document décrit le flux actuellement mis en œuvre pour une application partenaire confidentielle qui se connecte à Parkour Design. L’enregistrement des clients et l’accès en production nécessitent une validation technique et de sécurité.
Contrat actuel : le protocole est déployé et utilisé pour les intégrations coordonnées. Ce n’est pas un service d’autorisation en libre-service. Parkour Design fournit l’identifiant client, le secret client, les URI de redirection enregistrées et les scopes autorisés par un canal sécurisé.
Environnements et découverte
Utilisez la découverte OpenID Connect plutôt que de construire les URL des points de terminaison.
| Environnement | Émetteur | Document de découverte |
|---|---|---|
| Production | 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 |
Récupérez le document de découverte au démarrage de l’application, mettez-le en cache pour une durée limitée et actualisez-le quand les clés de signature changent. Exigez que l’issuer renvoyé corresponde exactement à l’émetteur configuré.
Le document de découverte actuel publie :
| Fonction | Valeur actuelle |
|---|---|
| Type de réponse | code |
| Types d’octroi | authorization_code, refresh_token |
| Authentification du client | client_secret_basic, client_secret_post |
| Signature du jeton d’identité | RS256 |
| Méthodes PKCE | S256, plain |
| Scopes | openid, profile, email |
| Attributs | sub, email, email_verified, name |
Utilisez client_secret_basic et PKCE S256. N’utilisez pas plain, même si le serveur actuel l’annonce pour des raisons de compatibilité.
Prérequis à l’enregistrement
Transmettez à Parkour Design avant la mise en œuvre :
- le nom de l’application et son responsable technique ;
- les URI de redirection de test et de production ;
- les scopes demandés et le parcours utilisateur ;
- les contacts pour la remise et la rotation des identifiants ;
- les exigences de déconnexion, de dissociation des comptes et de conservation.
La correspondance des URI de redirection est exacte. Le schéma, l’hôte, le port, le chemin, la casse et la barre oblique finale doivent correspondre à la valeur enregistrée. Utilisez une URL de rappel sans chaîne de requête ni fragment.
Le service actuel prend en charge les clients serveur confidentiels. Les clients publics fonctionnant uniquement dans le navigateur ou en natif ne sont pas pris en charge, car chaque demande de jeton exige un secret client.
Séquence d’autorisation
1. Créer la transaction côté navigateur
Générez et conservez côté serveur :
- une valeur
stateà forte entropie et à usage unique ; - un
nonceOIDC à forte entropie ; - un vérificateur PKCE et son défi SHA-256 ;
- la destination prévue après la connexion ;
- une courte durée d’expiration.
Associez ces valeurs à la session du navigateur de l’utilisateur. Ne placez jamais le secret client, le vérificateur ou les jetons dans une URL.
2. Rediriger l’utilisateur
Construisez l’URL d’autorisation à partir de l’authorization_endpoint du document de découverte :
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
N’utilisez que les scopes validés lors de l’enregistrement du client. openid email profile est un exemple valable si les trois scopes ont été validés ; demander un scope non validé renvoie invalid_scope.
Parkour Design authentifie l’utilisateur et lui demande son consentement. Une réponse positive renvoie :
{redirect_uri}?code={authorization_code}&state={state}
Une demande refusée renvoie :
{redirect_uri}?error=access_denied&state={state}
3. Valider le rappel
Avant d’échanger le code :
- rejetez un
stateabsent ou inattendu ; - rejetez une transaction de navigateur expirée ou déjà consommée ;
- consommez la transaction pour que le rappel ne puisse pas être rejoué ;
- traitez une
errorOAuth sans tenter d’échange de jeton.
Les codes d’autorisation expirent au bout de cinq minutes et ne sont utilisables qu’une fois.
4. Échanger le code côté serveur
Envoyez une requête encodée en formulaire depuis le serveur du partenaire :
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}"
Le redirect_uri doit être identique à la valeur utilisée dans la demande d’autorisation.
Une réponse positive a actuellement cette forme :
{
"access_token": "<signed JWT>",
"refresh_token": "<opaque token>",
"token_type": "Bearer",
"expires_in": 900,
"scope": "email openid profile",
"id_token": "<signed JWT>"
}
Les réponses de jetons utilisent Cache-Control: no-store et Pragma: no-cache. L’id_token n’est renvoyé que si openid est accordé.
Valider l’identité
Validez le jeton d’identité avant d’ouvrir une session côté partenaire :
- récupérez les clés depuis le
jwks_uridu document de découverte ; - choisissez la clé identifiée par le
kiddu JWT ; - exigez une signature
RS256; - exigez une égalité exacte de l’émetteur ;
- exigez l’identifiant client comme audience ;
- validez l’expiration et l’heure d’émission avec une petite tolérance de décalage d’horloge ;
- exigez le
nonced’origine ; - utilisez
subcomme identifiant stable de l’utilisateur Parkour Design.
Attributs actuels du jeton d’identité :
{
"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>"
}
Ne liez pas les comptes uniquement par l’adresse e-mail. Conservez iss et sub comme clé d’identité externe. Considérez l’e-mail et le nom comme des attributs de profil modifiables.
Le point de terminaison UserInfo est disponible quand le jeton d’accès contient 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"
}
Jetons d’accès et de rafraîchissement
| Jeton | Durée de vie | Traitement par le client |
|---|---|---|
| Code d’autorisation | 5 minutes | L’échanger une fois et ne jamais le conserver après usage |
| Jeton d’identité | 15 minutes | Le valider une fois ; ne pas l’utiliser comme jeton porteur d’API |
| Jeton d’accès | 15 minutes | Le garder côté serveur et ne l’envoyer qu’aux API de ressources de Parkour Design |
| Jeton de rafraîchissement | 30 jours | Le chiffrer au repos et le remplacer de façon atomique après chaque rafraîchissement |
Les jetons de rafraîchissement changent à chaque utilisation réussie :
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}"
La réponse contient un nouveau jeton d’accès et un jeton de rafraîchissement de remplacement. Elle ne contient pas de nouveau jeton d’identité. Sérialisez les rafraîchissements pour chaque session utilisateur et client, puis remplacez de façon atomique le jeton de rafraîchissement enregistré. La réutilisation d’un ancien jeton renvoie invalid_grant.
Parkour Design consomme l’ancien jeton de rafraîchissement avant de renvoyer son remplaçant. Si un délai dépassé ou une réponse perdue rend le résultat incertain, ne réessayez pas aveuglément avec l’ancien jeton. Supprimez l’état local des jetons et relancez un flux d’autorisation. Des demandes de rafraîchissement simultanées pour la même session créent le même risque.
La durée de vie du rafraîchissement est actuellement glissante : chaque rotation réussie redémarre une durée de 30 jours. Parkour Design n’expose pas actuellement de point de terminaison de révocation ou d’introspection des jetons. La déconnexion dans l’application partenaire doit supprimer les jetons qu’elle conserve. Un jeton d’accès peut rester valide jusqu’à son expiration au bout de 15 minutes.
Utiliser les jetons d’accès aux API
Les jetons d’accès de Parkour Design ont toujours l’audience parkour-api. Ce sont des identifiants valables uniquement pour les API de ressources de Parkour Design décrites dans Échange de données. Ne les transmettez jamais à une API partenaire ni à un autre tiers ; les ressources exploitées par le partenaire doivent utiliser leur propre mécanisme d’autorisation.
Les jetons d’identité établissent l’identité et une session côté partenaire. N’utilisez jamais un jeton d’identité pour appeler une API.
Comportement actuel des scopes
Les scopes d’identité actuels sont openid, email et profile. L’API de ressources coordonnée autorise actuellement l’accès aux événements et aux résumés de projets avec openid ; elle n’expose pas encore de scopes de lecture dédiés.
Il s’agit d’une limite de la mise en œuvre actuelle, pas d’un modèle pour de nouvelles API. Les scopes demandés et les ressources accessibles sont confirmés lors de l’enregistrement du client. De futurs contrats de ressources pourront introduire des scopes dédiés.
Les jetons actuels et UserInfo incluent l’e-mail et le nom plus largement que ne le laisseraient supposer les scopes email et profile. Les clients doivent tout de même ne demander que les scopes validés et ne pas compter sur le maintien de ce comportement.
Gestion des erreurs
Le point de terminaison d’autorisation a deux canaux d’erreur :
- une fois l’URI de redirection validée, le refus de consentement et certaines erreurs
invalid_requestliées au consentement redirigent vers cette URL de rappel avecerroret lestated’origine ; - les échecs de validation survenant avant qu’une URL de rappel de confiance soit établie, notamment sur le client, l’URI de redirection, le scope, le type de réponse et PKCE, renvoient directement une réponse JSON HTTP
400.
Les erreurs des API de jetons et de ressources utilisent aussi un corps JSON compact :
{"error": "invalid_grant"}
| Erreur | Signification |
|---|---|
invalid_client | Client absent, inconnu, inactif ou mal authentifié |
invalid_redirect_uri | URL de rappel absente ou non enregistrée ; code propre à la mise en œuvre actuelle de Parkour Design |
invalid_scope | Ensemble de scopes vide ou non validé |
invalid_request | Champs manquants ou combinaison PKCE invalide |
access_denied | L’utilisateur a refusé le consentement |
invalid_grant | Code ou jeton de rafraîchissement invalide, expiré, réutilisé ou mal associé |
unsupported_response_type | Réponse d’autorisation autre que code |
unsupported_grant_type | Type d’octroi de jeton non pris en charge |
invalid_token | Jeton porteur d’API absent, mal formé, expiré ou invalide |
N’exposez pas à l’utilisateur final les réponses de jetons brutes ni les diagnostics du protocole. Journalisez un identifiant de corrélation, le point de terminaison, le statut et un code d’erreur sans risque, sans journaliser les codes, jetons, secrets, valeurs de nonce ni données personnelles.
Limites actuelles
- L’enregistrement des clients et le retrait du consentement sont coordonnés manuellement.
- PKCE,
stateetnoncesont acceptés mais pas imposés par le serveur ; les clients partenaires doivent les imposer. - La découverte annonce PKCE
plain; les clients partenaires doivent utiliserS256. - Il n’existe ni révocation ni introspection des jetons, ni enregistrement dynamique, ni point de terminaison standard de fin de session.
- La réutilisation d’un jeton de rafraîchissement ne révoque pas toute la famille de jetons.
- Les jetons d’accès restent valides jusqu’à leur expiration après une déconnexion locale.
- L’autorisation actuelle des ressources utilise
openidau lieu de scopes de ressources dédiés.
Examinez ces limites lors du démarrage de l’intégration et ne les remplacez pas en silence par des hypothèses issues d’un autre fournisseur OAuth.