Skip to Content

Tokens

À quoi servent les ID, access et refresh tokens, qui valide lequel, combien de temps ils vivent, et comment fonctionnent rotation et stockage sûr.

Une seule connexion peut produire trois tokens différents, et la plupart des problèmes d'intégration viennent d'une confusion sur le rôle de chacun. Cette page est le tableau de référence : finalité, audience, durée de vie et règles de manipulation par type de token.

Les trois tokens

TokenDestinataireÀ quoi il sertValidé par
ID tokenL'application (son client ID est l'audience)Prouve qui s'est connecté et transporte des claims de profil (sub, name, email, ...).L'application, généralement au travers de sa bibliothèque OIDC.
Access tokenUne API (son identifiant est l'audience)Autorise les appels à cette API et transporte les scopes accordés.L'API, à chaque requête ; voir Protéger une API.
Refresh tokenLa plateforme elle-mêmePermet à l'application de renouveler son access token plus tard sans renvoyer l'utilisateur vers la page de connexion.La plateforme, au niveau du token endpoint.

L'erreur la plus fréquente consiste à envoyer l'ID token à une API. Un ID token authentifie l'utilisateur auprès de l'application et son audience est le client ID de l'application : une API correctement implémentée le rejette donc. Envoyez l'access token aux API, et traitez-le comme opaque à l'intérieur du client : son contenu est un contrat entre la plateforme et l'API, pas avec l'application.

Formats d'access token

  • Pour une API enregistrée (le client a transmis l'identifiant de l'API comme resource indicator) : un JWT signé portant l'identifiant de l'API dans aud, les scopes accordés dans scope et l'appelant dans sub. L'API le valide hors ligne à l'aide des clés publiées par la plateforme. Avec le RBAC activé, il transporte en outre les claims permissions / roles.
  • Sans API cible : un token opaque, utilisable uniquement sur l'endpoint UserInfo de la plateforme. Les tokens opaques (et les refresh tokens) peuvent être contrôlés sur l'endpoint standard d'introspection de token et annulés sur l'endpoint de révocation ; les deux figurent dans le document de discovery. Un client peut introspecter ses propres tokens ; les tokens d'autres clients, seule une application créée dans l'Admin Console avec un client secret ou une clé (un serveur de ressources) le peut, et non une application enregistrée dynamiquement.

Durées de vie

Token / artefactDurée de vieOù cela se configure
Authorization code1 minute, usage uniqueFixe
Access token pour une API1 jour par défaut (2 heures via les flux implicites)Par API, sur son onglet de paramètres ; voir API
Access token sans API cible (UserInfo)1 heureFixe
Token machine-to-machine sans API cible10 minutesFixe
ID token1 heure par défautPar application ; voir Applications
Refresh token14 jours, prolongeable par rotation jusqu'à 1 an au totalFixe ; voir ci-dessous
Device code10 minutesFixe
Session single sign-onDélais d'inactivité et absolusÀ l'échelle de l'instance sous Paramètres → Connexion, surchargeable par répertoire ; voir Paramètres de connexion

Refresh tokens

Quand un refresh token est émis. L'application doit avoir le grant type refresh token activé. Les applications first-party (sans écran de consentement) en reçoivent alors un automatiquement ; les applications pour lesquelles Exiger le consentement de l'utilisateur est activé n'en reçoivent un que si l'utilisateur a accordé le scope offline_access.

Rotation. Les refresh tokens tournent au lieu de vivre indéfiniment :

  • Un client public (application monopage ou native, sans client secret) reçoit un refresh token de remplacement à chaque utilisation. Pour les clients basés sur le navigateur, le remplaçant conserve la durée de vie restante : la rotation ne la prolonge donc pas.
  • Un client confidentiel conserve son refresh token jusqu'à ce qu'environ 70 % de sa durée de vie soit écoulée ; l'utilisation suivante émet alors un nouveau token de 14 jours.
  • Quelle que soit la rotation, une chaîne de refresh tokens prend fin un an après la connexion initiale au plus tard ; l'utilisateur doit ensuite se reconnecter.

Un refresh token remplacé par rotation (donc déjà utilisé) est invalide ; si votre client persiste les tokens, stockez toujours le plus récent de chaque réponse.

Révocation. Une application peut annuler un refresh token de façon proactive sur l'endpoint de révocation (indiqué dans le document de discovery), ce qui est une bonne pratique lors de votre propre déconnexion. Les utilisateurs peuvent mettre fin à leurs sessions depuis leur portail de compte (« se déconnecter partout »), et les tokens liés à une session s'arrêtent avec elle ; voir la section suivante.

Tokens et déconnexion

La déconnexion met fin à la session SSO de la plateforme, mais les tokens suivent leurs propres règles :

  • Les tokens émis sans offline_access sont liés à la session. Les tokens opaques cessent de fonctionner dès la fin de la session.
  • Un access token JWT ne peut pas être rappelé : les API le valident hors ligne, il reste donc techniquement utilisable jusqu'à son expiration, même après la déconnexion. Si cette fenêtre compte pour une API, raccourcissez la durée de vie de son access token plutôt que de compter sur la déconnexion.
  • Les refresh tokens obtenus avec offline_access survivent à la déconnexion, et c'est voulu (c'est précisément le sens de l'accès hors ligne). Ils prennent fin à leur expiration, en atteignant la limite d'un an, ou en cas de révocation.
  • Les applications peuvent être informées de la déconnexion par le back-channel logout ; voir Durées de vie des jetons et déconnexion. L'articulation entre la session de la plateforme, les sessions applicatives et la session d'un fournisseur d'identité en amont est décrite dans Cycle de vie des utilisateurs : Sessions.

Stocker les tokens

  • Contre les scripts qui s'exécutent dans la page (cross-site scripting) : un token placé dans localStorage ou sessionStorage est lisible par n'importe quel script injecté. Les applications navigateur conservent les tokens uniquement en mémoire et s'appuient sur la rotation des refresh tokens pour couvrir la courte durée de vie de l'access token.
  • Contre les autres logiciels présents sur l'appareil : un token stocké dans un simple fichier ou dans un magasin de préférences est à une lecture de fichier de distance. Les applications natives utilisent le stockage protégé du système d'exploitation (Keychain, Keystore, gestionnaire d'identifiants).
  • Contre le navigateur dans son ensemble : une application côté serveur n'a jamais besoin que le navigateur détienne un token. Conservez les tokens sur le serveur, liés à votre propre cookie de session.
  • Contre les fuites en transit et dans les journaux : ne transmettez les tokens que par TLS dans l'en-tête Authorization, jamais dans des URL (elles finissent dans les journaux des proxys et des serveurs), et ne les écrivez jamais vous-même dans des journaux.

Sujets liés

Sur cette page