Parcours · administrateur de la plateforme
Donner à un intégrateur son compte, un rôle aux scopes choisis, une clé API rangée dans Vault, et la documentation des actions qu'il va appeler.
Thomas Robin ([email protected]) écrit une intégration qui appellera le Hub
d'Exemplia par programme. Il lui faut un compte à lui, des droits limités à son besoin, une clé
API, et l'endroit où lire le nom exact de chaque action. Il vous faut un compte SUPERADMIN du Hub.
Rejouer tout le parcours dans le Hub
Une clé API n'a pas de droits à elle : elle emprunte ceux du compte qui la possède, avec son tenant. On ne crée donc pas la clé de Thomas sur le compte d'un administrateur : on lui ouvre son propre compte, qui ne portera que les rôles utiles à son intégration.
Remplissez le prénom, le nom, l'adresse et un mot de passe initial, transmis à Thomas par un
canal sûr ; le Hub n'en garde que l'empreinte. Le champ Tenant ID reçoit exemplia.
Créer l'utilisateur : le compte est actif tout de suite.
⚠ Sur le Hub 3.77.0, les cases de rôles du formulaire sont ignorées à la création : le compte naît sans rôle. Le rôle se donne depuis sa fiche, deux étapes plus loin.
Action du Hub : iam_worker.create_user
Faire cette étape dans le Hub → Pour aller plus loin : iam.users.creer.ouvrir iam.users.creer.tenant_id iam.users.creer.roles iam.users.creer.valider
Les droits du Hub se règlent en deux étages. Un scope est une permission élémentaire
(read:apps, admin:dns…) ; un rôle est un paquet de scopes, donné aux comptes. Un scope
ne se donne jamais directement à une personne.
Créez un rôle integrateur, avec une description d'une ligne. Il naît vide : dépliez
ensuite sa ligne et ajoutez-lui les scopes dont l'intégration a besoin, par exemple read:apps
(« View applications »). Un rôle sans scope ne donne aucun droit.
Les scopes se lisent dans IAM › Scopes. Un scope manquant se déclare là, et seulement là :
iam_worker n'a pas d'action pour en créer, un agent ne peut donc pas le faire par MCP.
⚠ Les majuscules comptent : integrateur et INTEGRATEUR sont deux rôles. Et ajouter un
scope à un rôle le donne aussitôt à tous ses titulaires.
Action du Hub : iam_worker.create_role
Faire cette étape dans le Hub → Pour aller plus loin : iam.roles.ecran iam.roles.creer.name iam.roles.creer.valider iam.roles.scopes.ajouter iam.scopes.ecran
Ouvrez la fiche de Thomas depuis la liste des utilisateurs. Assigner un rôle lui donne
integrateur ; ses scopes s'ajoutent aussitôt aux scopes effectifs du compte, affichés
plus bas en lecture seule. Assigner un rôle déjà détenu ne change rien.
L'écran montré ici est la fiche d'un autre compte, celui de Claire Martin : celle de Thomas est la même page, avec un seul rôle.
Action du Hub : iam_worker.assign_role
Faire cette étape dans le Hub → Pour aller plus loin : iam.user.roles.choix iam.user.roles.assigner iam.user.scopes.titre
La clé permet au programme de Thomas d'appeler le Hub sans mot de passe. Elle s'envoie dans
l'en-tête X-Api-Key, et le Hub agit alors au nom du compte de Thomas, avec son tenant
et ses droits.
Choisissez le compte de Thomas dans Utilisateur, donnez à la clé un nom qui dit où elle sera posée (« Essais de Thomas Robin ») : c'est ce nom qui permettra de la retrouver pour la révoquer. Une durée courte, ici 90 jours, limite les dégâts d'une clé oubliée dans un fichier.
Créer la clé : le Hub revient sur cet écran avec un bandeau vert qui montre la clé une seule fois, avec un bouton Copier. Il n'en garde que l'empreinte SHA-256 : partez de la page sans l'avoir copiée, et elle est perdue. Il faut alors la révoquer et en créer une autre.
Thomas peut aussi créer ses propres clés, sans vous : action iam_worker.create_my_api_key,
dix clés actives au plus par défaut.
⚠ La clé ne reçoit pas de scopes propres : sur la porte /api/*, elle a les droits de son
compte. ⚠ Verrouiller le compte ne coupe pas ses clés : révoquez-les. ⚠ Une clé expirée reste
affichée « Active » : comparez avec la colonne Expire le.
Action du Hub : iam_worker.create_api_key
Faire cette étape dans le Hub → Pour aller plus loin : iam.apikeys.ecran iam.apikeys.creer.user iam.apikeys.creer.expiration iam.apikeys.creer.valider iam.apikeys.col.statut iam.apikeys.ligne.revoquer
Une clé collée dans un fichier de configuration ou dans un dépôt finit par fuir. Le Hub confie
ses mots de passe, jetons et clés à Vault, un coffre dédié ; les applications du Hub y
lisent leurs secrets au démarrage, sous apps/<application>/….
L'écran ne sait pas écrire : le secret se pose par l'action vault_worker.set_secret, avec
un chemin (path), un nom de champ (key) et la valeur (value). Elle complète le secret sans
effacer ses autres champs.
L'écran sert ensuite à vérifier. Voir affiche les noms des champs d'un secret, avec
des points à la place des valeurs : vous constatez que le champ attendu est là, sans rien
divulguer. Le bouton entouré ouvre le secret apps/things/database de l'application Things.
⚠ Sur le Hub 3.77.0, cet écran est cassé : la fonction qui ouvre un secret
(secretLeaf()) est déclarée hors du contenu de la page, que le gabarit ne transmet pas au
navigateur. Voir et Révéler ne font donc rien, et le démonstrateur reproduit fidèlement
cette panne. En attendant le correctif, la vérification se fait par l'action
vault_worker.get_secret_keys, qui rend les noms des champs.
⚠ Révéler affiche les valeurs en clair, et l'écrit dans le journal du Hub à votre nom. Sur le Hub 3.77.0, un seul « Révéler » dévoile tous les champs du secret, et aucun droit propre ne le protège : tout SUPERADMIN qui ouvre l'écran peut révéler. Dans ce démonstrateur, aucune valeur n'est affichée.
Action du Hub : vault_worker.set_secret
Faire cette étape dans le Hub → Pour aller plus loin : vault.secrets.ecran vault.secrets.explorateur vault.secrets.voir vault.secrets.reveler
Le Hub publie la description de son API au format OpenAPI. Swagger UI l'affiche : chaque
route, ses paramètres, ses réponses. On y trouve en particulier les routes
/api/actions/<worker>/<action>, une par action de worker : la porte REST de tout ce que
font les écrans. C'est là que le programme de Thomas enverra sa clé, en X-Api-Key.
OpenAPI JSON ouvre la description brute, /v3/api-docs. Thomas la donne à un générateur
de client (OpenAPI Generator, Postman, Insomnia) pour obtenir un client typé. Elle suit les
workers déployés.
Pour les essais « Try it out », la page pose un jeton à votre nom, avec les scopes de vos rôles, valable 15 minutes : rechargez la page pour en avoir un neuf.
⚠ Les essais sont réels : un « Try it out » sur une action d'écriture modifie le Hub. ⚠ Le badge « Authentifie » s'affiche même si le jeton n'a pas pu être fabriqué. Dans ce démonstrateur, la zone Swagger reste vide : le vrai Hub la charge en direct.
Faire cette étape dans le Hub → Pour aller plus loin : swagger.ecran swagger.openapi_json swagger.authentifie swagger.zone
Pour un appel MCP, Thomas a besoin du nom exact de l'action et de ses paramètres. MCPagger les
rassemble, application par application. soclehub est le Hub lui-même : toujours disponible.
Cliquez sur une application : ses workers s'affichent, et pour chacun ses actions, leur mode
(SYNC, ASYNC), le repère READ-ONLY des actions sans effet, et le tableau de leurs
paramètres, où un astérisque rouge marque un paramètre obligatoire. Côté MCP, une action
s'appelle <worker>__<action>, avec deux soulignés : iam_worker__list_users.
Tester ouvre un essai prérempli. ⚠ L'essai part toujours vers le Hub, sur
/api/actions : il n'aboutit que pour les actions de soclehub, et il y est réel. Pour
essayer l'action d'une autre application, Thomas passe par le POST /mcp de cette application.
Action du Hub : mcpagger_aggregator_worker.list_all_specs
Faire cette étape dans le Hub → Pour aller plus loin : mcpagger.ecran mcpagger.application mcpagger.parametres.col mcpagger.action.tester
exemplia, avec le seul rôle integrateur ;Thomas appelle /api/actions/<worker>/<action> avec sa clé en X-Api-Key. Le Hub agit en son
nom, dans les limites des scopes du rôle integrateur.