Jetons et durées de vie

Code, id_token, access_token, jeton client_credentials et clé de signature webhook : à quoi sert chacun, combien de temps il vit, comment le protéger.

Plusieurs « jetons » interviennent dans une intégration. Ils ne se ressemblent pas et ne servent pas aux mêmes choses : les confondre est la première source d’erreurs.

Vue d’ensemble

Le code d’autorisation

Il arrive dans l’URL de retour (?code=…&state=…). Il n’a de valeur que quelques instants : votre serveur l’échange tout de suite au endpoint token, avec ses identifiants. Il est à usage unique : un second essai est refusé. Il transite par le navigateur, c’est pourquoi il ne donne rien sans votre client_secret.

L’id_token : la preuve d’identité

C’est un JWT : trois blocs encodés en base64url séparés par des points (en-tête, contenu, signature). Le contenu contient :

• les claims que l’utilisateur a partagés (given_name, birthdate…) ;
• des informations sur le jeton lui-même : iss (qui l’a émis), aud (pour qui : votre client_id), sub (l’utilisateur), iat/exp (émis le / expire le), nonce (le vôtre), et des claims techniques (at_hash, auth_time, jti, sid, rat).

Ne lisez jamais le contenu sans avoir vérifié la signature : n’importe qui peut fabriquer un JWT qui a l’air valide. La vérification se fait avec les clés publiques du jwks_uri ; voir Vérifier les jetons. Une fois vérifié, extrayez et stockez les claims dont vous avez besoin : le jeton lui-même expire vite.

L’access_token : la clé pour appeler les API de l’utilisateur

Il représente le consentement donné par cet utilisateur pour cette transaction. Vous le présentez dans l’en-tête Authorization: Bearer <access_token> à :

• l’endpoint userinfo (qui renvoie les mêmes claims que l’id_token) ;
• l’URL d’un claim de document (private:doc.*).

Dans les exemples du guide, ce n’est pas un JWT : traitez-le comme une chaîne opaque, ne cherchez pas à le décoder. Sa durée de validité est indiquée par expires_in dans la réponse du endpoint token. Dans tous les cas, les informations ne sont récupérables que 30 minutes après le consentement : appelez les API tout de suite.

Règles de sécurité : jamais dans une URL (elle serait journalisée), jamais dans le navigateur ou une application mobile, jamais dans les logs, jamais envoyé ailleurs que vers les endpoints A3BC.

Le jeton client_credentials : l’accès sans utilisateur

Pour le partage différé, l’utilisateur n’est plus là au moment où vous interrogez l’API (c’est justement le but). Votre serveur s’authentifie donc lui-même, avec ses identifiants :

curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d scope=private:delayed_sharing \
  https://oidc-sandbox.a3bc.io/oauth2/token

Il ne vaut que pour le scope private:delayed_sharing et vit environ 10 minutes : redemandez-en un à chaque appel, ou mettez-le en cache jusqu’à expires_in moins une marge.

La clé de signature webhook : l’authentification dans l’autre sens

Pour toutes les autres clés, c’est vous qui prouvez votre identité à A3BC. Ici, c’est A3BC qui prouve son identité à votre serveur : chaque notification porte une signature calculée avec une clé que vous êtes seul(e) à partager avec A3BC. Ce n’est pas un jeton d’accès, on ne l’envoie jamais nulle part. Voir Webhooks.

Les identifiants du RP

client_secret_basic signifie que vous envoyez Authorization: Basic base64(client_id:client_secret). Les bibliothèques HTTP le font avec un paramètre auth=(client_id, client_secret) (Python requests) ou -u client_id:client_secret (curl).