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.
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 Keycloak | Jeton enrichi (wakaToken) | Réponse de /api/me | |
|---|---|---|---|
| Émis par | L'instance Keycloak de l'environnement | Wakastart, à partir du jeton Keycloak | L'API publique |
| Format | JWT signé RS256 par Keycloak | JWT signé par Wakastart | JSON |
| Porte | Identité OIDC (sub, email), azp (identifiant client de votre application), iss (instance et realm), wenv (environnement), organisation | Identité, niveau d'administration (wadl), identifiants courts du partenaire, du réseau, du client, de l'application et de l'utilisateur, thème, langue, environnement | Identité, organisation, équipes, profil avec ses droits, habillage |
| Sert à | Appeler l'API publique, vérifier l'identité dans votre backend | Transmettre un contexte signé à l'API publique sans nouvel enrichissement | Décider de l'affichage et des autorisations dans votre application |
| Durée | 5 minutes par défaut | Celle du jeton Keycloak d'origine, 15 minutes au plus si elle est inconnue | Valable 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ément | Durée par défaut |
|---|---|
| Jeton d'accès Keycloak | 5 minutes |
| Code d'autorisation | 5 minutes |
| Session de l'application, sans activité | 6 heures |
| Session de l'application, au maximum | 12 heures |
| Session Keycloak (connexion unique), sans activité et au maximum | 24 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.rightsdans 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.