Jeton de contexte
Borner à l'organisme d'un client une action que votre wakapp fait sur Wakastart avec sa clé sk_, et en tracer l'origine.
Une clé de votre wakapp n'a aucun droit sur Wakastart. Quand l'appel d'un client doit déclencher une action Wakastart, inviter un apprenant par exemple, c'est votre wakapp qui la demande, avec sa propre clé sk_. Elle y joint un jeton de contexte, qui borne l'action à l'organisme du client et en prouve l'origine.
Important
Le jeton de contexte est en cours de déploiement. Tant que l'introspection ne renvoie pas de context_token sur votre environnement, continuez d'appeler Wakastart avec votre seule clé sk_. Au lancement, toutes les actions sont en mode observe : un appel sans contexte n'est refusé qu'une fois l'action passée en required ou bound pour votre application.
Définition
Le jeton de contexte est un jeton signé par Wakastart, valable 60 secondes au plus. Il atteste que Wakastart a vérifié, il y a moins d'une minute, soit une clé d'un organisme présentée à votre wakapp, soit le jeton d'un utilisateur de votre wakapp. Votre wakapp le joint à ses appels dans l'en-tête X-WakaStart-Context, en plus de sa clé sk_.
Il ne fait que restreindre :
organismes effectifs = organismes de la clé sk_ ∩ organisme(s) du contexte
droits effectifs ⊆ droits de la clé sk_Il n'ajoute aucun droit à votre clé sk_ : il borne l'organisme.
Pourquoi ça existe
La clé sk_ d'une wakapp couvre souvent plusieurs organismes. Prenons une wakapp de formation dont la clé couvre l'Organisme Alpha et l'Organisme Beta :
- Le SI de l'Organisme Alpha demande à la wakapp d'inviter un apprenant. La wakapp vérifie la clé
wsk_reçue : organisme Alpha, droitparticipants.inviteprésent. - La wakapp appelle
POST /api/invitationsavec sa clésk_.
Si la wakapp prend l'organisme cible dans la requête du client, par erreur ou par malveillance, la clé de l'Organisme Alpha fait inviter quelqu'un chez l'Organisme Beta. Sans contexte, Wakastart voit une demande légitime, avec une clé valable sur les deux organismes, et ne sait pas quel client l'a déclenchée. Avec le contexte, Wakastart refuse toute action hors de l'organisme qui a présenté sa clé.
Comment ça marche
Deux contextes
| Contexte | Quand | Comment l'obtenir | Organisme imposé |
|---|---|---|---|
Clé client (origin_type: customer_api_key) | Un client appelle votre wakapp avec une clé de votre wakapp, avec ou sans personne derrière | Champ context_token de la réponse d'introspection | Celui de la clé, toujours lu dans l'enregistrement de la clé |
Utilisateur (origin_type: user) | Un utilisateur connecté à votre wakapp y détient le droit, mais pas le droit Wakastart correspondant : le bouton « Inviter » d'un formateur, par exemple | POST /api/app-keys/user-context avec le jeton de l'utilisateur | Ceux de sa portée ; un administrateur réseau peut en avoir plusieurs |
Le contexte « utilisateur » ne remplace pas l'envoi du jeton de l'utilisateur. Si vous transmettez directement ce jeton à Wakastart, l'action est faite avec ses droits et sa portée, et votre clé est ignorée. Le contexte « utilisateur » sert à l'autre cas : votre wakapp agit avec sa propre clé pour le compte d'un utilisateur qui n'a pas lui-même le droit Wakastart.
Modes par action
Wakastart règle l'exigence de contexte par type d'action et par application :
| Mode | Contexte absent | Contexte présent mais refusé | Usage unique |
|---|---|---|---|
observe | Accepté | Accepté ; l'écart est journalisé par Wakastart | Non |
preferred | Accepté ; l'absence est journalisée | Refusé | Non |
required | Refusé (403 CONTEXT_REQUIRED) | Refusé | Non |
bound | Refusé (403 CONTEXT_REQUIRED) | Refusé | Oui |
- Sans usage unique, un contexte valide sert pendant ses 60 secondes : relecture, pagination, plusieurs actions de la même requête.
- En
bound, un contexte ne sert qu'à une seule action, sur une seule cible : le second usage est refusé (403 CONTEXT_REPLAYED). Pour une seconde action, obtenez un nouveau contexte.
Toutes les actions démarrent en observe. La bascule vers un mode plus strict se fait application par application et par type d'action, en commençant par les invitations, puis les profils, les droits et les comptes. Les nouvelles wakapps ont vocation à démarrer directement en required. Joignez donc le contexte dès maintenant à chaque action déclenchée par un client : en observe, il ne gêne pas, et votre wakapp sera prête au passage en required.
Ce que Wakastart vérifie
Avec un contexte, Wakastart refuse notamment :
- une action dont l'organisme cible n'est pas celui du contexte ;
- une demande dont un objet (profil attribué, équipe, invitation, utilisateur visé) n'appartient pas à l'organisme du contexte ;
- la création ou la modification d'un compte avec un niveau d'administration au-dessus d'Administrateur client ;
- un contexte expiré, ou émis pour une autre application ou un autre environnement ;
- un contexte dont la clé client a été révoquée, suspendue, ou dont les droits ont changé depuis son émission.
Par ailleurs, avec ou sans contexte, personne n'attribue un niveau supérieur au sien : votre clé sk_ a le niveau de son compte. La liste complète des refus est dans Codes d'erreur.
Ce que le contexte garantit, et ce qu'il ne garantit pas
- Il prouve que Wakastart a vérifié, il y a moins de 60 secondes, une clé de cet organisme présentée à votre wakapp, ou le jeton d'un utilisateur de votre wakapp.
- Il empêche votre code de viser un autre organisme : votre wakapp ne peut pas fabriquer un contexte pour un organisme dont aucune clé ne lui a été présentée.
- Il ne prouve pas que l'utilisateur a le droit de demander l'action dans votre wakapp, ni que l'opération a été voulue par le client : ce contrôle reste celui de votre wakapp.
- Wakastart trace chaque action faite avec un contexte : votre application, l'origine prouvée (clé client ou utilisateur) et l'organisme réellement touché.
Exemples
- Un traitement nocturne. Le SI de l'Organisme Alpha appelle votre wakapp avec sa clé
wsk_pour inscrire des apprenants. L'introspection renvoie uncontext_token; votre wakapp le joint à chaquePOST /api/invitationsde cette requête. - Le bouton « Inviter » d'un formateur. Le formateur détient
participants.invitedans votre wakapp, mais aucun droit Wakastart. Votre wakapp vérifie son droit, obtient un contexte « utilisateur », puis invite avec sa clésk_dans l'organisme du formateur.