Aller au contenu

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.

ConceptDéveloppeurBêta
Voir en Markdown

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 :

Texte
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 :

  1. Le SI de l'Organisme Alpha demande à la wakapp d'inviter un apprenant. La wakapp vérifie la clé wsk_ reçue : organisme Alpha, droit participants.invite présent.
  2. La wakapp appelle POST /api/invitations avec 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

ContexteQuandComment l'obtenirOrganisme imposé
Clé client (origin_type: customer_api_key)Un client appelle votre wakapp avec une clé de votre wakapp, avec ou sans personne derrièreChamp context_token de la réponse d'introspectionCelui 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 exemplePOST /api/app-keys/user-context avec le jeton de l'utilisateurCeux 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 :

ModeContexte absentContexte présent mais refuséUsage unique
observeAcceptéAccepté ; l'écart est journalisé par WakastartNon
preferredAccepté ; l'absence est journaliséeRefuséNon
requiredRefusé (403 CONTEXT_REQUIRED)RefuséNon
boundRefusé (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 un context_token ; votre wakapp le joint à chaque POST /api/invitations de cette requête.
  • Le bouton « Inviter » d'un formateur. Le formateur détient participants.invite dans 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.

Pour aller plus loin