Tokens

Imaginez que vous avez créé une boutique de vêtements en ligne. Vous voulez afficher, sur le site que voient vos clients, les produits que vous avez enregistrés dans le studio de contenu. Mais ce site n'est pas une personne, c'est un programme. Il ne peut pas se connecter avec un identifiant et un mot de passe comme le ferait un humain. Dans ce cas, la clé secrète que l'on délivre pour qu'un site ou un programme puisse accéder au contenu à la place d'une personne, c'est le token.

Voyez le token comme une clé qui ouvre une serrure. Celui qui détient cette clé peut manipuler le contenu dans des limites définies, sans avoir à se connecter. C'est pourquoi un token doit être traité exactement comme un mot de passe. Il ne faut le montrer à personne, et s'il fuite, celui qui le récupère peut utiliser tels quels les droits associés.

WEEGLOO propose deux types de clés aux usages différents. La première est une clé puissante liée à un compte (Personal Access Token), la seconde une clé restreinte servant à lire et transmettre du contenu vers un site public (Delivery Access Token). Sur cette page, vous découvrirez ce qu'est chacune de ces clés et quand l'utiliser, puis vous en délivrerez une vous-même depuis le studio de contenu.

Les deux clés ont des usages différents

Voici d'abord, en un coup d'œil, ce qui les distingue.

L'essentiel est le suivant. Le Personal Access Token se rapproche d'un passe-partout qui agit à la place d'une personne, tandis que le Delivery Access Token est une clé restreinte qui « ne permet de voir que le panneau d'affichage à l'entrée ». Leurs usages ne se chevauchent pas, il vous suffit donc de choisir celle qui correspond à ce que vous voulez faire.

La clé liée à un compte : Personal Access Token

Le Personal Access Token est une clé liée au compte qui l'a délivrée. Avec cette clé, vous pouvez faire, sans vous connecter, tout ce que ce compte peut faire dans le studio de contenu. Cela va jusqu'aux tâches de gestion comme enregistrer un produit, le modifier ou le publier.

Cette clé est donc puissante. Par exemple, si vous créez un programme qui met automatiquement en ligne les nouveaux produits dans le studio de contenu chaque nuit, ce programme ne peut pas se connecter comme une personne : vous lui confiez donc cette clé. C'est la clé que l'on utilise pour faire tourner automatiquement des tâches de gestion là où aucune personne ne regarde directement, comme un serveur ou un script d'automatisation.

Aussi puissante soit-elle, elle demande de la prudence. Cette clé ne doit pas être placée dans le site public que voient vos clients, ni dans un navigateur. Si vous la placez dans un endroit public, n'importe qui peut l'en extraire, et celui qui met la main dessus peut utiliser tels quels les droits du compte qui l'a délivrée. Quand il s'agit seulement de récupérer et d'afficher des produits sur un site public, on n'utilise pas cette clé puissante mais le Delivery Access Token présenté ci-dessous.

Pour délivrer un Personal Access Token, il suffit de lui donner un nom. Vous ne choisissez pas séparément l'étendue des droits, car elle hérite telle quelle des droits du compte qui l'a délivrée.

La clé liée à un Space : Delivery Access Token

Le Delivery Access Token est une clé en lecture seule liée à un seul Space précis. Avec cette clé, vous pouvez uniquement lire le contenu à l'état Published (publié) à l'intérieur de ce Space. Le contenu à l'état Draft, qui n'a pas été publié, ne se lit pas avec cette clé, et il n'est pas non plus possible de le modifier ou de le supprimer.

C'est précisément cette clé qu'utilise le site de votre boutique pour récupérer et afficher des produits. Le site n'a qu'à afficher les produits, il n'a pas besoin de les enregistrer ni de les supprimer : une clé restreinte qui ne sait que lire suffit donc. Même si cette clé fuite, on pourra seulement lire le contenu publié, mais on ne pourra pas endommager le contenu.

Ce que signifie publier (Published) du contenu et pourquoi il faut le publier pour qu'il soit rendu public (transmis) à l'extérieur est traité dans États et publication.

Associez un rôle restreint pour limiter la portée de lecture

Lorsque vous délivrez un Delivery Access Token, vous définissez jusqu'où cette clé peut lire au moyen d'un SpaceRole (rôle) que vous lui associez. Un rôle est un ensemble de droits qui définit « quoi et jusqu'à quelle action il est possible de faire ». Quand vous associez un rôle à une clé, cette clé ne peut lire que ce qu'autorise le rôle associé.

Pour le site de la boutique, il suffit de lire les « produits » : vous créez donc un rôle restreint qui n'autorise que Read sur les produits (Content), et vous l'associez. Ainsi, même si cette clé fuite, seules les informations sur les produits seront lisibles, sans que d'autres contenus ni les informations des membres ne fuitent.

N'associez pas le rôle Administrator, qui peut tout faire. L'Administrator est le rôle au pouvoir le plus élevé, capable de tout faire à l'intérieur de ce Space. Si vous associez des droits aussi larges à une clé destinée à un site public qui n'a qu'à lire, le risque devient grand en cas de fuite de la clé. Il est plus sûr de créer à part un rôle restreint à la seule lecture du nécessaire, puis de l'associer.

La façon de créer un rôle et d'en restreindre les droits est traitée dans Rôles et permissions. En vous appuyant sur cette page, préparez à l'avance le rôle, n'autorisant que Read sur les produits, que vous associerez à la clé destinée au site public.

Gérer la valeur secrète délivrée

Pour les deux clés, une fois la délivrance terminée, une valeur de token secrète apparaît à l'écran. Cette valeur est la clé elle-même. C'est cette valeur que vous utilisez lorsque vous la placez dans un serveur ou un site. Copiez-la sur place juste après la délivrance et conservez-la. Vous pouvez aussi la retrouver depuis l'écran de détail du token.

Toutefois, les deux clés ne se rangent pas au même endroit.

• Traitez le Personal Access Token comme un mot de passe. C'est une clé puissante : gardez-la uniquement sur le serveur et ne la placez pas dans le site public que voient vos clients, ni dans un navigateur, ni dans du code que d'autres peuvent voir.
• Le Delivery Access Token, à l'inverse, a justement pour vocation d'être placé dans le site public que voient vos clients. Toute personne qui ouvre le site peut en somme voir cette valeur, mais comme vous y avez associé un rôle restreint, quiconque récupère cette valeur ne pourra rien faire au-delà de la portée de lecture qu'autorise ce rôle. La placer dans le site ne pose donc pas de problème en soi. Évitez simplement de la diffuser à la légère en dehors du site auquel elle est destinée.

Si vous avez perdu une clé ou qu'elle semble utilisée autrement que prévu, il vous suffit de la supprimer, d'en délivrer une nouvelle et de remplacer l'ancienne.

Délivrer un Personal Access Token

Vous allez délivrer un Personal Access Token à confier au programme qui met en ligne automatiquement les nouveaux produits chaque nuit.

1. Dans les paramètres du compte, ouvrez l'écran Personal Access Token.
2. Cliquez sur le bouton Créer en haut à droite.
3. Dans le champ du nom, saisissez Mise en ligne nocturne des nouveautés. Ce nom sert à reconnaître plus tard à quel usage la clé a été créée.
4. Cliquez sur le bouton Enregistrer pour délivrer la clé.

Une fois la délivrance terminée, la valeur de token secrète apparaît à l'écran. Copiez-la sur place et conservez-la dans un endroit sûr. L'écran a la même apparence que le résultat de la délivrance du Delivery Access Token ci-dessous.

Délivrer un Delivery Access Token

Cette fois, vous allez délivrer le Delivery Access Token que le site de la boutique utilisera pour récupérer et afficher les produits. Cette clé est liée au Space de la boutique de vêtements, et on lui associe un rôle restreint capable de lire les produits.

Il faut d'abord que le rôle à associer à cette clé existe dans le Space. Préparez à l'avance, dans Rôles et permissions, un rôle qui n'autorise que Read sur les produits (Content). Ci-dessous, on suppose que ce rôle a été créé sous le nom Lecture seule des produits.

1. Dans les paramètres du Space de la boutique de vêtements, ouvrez l'écran Delivery Access Token.
2. Cliquez sur le bouton Créer en haut à droite.
3. Dans le champ du nom, saisissez Transmission vers le site de la boutique.
4. Dans le champ de description, vous pouvez noter à quoi sert cette clé. (Facultatif.)
5. Dans Space Role, choisissez Lecture seule des produits. Ne choisissez pas Administrator.
6. Cliquez sur le bouton Créer pour délivrer la clé.

Une fois la délivrance terminée, la valeur de token secrète apparaît à l'écran. Copiez-la sur place et conservez-la dans un endroit sûr.

Supprimez les clés que vous n'utilisez plus

Il est plus sûr de ne pas laisser traîner une clé devenue inutile, mais de la supprimer. Dans la liste des tokens, repérez la clé que vous n'utilisez plus et supprimez-la. Une fois la clé supprimée, il n'est plus possible d'accéder à quoi que ce soit avec elle. Il en va de même lorsqu'une clé semble avoir fuité. Il vous suffit de supprimer la clé suspecte, d'en délivrer une nouvelle et de remplacer l'ancienne.

Et ensuite

• Rôles et permissions : créez le rôle, à la portée de lecture restreinte, que vous associerez au Delivery Access Token.
• États et publication : avec un Delivery Access Token, on ne lit que le contenu à l'état Published. Découvrez ce qu'est la publication.
• Référence API : traite les spécifications techniques, comme le format des requêtes, nécessaires pour délivrer un token ou récupérer du contenu directement depuis un programme.