Explication des jetons de renouvellement et des délais d’expiration des sessions dans Keycloak

Les applications basées sur Keycloak voient parfois l’endpoint des tokens répondre 400 Bad Request lors du renouvellement. En bref, cela signifie que le processus de renouvellement ne fonctionne pas. Plus fréquemment, Keycloak refuse délibérément : la session est devenue inactive, a atteint son âge maximal, a été révoquée, ou le token de renouvellement n’est plus valide. Ces situations relèvent des politiques définies, et non de défauts techniques.

Ce guide explique les éléments essentiels en environnement de production : la fonction des tokens d’accès et de renouvellement, le déroulement complet du processus de renouvellement, les deux compteurs de temps des sessions qui conditionnent un renouvellement réussi, ainsi que les modèles et anti-modèles à adopter pour gérer le reste.

Pourquoi cet article existe

Lorsque l’endpoint des tokens renvoie 400, les équipes enregistrent souvent un bug d’authentification. La première question utile à se poser est de savoir quelle règle liée à la durée de vie ou à la révocation a été activée. Comprendre cette réponse évite de considérer un refus correct comme une panne.

1. Deux tokens, deux fonctions très différentes

Lors de la connexion, Keycloak délivre généralement un token d’accès, un token de renouvellement et un token d’ID. Le fonctionnement quotidien repose sur les deux premiers.

• Token d’accès — Attaché aux appels API ordinaires pour prouver l’identité de l’utilisateur. Sa durée de vie est courte, souvent mesurée en minutes.
• Token de renouvellement — Envoyé uniquement à Keycloak afin d’obtenir un nouveau token d’accès. Sa durée de vie est plus longue, généralement trente minutes ou plus.
• Token hors ligne — Accès temporaire optionnel dont la durée de vie peut dépasser celle d’une session SSO normale, géré par une politique distincte.

Exemple concret : le token d’accès est une carte temporaire présentée à chaque porte. Le token de renouvellement correspond aux documents qui remplacent cette carte ; il n’est jamais montré aux API des applications et doit être envoyé uniquement à l’endpoint de tokens de Keycloak.

2. Le flux normal

Le connexion restitue l’ensemble des jetons. Par la suite, le client ajoute le jeton d’accès à chaque appel :

GET /api/products
Authorization: Bearer eyJ...

La durée de validité des accès est courte — cinq à quinze minutes étant courants. Si la connexion a lieu à 09:00 avec un jeton d’accès valable cinq minutes, dès 09:05 le prochain appel API renvoie 401 Unauthorized.

Ce code 401 ne signifie pas un déconnexion immédiate ; il s’agit d’un signal indiquant qu’il faut renouveler le jeton.

3. L’appel de renouvellement lui-même

Le client envoie les données au point de terminaison des jetons de Keycloak en utilisant le jeton de renouvellement :

POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id=<client-id>
refresh_token=<refresh-token>

Un état correct se manifeste comme suit :

{
  "access_token": "new-access-token",
  "expires_in": 300,
  "refresh_token": "new-refresh-token",
  "refresh_expires_in": 1800
}

Le client stocke le nouveau jeton d’accès, réessaie la demande initiale, et l’utilisateur ne perçoit jamais ce changement.

4. Détails de la rotation : remplacer à chaque fois les identifiants de renouvellement stockés

La réponse inclut souvent également un jeton de mise à jour nouveau. Lorsque la rotation des jetons de mise à jour est activée, l’ancien jeton devient invalide dès que le nouveau est émis. La réutilisation de la valeur ancienne entraîne un échec lors du renouvellement suivant.

// Correct
saveAccessToken(response.access_token);
if (response.refresh_token) {
  saveRefreshToken(response.refresh_token);
}

// Wrong — keeps using the token that rotation just invalidated
const refreshToken = originalRefreshToken;

C’est le fait de conserver la valeur de mise à jour mise à jour après chaque succès – et non seulement après connexion – qui distingue une session qui se renouvelle silencieusement pendant des heures d’une autre qui échoue dès la deuxième tentative.

5. Inactif versus Max : les compteurs qui contrôlent le renouvellement

Les realms disposent d’au moins deux compteurs de session, et le changement de leur signification est à l’origine de la plupart des demandes d’aide du type « pourquoi l’authentification a échoué » :

• Inactivité de la session SSO – Durée pendant laquelle la session peut rester sans activité avant que Keycloak ne la termine. Un renouvellement réussi compte comme une activité et réinitialise ce compteur.

En bref :

IDLE = how long since the session was last active
MAX  = how long since the user originally logged in

Avec Idle = 30 minutes et Max = 16 heures, des renouvellements fréquents maintiennent le compteur d’inactivité à un niveau bas toute la journée, mais après seize heures depuis la connexion, la session se termine même si l’utilisateur était actif une minute plus tôt. Un timing de renouvellement parfait ne peut pas dépasser cette durée maximale ; il ne fait que prolonger la vie de la session dans cette fenêtre temporelle.

Les paramètres Idle/Max par client reflètent les compteurs du domaine, mais uniquement pour ce client. La limite la plus stricte s’applique.

Pourquoi une durée maximale de seize heures apparaît dans les exemples : une équipe ERP travaillant sur des shifts d’environ douze heures peut choisir douze heures de travail accompagnées d’une marge de quatre heures afin que la session puisse durer toute une journée sans nécessiter un nouveau connexion en cours de tâche, tout en évitant qu’elle ne dure indéfiniment. Ce chiffre est une décision commerciale ; la compétence essentielle consiste à savoir quel mécanisme il régule.

Pourquoi un temps d’inactivité de trente minutes surprend encore les gens : même avec une durée maximale généreuse, un déjeuner ou une réunion longue peut provoquer l’inactivité prématurément. Si les utilisateurs doivent revenir sans devoir se réauthentifier, il convient d’envisager l’inactivité comme une décision liée au produit ou à la sécurité — et non simplement comme un problème à masquer dans le code client.

6. Lire 400 depuis l’endpoint du token sans supposer une panne

Une mise à jour échouée peut se manifester comme suit :

{
  "error": "invalid_grant",
  "error_description": "Token is not active"
}

Ce payload peut correspondre à plusieurs cas distincts :

• Les identifiants de mise à jour sont devenus obsolètes d’eux-mêmes

401 on API request
  → try refresh, exactly once
      → success: save new tokens, retry the original request
      → failure: clear auth state, redirect to login

if (tokenExpired) {
  if (!refreshInProgress) {
    refreshInProgress = refreshToken();
  }

  try {
    const tokens = await refreshInProgress;
    updateTokens(tokens);
    return retryOriginalRequest();
  } finally {
    refreshInProgress = null;
  }
}

12. Le modèle mental à retenir

Trois niveaux, avec une dépendance unidirectionnelle :

Access token                   → used for normal API calls
Refresh token                   → used to get a new access token
Keycloak session (Idle + Max)   → decides whether that refresh is allowed at all

Liste de contrôle

• Traiter l’expiration du jeton d’accès séparément de la fin de la session — tenter un seul renouvellement avant d’interpréter une erreur 401 comme une déconnexion.
• Conserver le jeton de renouvellement mis à jour après chaque succès, et non seulement le nouveau JWT d’accès.
• Se souvenir des deux compteurs temporels : l’un renouvelle la session en cas d’inactivité ; l’autre, basé sur l’heure réelle depuis la connexion, détermine l’âge maximal.
• Faire en sorte que l’échec du renouvellement soit définitif — une seule tentative, puis effacer les identifiants et rediriger l’utilisateur vers la page de connexion ; ne jamais réessayer en boucle.