Skip to content

Rafraîchir la session

Renouveler le jeton d'accès Keycloak avant son expiration avec le refresh token, une seule fois à la fois, et recharger le contexte utilisateur.

GuideDeveloper
Duration
10 min

This page has not been translated yet and is shown in French.

Le jeton d'accès Keycloak vit 5 minutes par défaut. Votre serveur le renouvelle avec le refresh token, sans intervention de l'utilisateur, tant que la session Keycloak est active. Ce guide montre comment rafraîchir avant l'expiration, éviter les rafraîchissements concurrents et réagir à une session terminée.

Avant de commencer

Appeler Keycloak avec le refresh token

Envoyez le refresh token au point de terminaison de jetons de l'émetteur de la session :

Bash
curl -s -X POST "https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d client_id=EXAPP1 \
  -d "refresh_token=$REFRESH_TOKEN"

Réponse attendue (extrait) :

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
  "expires_in": 300,
  "refresh_expires_in": 21540,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIn0...",
  "token_type": "Bearer"
}

Remplacez toujours le refresh token de la session par celui que renvoie la réponse : l'ancien peut ne plus être accepté.

Rafraîchir avant l'expiration, une fois à la fois

Rafraîchissez quand le jeton expire dans moins d'une minute, et mutualisez les demandes concurrentes : deux requêtes qui rafraîchissent en même temps avec le même refresh token peuvent faire échouer la seconde.

refresh.tsTypeScript
interface TokenSession {
  issuer: string;
  clientId: string;
  accessToken: string;
  refreshToken: string;
  accessTokenExpiresAt: number;
  me?: unknown;
}

const inFlight = new Map<string, Promise<void>>();

export class SessionExpiredError extends Error {}

export async function ensureFreshToken(session: TokenSession): Promise<string> {
  if (session.accessTokenExpiresAt - Date.now() > 60_000) return session.accessToken;

  const key = session.refreshToken;
  if (!inFlight.has(key)) {
    inFlight.set(
      key,
      (async () => {
        const response = await fetch(`${session.issuer}/protocol/openid-connect/token`, {
          method: "POST",
          headers: { "Content-Type": "application/x-www-form-urlencoded" },
          body: new URLSearchParams({
            grant_type: "refresh_token",
            client_id: session.clientId,
            refresh_token: session.refreshToken,
          }),
        });
        if (!response.ok) throw new SessionExpiredError(await response.text());
        const tokens = (await response.json()) as {
          access_token: string;
          refresh_token: string;
          expires_in: number;
        };
        session.accessToken = tokens.access_token;
        session.refreshToken = tokens.refresh_token;
        session.accessTokenExpiresAt = Date.now() + tokens.expires_in * 1000;
        delete session.me; // les droits ont pu changer : rechargez /api/me
      })().finally(() => inFlight.delete(key)),
    );
  }
  await inFlight.get(key);
  return session.accessToken;
}

Appelez ensureFreshToken avant chaque appel à l'API publique. Si votre service a plusieurs réplicas, placez la session dans un stockage partagé pour que le dernier refresh token soit visible de tous.

Réagir à une session terminée

Quand Keycloak refuse le refresh token, la session est terminée : inactivité de plus de 6 heures, durée maximale de 12 heures atteinte par défaut, déconnexion ou compte désactivé. Keycloak répond alors 400 avec, par exemple :

JSON
{ "error": "invalid_grant", "error_description": "Token is not active" }
  1. Ne réessayez pas : supprimez la session locale.
  2. Redirigez l'utilisateur vers votre route de connexion.
TypeScript
try {
  const token = await ensureFreshToken(req.session as TokenSession);
  // … appel à l'API publique avec token
} catch (err) {
  if (err instanceof SessionExpiredError) {
    return req.session.destroy(() => res.redirect("/login"));
  }
  throw err;
}

Sur une réponse 401 de l'API publique, tentez au plus un rafraîchissement, puis renvoyez vers la connexion : ne bouclez jamais.

Vérifier le résultat

  1. Connectez-vous, puis attendez plus de 5 minutes.
  2. Déclenchez un appel à l'API publique depuis votre application.

Résultat attendu : l'appel aboutit sans retour à la page de connexion, et la date d'expiration stockée dans la session a avancé.

Voir aussi