Aller au contenu

Jetons et sessions

Le jeton Keycloak, le jeton enrichi et /api/me, ce que chacun porte, combien de temps il vit et comment la session se renouvelle.

ConceptDéveloppeur
Voir en Markdown

Après la connexion, votre serveur détient des jetons Keycloak standard. Wakastart y ajoute deux moyens de connaître le contexte métier de l'utilisateur : le jeton enrichi, signé, et la réponse de GET /api/me, complète. Cette page explique quand utiliser chacun.

Définition

Jeton KeycloakJeton enrichi (wakaToken)Réponse de /api/me
Émis parL'instance Keycloak de l'environnementWakastart, à partir du jeton KeycloakL'API publique
FormatJWT signé RS256 par KeycloakJWT signé par WakastartJSON
PorteIdentité OIDC (sub, email), azp (identifiant client de votre application), iss (instance et realm), wenv (environnement), organisationIdentité, niveau d'administration (wadl), identifiants courts du partenaire, du réseau, du client, de l'application et de l'utilisateur, thème, langue, environnementIdentité, organisation, équipes, profil avec ses droits, habillage
Sert àAppeler l'API publique, vérifier l'identité dans votre backendTransmettre un contexte signé à l'API publique sans nouvel enrichissementDécider de l'affichage et des autorisations dans votre application
Durée5 minutes par défautCelle du jeton Keycloak d'origine, 15 minutes au plus si elle est inconnueValable jusqu'au prochain changement de droits

Le jeton enrichi ne contient pas les droits applicatifs, les équipes ni les rôles HDS : ils ne sont disponibles que dans /api/me. Le détail des champs est dans la référence.

Pourquoi ça existe

Keycloak sait qui est l'utilisateur, mais pas ce qu'il peut faire dans votre application : les profils, les droits et l'organisation vivent dans Wakastart. Plutôt que d'alourdir le jeton Keycloak, Wakastart calcule ce contexte à la demande, pour l'environnement de la session, et le sert par /api/me.

Comment ça marche

Appeler l'API publique

L'API publique accepte trois modes d'authentification :

  • Authorization: Bearer <jeton Keycloak> : l'API vérifie le jeton et calcule le contexte de l'utilisateur à chaque appel ;
  • x-enriched-token: <jeton enrichi> : l'API vérifie la signature du jeton enrichi ;
  • x-api-key: sk_… : pour un serveur sans utilisateur connecté, voir Clés API.

Dans les deux premiers cas, le jeton doit avoir été émis pour votre application : son azp doit correspondre à votre application, sinon l'API refuse l'appel. L'utilisateur doit aussi avoir accès à l'application dans l'environnement de la session ; sans cet accès, Wakastart ne calcule aucun contexte et l'API répond 401.

Prise en compte des changements de droits

Wakastart garde le contexte calculé d'un utilisateur au plus 60 secondes. Un profil attribué ou retiré par un administrateur est donc visible dans /api/me en une minute au plus. Rechargez /api/me après chaque rafraîchissement de session pour suivre ces changements.

Durées de session

Valeurs par défaut des realms Wakastart :

ÉlémentDurée par défaut
Jeton d'accès Keycloak5 minutes
Code d'autorisation5 minutes
Session de l'application, sans activité6 heures
Session de l'application, au maximum12 heures
Session Keycloak (connexion unique), sans activité et au maximum24 heures

Lisez toujours expires_in et refresh_expires_in dans la réponse de Keycloak plutôt que de coder ces valeurs. Tant que le refresh token est valide, votre serveur obtient de nouveaux jetons sans intervention de l'utilisateur. Une fois la session expirée, l'utilisateur repasse par la page de connexion.

Fin de session

La déconnexion invalide le refresh token et ferme la session Keycloak. Le jeton d'accès déjà émis reste techniquement valide jusqu'à son expiration : c'est pourquoi sa durée est courte. Un compte désactivé dans Wakastart ne peut plus obtenir de contexte : l'API publique refuse ses appels.

Exemples

  • Afficher ou masquer un bouton. Votre front lit profile.rights dans la réponse de /api/me, mise en cache dans la session serveur.
  • Protéger une route de votre backend. Votre backend vérifie la signature du jeton Keycloak, puis contrôle le droit dans /api/me.
  • Appeler un module Wakastart. Votre serveur transmet le jeton Keycloak de l'utilisateur à l'API publique ; Wakastart applique lui-même les droits.

Pour aller plus loin