Aller au contenu

Référence de Control Center Connect

Control Center Connect exécute les connexions aux fournisseurs pour les serveurs qui n’ont pas enregistré leurs propres applications. Un serveur utilise soit le Connect hébergé de Control Center, soit un Connect qu’exploite son organisation (Exécuter un serveur Connect), soit aucun. Le choix se fait dans Paramètres → Serveur → Authentification unique → Control Center Connect, avec cc_server connect ou avec CC_CONNECT_URL. Un espace de travail suit ce choix, sauf si un administrateur en choisit un autre pour cet espace sous Paramètres → Espace de travail → Intégrations (Choix par espace de travail).

Chaque fournisseur est une voie. Sous Utiliser mes propres applications (ou avant qu’aucun choix ne soit fait), une voie s’exécute avec l’application propre au serveur lorsqu’elle est entièrement configurée, sinon elle est indisponible. Avec Control Center ou un Connect personnalisé, Connect exécute chaque voie qu’il sert : les applications propres du serveur restent enregistrées mais ne sont pas utilisées, ni pour les connexions, ni pour l’automatisation du serveur, ni pour le statut qu’il signale. Un espace de travail qui a fait son propre choix exécute alors chaque voie selon ce choix.

Voie Une application propre requiert Via Connect
github Identifiant d’application, clé privée, identifiant client et secret client Les personnes se connectent à la GitHub App partagée
google Identifiant client et secret client Les personnes connectent Google Calendar
linear Identifiant client Les personnes se connectent à Linear
linear_app Identifiant client Un administrateur de l’espace de travail connecte l’acteur applicatif de Linear
slack La connexion à l’application Slack propre à un espace de travail Un administrateur de l’espace de travail connecte Slack à l’application Slack partagée
klipy KLIPY_APP_KEY La recherche de GIF, relayée par Connect

Une application propre qui n’est que partiellement configurée met sa voie en erreur, jamais en repli silencieux sur Connect. Un espace de travail sur Utiliser mes propres applications ne passe jamais par les applications du serveur ni par un Connect, pour aucun fournisseur. Changer le choix de Connect du serveur ne déconnecte personne d’un espace de travail qui a fait son propre choix.

Connect voit Connect ne voit jamais
L’identifiant d’installation du serveur et les signatures de ses requêtes Le code source, le contenu des dépôts, les diffs ou le texte des pull requests
Le compte du fournisseur qui s’est connecté, pendant la connexion Les tickets, les transcriptions ou quoi que ce soit dans une base de données d’espace de travail
L’espace de travail auquel appartient un identifiant, sous forme d’identifiant opaque dans le scellé Les secrets propres aux applications du serveur : ils ne quittent jamais le serveur
Le dépôt pour lequel un jeton GitHub limité à un dépôt est émis Les jetons d’actualisation au repos : ils n’existent qu’à l’intérieur des scellés que conserve le serveur
L’équipe Slack liée au serveur Les secrets Linear : le serveur échange lui-même le code de Linear
Les termes de recherche de GIF, lorsqu’il relaie Klipy Les mots de passe, les clés d’appairage ou les clés des fournisseurs de modèles
Les références d’événements Slack (équipe, canal, identifiant de message) et le texte des commandes slash Le texte des messages Slack : Connect le supprime à l’arrivée et le serveur lit lui-même le message depuis Slack

Connect garde les connexions en attente, les nonces et les caches pendant au plus 10 minutes, et les compteurs d’usage horaires pendant au plus deux heures. Un jeton GitHub limité à un dépôt émis pour une personne reste enregistré, scellé à la connexion qui l’a demandé, jusqu’à son expiration (au plus 8 heures), afin que Connect puisse le remettre de nouveau et le révoquer à la déconnexion. Ses seuls enregistrements durables sont les liaisons Slack (à quel serveur chaque équipe Slack est liée) et les identifiants d’installation retirés. Les erreurs portent un code, jamais la réponse du fournisseur. Les journaux n’enregistrent les identifiants d’installation que sous forme de hachages à clé, et un jeton GitHub seulement sous la forme hashed_token que présente pour lui le journal d’audit de l’organisation GitHub, afin qu’un propriétaire d’organisation puisse faire correspondre les deux.

Mode Réglage Comportement
Non défini Serveur neuf Aucune voie n’utilise Connect. La configuration initiale demande au propriétaire du serveur de choisir
hosted Utiliser les applications de Control Center https://connect.usectrl.dev, avec une configuration signée hors ligne. Les applications propres du serveur ne sont pas utilisées
custom Utiliser un serveur Connect personnalisé Un Connect à une URL HTTPS (http sur la boucle locale uniquement), approuvé à la première utilisation. Les applications propres du serveur ne sont pas utilisées
off Utiliser mes propres applications Aucune voie n’utilise Connect. Seules les applications propres connectent les personnes

CC_CONNECT_URL dans l’environnement ou le .env du serveur verrouille le choix : hosted, off ou une URL Connect. Paramètres affiche alors le verrou et ne peut pas le modifier.

Cette version ne compile aucune clé de configuration hébergée : le mode hébergé signale donc hosted_unprovisioned et ne sert aucune voie. Les applications propres et un Connect personnalisé fonctionnent.

Le Connect hébergé tourne dans un seul conteneur. Sa clé de scellement et la clé privée de la GitHub App partagée sont des variables d’environnement là-bas, et non des clés dans un coffre qui ne fait que signer ou déchiffrer, comme GitHub le recommande pour la clé privée d’une App. C’est une lacune connue de la configuration actuelle.

Un serveur lit la configuration de Connect au plus toutes les 10 minutes et attend au plus 5 secondes pour chaque appel. Lorsque Connect est injoignable, la dernière configuration valide reste en vigueur et Paramètres la signale comme périmée.

Paramètres → Espace de travail → Intégrations → Control Center Connect remplace le choix du serveur pour un seul espace de travail. Chaque membre le voit, ainsi que l’endroit où passe chaque connexion ; seul un administrateur de l’espace de travail le modifie.

Choix Comportement
Comme ce serveur Le choix par défaut. L’espace de travail suit ce que le propriétaire du serveur a choisi ; l’option le nomme
Utiliser les applications de Control Center Le Connect hébergé de Control Center, quel que soit celui qu’utilise le serveur
Utiliser mes propres applications Seules les applications propres de l’espace de travail : sa GitHub App, son client Google, son application Linear, sa clé Klipy et son application Slack. Un fournisseur qui n’en a pas est désactivé ici ; une application partiellement configurée est une erreur de configuration
Utiliser un serveur Connect personnalisé Un Connect à une adresse HTTPS que nomme l’espace de travail. Les adresses sur un réseau privé ou local sont refusées
  • Tout choix autre que Comme ce serveur garde les connexions GitHub et Linear de chaque personne dans un emplacement propre à l’espace de travail, afin qu’elles ne se mélangent jamais avec celles de l’ensemble du serveur
  • Le changement demande d’abord confirmation : tout le monde dans l’espace de travail doit se reconnecter à GitHub, Linear et Google Calendar par les nouvelles applications
  • La connexion Slack propre à un espace de travail fonctionne avec tous les choix ; Ajouter Control Center à Slack suit le choix
  • CC_CONNECT_URL empêche aussi un espace de travail d’avoir son propre Connect : il peut suivre le serveur ou utiliser ses propres applications
  • Le Connect personnalisé d’un espace de travail n’est approuvé à la première utilisation que pour cet espace : Faire confiance aux nouvelles applications là-bas ne modifie jamais ce que le serveur ou un autre espace de travail approuve
Élément Ce que c’est
Clé d’installation Une graine de 32 octets dans le fichier de secrets du serveur (connect_install_key), distincte des clés d’appairage des appareils
Clé par Connect Une clé Ed25519 dérivée de la graine et de l’adresse du Connect. Chaque requête adressée à Connect est signée avec elle (RFC 9421)
Identifiant d’installation 26 caractères dérivés de cette clé publique. Affiché dans Paramètres et par cc_server connect status

Le même serveur a un identifiant d’installation différent pour chaque adresse Connect. L’identifiant ne change que lorsque la clé est renouvelée.

Une connexion via Connect renvoie un scellé d’identifiant : un objet chiffré que seul le Connect qui l’a créé peut ouvrir. Il est lié au fournisseur, à l’adresse de Connect, à l’identifiant d’installation, à l’espace de travail, au compte du fournisseur, à l’application et à la génération du secret.

  • Le serveur stocke le scellé et l’identifiant d’installation pour lequel il a été scellé. Les jetons d’accès restent en mémoire
  • Pour actualiser, le serveur renvoie le scellé et reçoit un nouveau jeton d’accès et un nouveau scellé
  • Un scellé dont l’identifiant d’installation ou l’adresse de Connect ne correspond plus est supprimé à sa prochaine lecture, et la personne concernée se reconnecte. Cela se produit après un renouvellement de clé, un passage à un autre Connect, ou un répertoire de données restauré sur un autre serveur
  • Un scellé que Connect ne peut pas ouvrir est refusé avec access_denied

Une installation de la GitHub App partagée est utilisable depuis tout serveur. Connect ne tient aucun registre des serveurs autorisés à l’utiliser.

  • Installer l’application GitHub dans Paramètres → Espace de travail → Intégrations ouvre la page d’installation de l’application sur GitHub. Le serveur construit le lien à partir du nom de l’application dans la configuration de Connect
  • Un jeton limité à un dépôt exige que l’application soit installée sur le compte propriétaire du dépôt et que la personne connectée ait accès à ce dépôt. C’est le jeton propre de cette personne, borné à son rôle, jamais davantage
  • Une organisation limite Control Center sur GitHub : en retirant l’installation, en réduisant ses dépôts ou en retirant la personne
  • Pour les appels que seule la personne peut faire, comme la liste de ses installations, Connect remet au serveur le jeton d’utilisateur de la GitHub App propre à la personne, et non un jeton limité à un dépôt. Se connecter sur un serveur revient à lui faire confiance avec ce jeton
  • Une organisation qui impose une liste d’autorisation d’adresses IP à GitHub ne peut pas utiliser le Connect hébergé, dont les adresses ne sont pas fixes. Elle enregistre alors sa propre GitHub App, sur ses serveurs ou sur un Connect qu’elle exploite
  • Déconnecter ne révoque que cette connexion : Connect dépense son jeton d’actualisation une seule fois et supprime ce que cela renvoie, supprime son jeton d’utilisateur ainsi que les jetons limités à un dépôt que Connect a émis pour elle. Une copie de son scellé conservée quelque part cesse de fonctionner. Les connexions de la personne sur d’autres serveurs et espaces de travail continuent de fonctionner. Pour retirer entièrement Control Center d’un compte GitHub, révoquez-le dans GitHub sous Paramètres → Applications → Applications GitHub autorisées → Révoquer

Les jetons émis en tant que bot de l’App (as: app) présentent le même bot sur GitHub pour chaque serveur qui utilise le même Connect : GitHub ne peut pas distinguer ces serveurs.

  • Chaque serveur peut faire lire et commenter le bot : read, review et comment (commentaires, étiquettes, assignés et réactions sur les tickets et les pull requests)
  • Une revue de pull request en tant que bot (bot, qui écrit des pull requests) n’est permise que pour les serveurs que l’opérateur de Connect liste dans CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Chaque autre serveur reçoit needs_requester et publie la revue avec le jeton propre de la personne responsable, que GitHub borne à cette personne : la revue apparaît à son nom. Cela couvre la publication des revues par IA, les commentaires de revue et les demandes de relecteurs
  • Pousser, créer une branche et ouvrir une pull request (write) ne sont jamais émis en tant que bot partagé. Ils utilisent toujours la connexion propre au demandeur
  • Approuver une pull request n’est jamais automatisé, quel que soit le jeton
  • Un serveur ou un espace de travail disposant de sa propre GitHub App garde le bot pour tout cela, revues comprises

Ce que doivent savoir les propriétaires et membres d’une organisation

Section intitulée « Ce que doivent savoir les propriétaires et membres d’une organisation »
  • Un serveur sur lequel quelqu’un se connecte détient le jeton d’utilisateur de sa GitHub App : jusqu’à 8 heures par jeton, renouvelé jusqu’à ce que la personne se déconnecte. Il peut agir en son nom sur chaque dépôt sur lequel l’App partagée est installée et que la personne peut atteindre. Connect peut couper définitivement un serveur (installation retirée ou refusée), mais un jeton déjà remis reste valide jusqu’à son expiration
  • Installer la GitHub App partagée sur une organisation donne son accord pour chaque serveur Control Center sur lequel un membre se connecte, et non pour un seul serveur
  • Le bot est partagé, comme indiqué plus haut : une organisation ne peut pas savoir sur GitHub quel serveur a agi en tant que bot
  • Une organisation qui veut sa propre frontière enregistre sa propre GitHub App et exploite son propre Connect (Exécuter un serveur Connect), ou configure l’App sur ses propres serveurs
Connect Comment le serveur fait confiance à sa configuration
Hébergé Vérifie une signature Ed25519 par rapport à des clés compilées dans la version. Refuse une époque inférieure à la plus élevée qu’il a vue (rollback)
Personnalisé Épingle à la première utilisation l’identifiant d’application et l’identifiant client GitHub, les identifiants client Google et Linear, et les identifiants d’application et de client Slack. Un changement suspend les connexions via Connect (pins_changed) jusqu’à ce que le propriétaire du serveur appuie sur Faire confiance aux nouvelles applications

Les réglages Connect du serveur sont réservés au propriétaire du serveur.

Opération Effet
connect.status Mode, URL, verrou, identifiant d’installation, état de santé, époque de configuration et source de chaque voie
connect.configure Définit hosted, custom (avec url) ou off
connect.test Récupère de nouveau la configuration et indique l’état de santé
connect.confirmPins Accepte les identifiants modifiés d’un Connect personnalisé
connect.rotateKey Émet une nouvelle clé d’installation et un nouvel identifiant d’installation (force le remplace même lorsqu’un Connect n’a pas pu retirer l’ancien), voir Renouveler la clé d’installation

Le choix propre à un espace de travail a ses propres opérations, chacune nommant l’espace de travail :

Opération Qui Effet
workspaceConnect.status Tout membre Le choix, ce qu’il donne, l’état de santé et la source de chaque voie. L’identifiant d’installation et les épinglages en attente sont réservés aux administrateurs
workspaceConnect.set Administrateur de l’espace de travail Définit inherit, hosted, custom (avec url) ou own
workspaceConnect.test Administrateur de l’espace de travail Récupère de nouveau la configuration Connect de l’espace de travail et indique l’état de santé
workspaceConnect.confirmPins Administrateur de l’espace de travail Accepte les identifiants modifiés du Connect personnalisé de l’espace de travail

Les connexions elles-mêmes utilisent oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections et oauth.disconnect. La personne est toujours l’appelant connecté.

  1. Le serveur demande à Connect de démarrer la voie et reçoit l’URL d’autorisation du fournisseur, qu’il vérifie avant de l’afficher. GitHub affiche toujours son sélecteur de compte
  2. La personne approuve dans le navigateur. Le fournisseur revient vers Connect
  3. Connect affiche ce que le serveur qui a lancé la connexion pourra faire au nom de la personne, et pendant combien de temps. Connect ne peut pas savoir qui exploite ce serveur ; la page ne demande donc de continuer que si la personne a lancé la connexion elle-même, et de la fermer si quelqu’un lui a envoyé le lien. Lorsque le navigateur se trouve sur un autre réseau que celui d’où la connexion a été lancée, la page le dit : c’est normal pour un serveur hébergé ou un autre appareil, et c’est aussi ce que ressemble un hameçonnage. Annuler met fin à la connexion : le code du fournisseur n’est jamais utilisé. Chaque page ne répond qu’une fois ; une réponse qui ne vient pas de la page que Connect vient d’afficher est refusée
  4. Après Continuer, Connect affiche un code de 8 caractères et un lien control-center://oauth-done. Quiconque reçoit le code obtient l’accès qui vient d’être approuvé, il ne doit donc aller que là où la connexion a été lancée
  5. La personne saisit le code dans l’application, ou suit le lien. Le serveur récupère la connexion avec le code et sa propre preuve de la requête

Une connexion expire au bout de 10 minutes. Cinq codes erronés y mettent fin. Un lien que cette application n’a pas lancé est refusé avec Connexion non lancée d’ici. Connect limite le nombre de connexions qu’une même adresse réseau peut lancer, et la fréquence à laquelle les jetons GitHub sont émis par personne et par serveur, par personne sur l’ensemble des serveurs, par adresse et pour toute l’application. Les nouvelles connexions ont leur propre budget, si bien qu’elles ne retardent jamais les renouvellements dont d’autres ont besoin. Au-delà d’une limite, un appel est refusé avec rate_limited, et le serveur réessaie plus tard sans déconnecter personne. Une connexion au-delà de la limite de la personne est annulée chez GitHub et refusée.

Seul le propriétaire du serveur peut renouveler la clé, avec Renouveler la clé sur la carte Control Center Connect dans Paramètres → Serveur → Authentification unique. Il n’existe aucune commande pour cela. Lors du renouvellement :

  • Déconnecte tout le monde de chaque voie qui passe par Connect. Pour chaque serveur Connect avec lequel l’ancienne clé a servi, le serveur révoque les connexions GitHub et Slack qu’il y détient (une connexion Google n’a rien à révoquer et expire)
  • Retire l’ancien identifiant d’installation auprès de chacun de ces serveurs Connect, signé avec l’ancienne clé et prouvé par un scellé d’identifiant que le serveur détient auprès de ce Connect. Dès lors, Connect refuse chaque requête faite avec l’ancienne clé : un scellé, ou une copie de l’ancienne clé prise sur ce serveur, ne sert plus à rien, et les espaces de travail Slack liés à l’ancien identifiant sont libérés pour pouvoir se reconnecter. Les jetons déjà remis restent valides jusqu’à leur expiration (une heure pour un jeton de bot, huit heures pour celui d’une personne). Un serveur Connect dont ce serveur ne détient aucun scellé n’a rien à retirer et est ignoré
  • Donne ensuite au serveur une nouvelle clé d’installation et un nouvel identifiant d’installation
  • Si un serveur Connect est injoignable, ou refuse de retirer l’ancien identifiant, s’arrête avant de changer de clé et affiche Connect n’a pas pu retirer l’ancienne clé. Renouveler quand même change de clé malgré tout ; l’ancien identifiant d’installation reste alors utilisable auprès de ce Connect jusqu’à l’expiration de ses jetons, au plus 8 heures pour GitHub
  • Laisse intactes les connexions via les applications propres au serveur
  • Exige d’ajouter le nouvel identifiant d’installation à la liste d’autorisation d’un Connect personnalisé
Code Signification
hosted_unprovisioned Cette version n’a aucune clé de configuration hébergée
signature La configuration hébergée a échoué à la vérification de sa signature
rollback Connect a servi une configuration plus ancienne que celle déjà vue par le serveur
unreachable Le serveur ne peut pas joindre Connect
install_blocked Connect n’autorise pas cet identifiant d’installation, ou il a été retiré
pins_changed Un Connect personnalisé a annoncé d’autres identifiants d’application
protocol Connect a répondu sous une forme que ce serveur ne comprend pas