Tokens

Imaginez que vous avez créé une boutique de vêtements en ligne. Vous voulez récupérer et 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 détient peut utiliser tels quels les droits associés.

WEEGLOO propose trois types de clés aux usages différents : une clé puissante qui agit à la place d'un compte tout entier (Personal Access Token), une clé de lecture et d'écriture du contenu au sein d'un seul Space (Space Access Token), et une clé en lecture seule 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 trois clés et quand l'utiliser, puis vous en délivrerez une vous-même depuis le studio de contenu.

Les trois clés ont des usages différents

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

L'essentiel est le suivant. Le Personal Access Token se rapproche d'un passe-partout qui agit à la place d'une personne tout entière ; le Space Access Token est une clé qui lit et écrit du contenu au sein d'un seul Space ; et le Delivery Access Token est une clé en lecture seule qui se contente de lire le contenu publié. Selon que ce que vous voulez faire couvre l'ensemble d'un compte, va jusqu'à l'écriture au sein d'un seul Space, ou se limite à la lecture sur un site public, il vous suffit de choisir la clé qui convient.

La clé qui agit à la place d'un compte tout entier : Personal Access Token

Le Personal Access Token est une clé qui utilise tels quels les droits du 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, modifier ou publier un produit.

Cette clé est donc puissante. Si vous la confiez à un programme qui met en ligne et modifie automatiquement du contenu à la place d'une personne, ce programme peut travailler comme le propriétaire du compte. Pour des tâches de gestion qui vont d'un Space à l'autre ou qui touchent jusqu'aux paramètres d'un Space, cette clé est nécessaire. À l'inverse, pour une tâche qui consiste seulement à lire et écrire du contenu au sein d'un seul Space, il est plus sûr de restreindre les droits avec le Space Access Token présenté plus loin, plutôt que d'utiliser cette clé qui remplace un compte tout entier.

Aussi puissante soit-elle, elle demande de la prudence. Cette clé ne doit pas être placée dans un client public transmis à vos clients. 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 utilise le Delivery Access Token ci-dessous plutôt que cette clé puissante.

Pour délivrer un Personal Access Token, il vous suffit d'en définir le 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é qui lit et écrit au sein d'un Space : Space Access Token

Le Space Access Token est une clé qui ne s'utilise qu'au sein d'un seul Space précis. Contrairement au Delivery Access Token, qui ne permet que la lecture, cette clé permet de lire mais aussi d'écrire le contenu de ce Space. Un programme peut ainsi enregistrer de nouveaux produits ou les modifier à la place d'une personne, sans que celle-ci ait à se connecter.

Imaginez par exemple que vous vouliez permettre à vos clients de laisser un message de contact sur le site de la boutique sans même se connecter. Le client qu'utilise le visiteur doit écrire ce message dans le Space de la boutique, mais le Delivery Access Token, en lecture seule, ne permet pas d'écrire. Et si vous placiez dans le client le Personal Access Token, qui remplace un compte tout entier, une fuite de cette clé mettrait en danger non seulement la boutique, mais tout ce que le compte peut atteindre. C'est dans ce cas qu'intervient le Space Access Token, qui va jusqu'à l'écriture mais seulement au sein d'un seul Space. Faire écrire du contenu depuis le client d'un visiteur est l'usage type de cette clé, et on l'utilise aussi lorsqu'un serveur enregistre et modifie du contenu automatiquement.

Le Space Access Token n'exerce son pouvoir qu'au sein d'un seul Space. Il peut lire et écrire le contenu du Space de la boutique, mais il ne peut ni regarder dans un autre Space, ni changer les paramètres du Space, ni toucher à l'organisation et au compte. C'est pourquoi, à travail d'écriture équivalent, il est plus sûr que le Personal Access Token.

Où placer cette clé se décide selon l'usage. Vous pouvez la placer sur un serveur, ou dans le client qu'utilise le visiteur. La sécurité s'assure non pas en cachant la clé quelque part, mais en restreignant le rôle associé à son usage. C'est pourquoi la façon de lier le rôle, abordée ensuite, est importante.

Liez un rôle pour définir la portée de lecture et d'écriture

Lorsque vous délivrez un Space Access Token, vous définissez là aussi jusqu'où cette clé peut aller au moyen d'un SpaceRole (rôle) que vous lui associez. Contrairement au rôle du Delivery Access Token, qui définit « jusqu'où on peut lire », le rôle du Space Access Token définit « jusqu'où on peut lire et écrire ».

Le rôle associé se restreint selon l'endroit où la clé est placée. Pour une clé qui enregistre et modifie automatiquement des produits sur un serveur, associez un rôle qui n'autorise que Read, Create et Edit sur les produits (Content), sans y inclure Delete ni Publish. En revanche, pour une clé placée dans le client d'un visiteur et qui ne reçoit que des messages de contact, associez un rôle plus restreint qui n'autorise que la création (Create) des « messages de contact ». Ainsi, même si cette valeur fuite, on ne peut rien faire au-delà de ce que chacun autorise.

N'associez pas le rôle Administrator, qui peut tout faire. Plus une clé va jusqu'à l'écriture, et plus elle est placée dans un endroit visible par les visiteurs, plus il faut, pour la sécurité, y associer un rôle assez restreint pour que vous puissiez l'assumer même en cas de fuite.

La façon de créer un rôle qui autorise l'écriture est traitée dans Rôles et permissions. Le rôle « Responsable de l'enregistrement des produits » créé sur cette page est un exemple de rôle en écriture qui autorise jusqu'à l'enregistrement et la modification des produits.

La clé qui ne fait que lire au sein d'un Space : Delivery Access Token

Le Delivery Access Token est une clé en lecture seule qui ne vaut qu'au sein d'un seul Space précis. Avec cette clé, vous pouvez uniquement récupérer le contenu à l'état Published (publié) à l'intérieur de ce Space. Le contenu à l'état Draft, non 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 la clé qu'utilise le site de la boutique que voient vos clients pour récupérer et afficher les produits. Le site n'a qu'à afficher les produits, sans avoir 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é, sans pouvoir l'endommager.

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.

Définissez avec les Referrers autorisés les sites où cette clé peut servir

Si le rôle associé définit ce que cette clé peut lire, les Referrers autorisés définissent d'où elle peut être utilisée. Ce réglage se trouve en bas de l'écran de création, et il reste modifiable après la délivrance.

La valeur de départ est Aucune restriction. Dans cet état, le contenu est transmis quel que soit le site qui le demande. Si vous choisissez N'autoriser que les referrers indiqués, des champs où saisir une adresse apparaissent, et dès lors seules les requêtes venues des adresses inscrites ici passent. Si l'adresse de la boutique en ligne est https://shop.example.com, inscrivez cette adresse. Ainsi, même si la valeur de cette clé tombe entre les mains d'un tiers, elle ne fonctionne pas en dehors du site de la boutique.

Vous pouvez inscrire plusieurs adresses. Le bouton Ajouter fait apparaître un champ de plus, et l'icône de suppression à droite d'un champ retire cette ligne.

Pour autoriser d'un seul coup les adresses rattachées sous shop.example.com, ajoutez *. en tête et écrivez https://*.shop.example.com. Cette écriture couvre toutes les adresses qui portent quelque chose devant, comme event.shop.example.com. Elle n'inclut toutefois pas l'adresse https://shop.example.com elle-même. Si vous devez autoriser les deux, ajoutez aussi https://shop.example.com sur une ligne à part.

Cette liste fonctionne pour le cas où un visiteur ouvre le site dans son navigateur et y récupère le contenu. Si cette clé est utilisée non pas par un site mais par un programme qui tourne sur un serveur, on ne peut pas savoir de quel site vient la requête : pour une telle clé, laissez donc Aucune restriction en place.

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

Pour les trois clés, une fois la délivrance terminée, vous arrivez sur l'écran de détail de la clé. Le champ Token des Informations de base contient la valeur de token secrète, et le bouton Copier placé à gauche du champ copie la valeur entière. La valeur est plus longue que le champ : à l'écran, sa fin apparaît donc coupée, mais la copie porte bien sur la valeur entière. Cette valeur est la clé elle-même, et c'est elle que vous utilisez lorsque vous la placez dans un serveur ou un site. Même si vous ne l'avez pas copiée juste après la délivrance, vous pouvez revenir plus tard sur cet écran de détail pour la copier. L'ID qui figure sous la rubrique Token du panneau de droite est un identifiant qui désigne cette clé, et non une valeur secrète.

Toutefois, chaque clé ne se range 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 un client public que voient vos clients, ni dans du code que d'autres peuvent voir.
• Pour le Space Access Token, adaptez l'endroit où vous le placez au moyen du rôle associé. À une clé placée sur un serveur, associez un rôle en écriture à la mesure du nécessaire ; à une clé placée dans un client transmis aux clients, associez un rôle assez restreint pour que vous puissiez l'assumer même en cas de fuite (par exemple, ne créer qu'un seul type de publication). N'associez pas l'Administrator ni un rôle d'écriture étendu à une clé placée dans un endroit public.
• 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. Si vous inscrivez en plus l'adresse du site de la boutique dans les Referrers autorisés, cette valeur ne peut plus servir en dehors de ce site, même si elle tombe entre les mains d'un tiers. É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, vous arrivez sur l'écran de détail de la clé. Copiez depuis cet écran la valeur de token secrète, comme l'explique Gérer la valeur secrète délivrée, et conservez-la dans un endroit sûr du serveur où tourne ce programme.

Délivrer un Space Access Token

Cette fois, vous allez délivrer le Space Access Token qu'utilisera le serveur chargé d'enregistrer automatiquement des produits dans le Space de la boutique. Cette clé est utilisée dans le Space de la boutique, et on lui associe un rôle capable d'enregistrer et de modifier 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 capable de faire Read, Create et Edit sur les produits (Content). Ci-dessous, on suppose que ce rôle a été créé sous le nom Responsable de l'enregistrement des produits.

L'écran de délivrance et de gestion se trouve dans les paramètres du Space, au même endroit que celui du Delivery Access Token.

1. Dans les paramètres du Space de la boutique, ouvrez l'écran Space Access Token.
2. Cliquez sur le bouton Créer en haut à droite de la liste. L'écran de création du Space Access Token s'ouvre.
3. Dans le champ Nom, saisissez Serveur d'enregistrement automatique des nouveautés.
4. Dans SpaceRole, choisissez Responsable de l'enregistrement des produits. Ne choisissez pas Administrator.
5. Pour les Referrers autorisés, laissez Aucune restriction en place. Cette clé est en effet utilisée sur un serveur, et non par un site.
6. Cliquez sur le bouton Créer en haut à droite de l'écran pour délivrer la clé.

Une fois la délivrance terminée, vous arrivez sur l'écran de détail de la clé. Copiez depuis cet écran la valeur de token secrète, comme l'explique Gérer la valeur secrète délivrée, et conservez-la dans un endroit sûr. Ici, comme vous avez associé un rôle capable d'enregistrer et de modifier les produits, cette clé s'utilise sur le serveur qui a besoin de ce rôle. Si vous devez la placer directement dans le client qu'utilise un visiteur, délivrez à part une clé associée à un rôle plus restreint, assez pour que vous puissiez l'assumer même en cas de fuite. Pour une clé ainsi transmise aux visiteurs, inscrivez de plus l'adresse du site qui l'utilise dans les Referrers autorisés.

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 utilisée dans le Space de la boutique, 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, ouvrez l'écran Delivery Access Token.

2. Cliquez sur le bouton Créer en haut à droite de la liste. L'écran de création du Delivery Access Token s'ouvre.

3. Dans le champ Nom, saisissez Transmission vers le site de la boutique.

4. Dans le champ Description, vous pouvez noter à quoi sert cette clé. (Facultatif.)

5. Dans SpaceRole, choisissez Lecture seule des produits. Ne choisissez pas Administrator.

   

6. En bas de l'écran, dans les Referrers autorisés, choisissez N'autoriser que les referrers indiqués. Ce réglage limite l'usage de cette clé au seul site de la boutique.

7. Dans le champ apparu, saisissez https://shop.example.com.

8. Cliquez sur le bouton Ajouter.

9. Dans le champ qui vient d'apparaître, saisissez https://*.shop.example.com.

   

10. Cliquez sur le bouton Créer en haut à droite de l'écran pour délivrer la clé.

Une fois la délivrance terminée, vous arrivez sur l'écran de détail de la clé. Copiez depuis cet écran la valeur de token secrète, comme l'explique Gérer la valeur secrète délivrée, puis placez-la dans le site de la boutique pour l'utiliser.

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 en lecture seule à associer au Delivery Access Token, ainsi que le rôle de lecture et d'écriture à associer au Space 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.
• Space Access Token : traite des spécifications techniques, comme le format des requêtes, nécessaires pour délivrer un Space Access Token depuis un programme ou pour lire et écrire du contenu avec cette clé.
• Delivery Access Token : traite des spécifications techniques, comme les règles d'écriture exactes des adresses inscrites dans les Referrers autorisés et le format des requêtes nécessaires pour manipuler cette clé depuis un programme.
• Référence API : traite des spécifications techniques, comme le format des requêtes, nécessaires pour délivrer d'autres tokens ou manipuler du contenu directement depuis un programme.