Un compte de service permet à votre propre agent, script ou pipeline d’utiliser 50heads sans appartenir à une personne. Il appartient à votre organisation : il continue de fonctionner quand la personne qui l’a créé quitte l’entreprise, même quand votre fournisseur d’identité la retire.

Chaque compte de service a son propre identifiant client et son secret, travaille dans une de vos équipes, ne fait que ce que ses permissions autorisent et ne dépense que dans ses plafonds. Ses questions appartiennent à cette équipe et utilisent les crédits de l’équipe.

Nous déployons les comptes de service progressivement. Si vous ne voyez pas Comptes de service dans Réglages, puis Organisation, ils ne sont pas encore activés pour votre organisation. Contactez-nous si vous les voulez.

Qui peut les créer et les modifier

Les propriétaires et les admins d’une des équipes de l’organisation, connectés sur le site. Créer, modifier, désactiver et supprimer un compte de service demandent de confirmer à nouveau que c’est bien vous. Choisissez Confirmer que c’est vous quand on vous le demande. La confirmation vaut 10 minutes.

Un compte de service ne peut jamais se créer, se modifier ou s’élargir lui-même, ni en modifier un autre. Une clé d’API ou une application connectée non plus.

Créer un compte de service

  1. Allez dans Réglages, puis Organisation, et choisissez Gérer les comptes de service.
  2. Sous Nouveau compte de service, donnez-lui un nom qui dit à quoi il sert, par exemple « Agent de recherche nocturne ».
  3. Choisissez l’équipe où il travaille, si votre organisation en a plusieurs.
  4. Cochez ce qu’il peut faire. Ne lui donnez que ce dont il a besoin.
  5. Fixez une limite quotidienne et, si vous voulez, une limite par question, en crédits.
  6. Choisissez comment il se connecte : un secret client ou une clé privée (voir plus bas).
  7. Choisissez Créer le compte de service.

Le secret client est affiché une seule fois, avec l’identifiant client et l’adresse des jetons. Copiez-les tout de suite dans les réglages de votre agent. Nous ne gardons qu’une empreinte du secret : nous ne pouvons pas le montrer à nouveau. S’il est perdu, créez-en un nouveau.

Ce qu’il peut faire

Un compte de service peut avoir toutes les permissions d’une clé d’API, listées dans Clés d’API. Dans son équipe, il agit avec le rôle d’admin, limité par ces permissions. Il n’est jamais propriétaire de l’équipe et n’apparaît jamais parmi les membres.

Les permissions d’organisation lui permettent de lire et de gérer l’organisation, dans certaines limites :

Permission Ce qu’elle permet
organization:read Voir l’organisation, ses domaines, ses règles de connexion, l’authentification unique, SCIM et les comptes de service
organization:write Modifier les domaines, les règles de connexion et les réglages SCIM
members:read Voir où un membre est connecté
members:write Déconnecter un membre partout
audit:read Lire et exporter le journal d’audit

Certains actes demandent toujours une personne qui vient de confirmer que c’est bien elle, quelles que soient les permissions : configurer ou modifier la connexion d’authentification unique et l’activer ou la désactiver, la rendre obligatoire, la tester, changer les propriétaires de secours, créer ou remplacer des jetons SCIM, changer la durée de conservation des événements d’audit, placer ou lever une conservation légale, confier une équipe à un nouveau propriétaire, et tout ce qui touche aux comptes de service eux-mêmes.

Plafonds de dépense

Chaque compte de service a une limite quotidienne et peut avoir une limite par question, en crédits. Une demande qui dépasserait l’une ou l’autre est refusée avant toute dépense, exactement comme pour une clé d’API. Chaque demande a besoin d’un Idempotency-Key ; envoyer de nouveau la même clé renvoie la même question et ne facture jamais deux fois.

Comment il se connecte

Votre agent demande un jeton d’accès à l’adresse des jetons, https://auth.50heads.com/token, avec grant_type=client_credentials. Le jeton vaut une heure ; quand il expire, l’agent en redemande un. Il n’y a pas de jeton de rafraîchissement.

Avec un secret client, envoyez l’identifiant client et le secret en authentification HTTP Basic :

curl -s https://auth.50heads.com/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Appelez ensuite l’API avec Authorization: Bearer <access_token>, comme avec une clé d’API. Vous pouvez ajouter scope= pour demander moins de permissions qu’il n’en a, jamais plus.

Avec une clé privée, votre agent signe une courte assertion (private_key_jwt, ES256 ou RS256) au lieu d’envoyer un secret. Ne donnez à 50heads que les clés publiques, sous forme de JSON Web Key Set de 5 clés au plus. Ne collez jamais une clé privée. L’émetteur et le sujet de l’assertion sont l’identifiant client, son audience est l’adresse des jetons, elle a au plus cinq minutes et chacune ne sert qu’une fois.

Remplacer un secret

Choisissez Nouveau secret sur le compte de service. L’ancien secret reste valable le temps que vous choisissez (24 heures par défaut, jusqu’à une semaine, ou pas du tout), pour que vous puissiez basculer votre agent. Deux secrets au plus fonctionnent en même temps. Mettre fin à ce secret arrête tout de suite un ancien secret.

Le désactiver ou le supprimer

  • Désactiver arrête ses jetons dès leur prochaine demande, et il n’en reçoit plus de nouveaux. Réactiver le remet en service.
  • Supprimer arrête définitivement ses jetons et ses secrets, et les endpoints de webhook qu’il a créés. Les questions qu’il a posées restent dans l’équipe, et il reste dans le journal d’audit.

Retirer une personne, à la main ou par votre fournisseur d’identité, n’a jamais d’effet sur un compte de service.

Dans le journal d’audit

Chaque changement d’un compte de service est enregistré avec la personne qui l’a fait. Ce qu’un compte de service fait lui-même, par exemple poser une question, ajouter un domaine ou exporter le journal d’audit, est enregistré avec son nom et le type d’auteur service_account. Voir Le journal d’audit.

Voir aussi