Aller au contenu

Jeton enrichi et /me

Jeton Keycloak, jeton enrichi et GET /api/me : ce que porte chacun, comment les obtenir et lequel utiliser pour quoi.

ConceptDéveloppeur
Voir en Markdown

Après la connexion, votre application dispose d'un jeton Keycloak. Wakastart en tire deux choses : un jeton enrichi, court et signé, qui dit qui est l'utilisateur et dans quelle organisation ; et la réponse de GET /api/me, complète, qui ajoute son profil, ses droits, ses équipes et l'habillage à appliquer.

Définition

Chargement du schéma…
Jeton KeycloakJeton enrichiRéponse de /api/me
Émis parl'instance Keycloak de l'environnementWakastartl'API publique
Contientidentité OIDC, realm (dans l'émetteur), application (azp)niveau d'administration, WID du partenaire, du réseau, du client, de l'application et de l'utilisateur, environnement, thème, langueidentité, organisation, profil de l'environnement avec ses droits, équipes, habillage
Contient les droits ?nonnonoui
Duréeréglée par le realmcelle du jeton Keycloak, sinon 15 minuteslue à chaque appel
Usages'authentifier auprès de l'API publiques'authentifier ; son payload, lu à l'émission, donne l'organisation sans autre appeldécider de ce que l'utilisateur peut faire, habiller l'interface

Pourquoi ça existe

Le jeton Keycloak ne connaît que l'identité : il ignore le client de l'utilisateur, son profil et ses droits, qui vivent dans Wakastart. Le jeton enrichi ajoute ce contexte tout en restant assez petit pour voyager dans un cookie ; c'est pourquoi il ne transporte pas les droits, trop nombreux. GET /api/me donne tout, au prix d'un appel.

Comment ça marche

Le jeton enrichi

POST https://api.wakastart.app/api/auth/enrich, avec le jeton Keycloak en Authorization: Bearer, renvoie { token, payload } : le jeton signé et son contenu décodé. Ses clés de vérification ne sont pas publiées : lisez le contenu dans payload, au moment de l'émission, et faites vérifier le jeton par l'API publique plutôt que de décoder un jeton reçu d'ailleurs. Ses revendications :

RevendicationContenu
sub, email, given_name, family_nameidentité de l'utilisateur
azpl'application pour laquelle le jeton Keycloak a été émis
wadlniveau d'administration
pid, nid, cid, aid, uidWID du partenaire, du réseau, du client, de l'application et de l'utilisateur
wenvenvironnement de connexion : dev, staging ou prod. C'est lui qui désigne la fiche de l'utilisateur et la matrice de droits utilisées par toute l'API
wthm, wlngthème et langue, résolus en cascade
jti, exp, issidentifiant unique, expiration, émetteur wakastart-token-service

L'enrichissement échoue si l'utilisateur n'a pas de fiche ni d'accès à l'application dans cet environnement, ou si sa fiche est désactivée. Le uid est le WID de la fiche de cet environnement : une personne présente sur plusieurs environnements a un WID par environnement.

GET /api/me

GET https://api.wakastart.app/api/me accepte le jeton Keycloak (Authorization: Bearer) ou le jeton enrichi (x-enriched-token). Il renvoie :

  • l'identité de la fiche de l'environnement de connexion : wid, email, firstName, lastName, isActive, adminLevel, hdsRoles. /api/me ne prend aucun paramètre d'environnement : il n'existe pas de lecture « tous environnements » ;
  • l'organisation : partner, network, customer, chacun avec son wid et son name ;
  • teams : les équipes et le rôle (teamLevel) de l'utilisateur dans chacune ;
  • profile : le profil de cette fiche, avec rights, la liste des droits (code, name, category) lus dans la matrice de l'environnement de connexion ;
  • branding : logos, couleurs et variables CSS du thème, résolus du client vers l'application ;
  • lastLoginAt, createdAt.
JSON
{
  "wid": "EXUSR1",
  "email": "claire.martin@exemple.fr",
  "adminLevel": "NONE",
  "customer": { "wid": "EXCLI1", "name": "Clinique Exemple" },
  "teams": [{ "wid": "EXTEA1", "name": "Cardiologie", "teamLevel": "MEMBER" }],
  "profile": {
    "wid": "EXPRF1",
    "name": "Soignant",
    "rights": [{ "code": "dossiers.read", "name": "Lire les dossiers", "category": "Dossiers" }]
  }
}

Ce que l'API vérifie

Quel que soit le jeton présenté, l'API publique vérifie qu'il a été émis pour l'application concernée. Elle refuse avec 401 une requête sans jeton valide, et avec 403 un jeton d'une autre application ou un droit manquant. Un changement de profil ou de droits est pris en compte dans la minute.

Exemples

Afficher ou masquer un bouton. Au chargement, le back appelle /api/me et transmet au front la liste des codes de profile.rights. Le bouton « Signer l'ordonnance » n'apparaît que si ordonnances.sign y figure ; l'API de votre application refait la vérification côté serveur.

Router par organisation sans appel réseau. Après la connexion, votre serveur garde dans la session le payload renvoyé par POST /api/auth/enrich et y lit cid pour diriger chaque requête vers la base du bon client.

Lequel utiliser ?

Vous voulezUtilisez
Appeler l'API publique au nom de l'utilisateurle jeton Keycloak, ou le jeton enrichi
Connaître le client ou l'environnement de l'utilisateur sans appelle payload du jeton enrichi, gardé en session
Savoir si l'utilisateur a un droitGET /api/me
Habiller l'interface aux couleurs du clientGET /api/me (branding)
Appeler l'API depuis un serveur, sans utilisateurune clé API

Pour aller plus loin