Jeton enrichi et /me
Jeton Keycloak, jeton enrichi et GET /api/me : ce que porte chacun, comment les obtenir et lequel utiliser pour quoi.
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
| Jeton Keycloak | Jeton enrichi | Réponse de /api/me | |
|---|---|---|---|
| Émis par | l'instance Keycloak de l'environnement | Wakastart | l'API publique |
| Contient | identité 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, langue | identité, organisation, profil de l'environnement avec ses droits, équipes, habillage |
| Contient les droits ? | non | non | oui |
| Durée | réglée par le realm | celle du jeton Keycloak, sinon 15 minutes | lue à chaque appel |
| Usage | s'authentifier auprès de l'API publique | s'authentifier ; son payload, lu à l'émission, donne l'organisation sans autre appel | dé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 :
| Revendication | Contenu |
|---|---|
sub, email, given_name, family_name | identité de l'utilisateur |
azp | l'application pour laquelle le jeton Keycloak a été émis |
wadl | niveau d'administration |
pid, nid, cid, aid, uid | WID du partenaire, du réseau, du client, de l'application et de l'utilisateur |
wenv | environnement 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, wlng | thème et langue, résolus en cascade |
jti, exp, iss | identifiant 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/mene prend aucun paramètre d'environnement : il n'existe pas de lecture « tous environnements » ; - l'organisation :
partner,network,customer, chacun avec sonwidet sonname; teams: les équipes et le rôle (teamLevel) de l'utilisateur dans chacune ;profile: le profil de cette fiche, avecrights, 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.
{
"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 voulez | Utilisez |
|---|---|
| Appeler l'API publique au nom de l'utilisateur | le jeton Keycloak, ou le jeton enrichi |
| Connaître le client ou l'environnement de l'utilisateur sans appel | le payload du jeton enrichi, gardé en session |
| Savoir si l'utilisateur a un droit | GET /api/me |
| Habiller l'interface aux couleurs du client | GET /api/me (branding) |
| Appeler l'API depuis un serveur, sans utilisateur | une clé API |
Pour aller plus loin
- Référence API : jeton et /me : les endpoints et tous les champs.
- Droits, profils et équipes : d'où viennent les droits.
- Connecter vos utilisateurs : obtenir le jeton Keycloak et appeler
/api/me. - Authentification de l'API : les trois façons de s'authentifier.