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
| Token | Destinataire | À quoi il sert | Validé par |
|---|---|---|---|
| ID token | L'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 token | Une 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 token | La plateforme elle-même | Permet à 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 dansscopeet l'appelant danssub. 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 claimspermissions/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 / artefact | Durée de vie | Où cela se configure |
|---|---|---|
| Authorization code | 1 minute, usage unique | Fixe |
| Access token pour une API | 1 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 heure | Fixe |
| Token machine-to-machine sans API cible | 10 minutes | Fixe |
| ID token | 1 heure par défaut | Par application ; voir Applications |
| Refresh token | 14 jours, prolongeable par rotation jusqu'à 1 an au total | Fixe ; voir ci-dessous |
| Device code | 10 minutes | Fixe |
| Session single sign-on | Dé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_accesssont 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_accesssurvivent à 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
localStorageousessionStorageest 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
- Protéger une API : valider les access tokens dans votre propre API.
- API : scopes, audiences et paramètres de token par API.
- Applications : paramètres de token et de déconnexion par application.
- Paramètres de connexion : les délais d'expiration de la session SSO.