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.
Ce que Connect voit et ne voit jamais
Section intitulée « Ce que Connect voit et ne voit jamais »| 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.
Choix par espace de travail
Section intitulée « Choix par espace de travail »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_URLempê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
Identité d’installation
Section intitulée « Identité d’installation »| É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.
Identifiants scellés
Section intitulée « Identifiants scellés »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
Installations GitHub
Section intitulée « Installations GitHub »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
Le bot partagé
Section intitulée « Le bot partagé »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,reviewetcomment(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 dansCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Chaque autre serveur reçoitneeds_requesteret 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
Confiance dans la configuration
Section intitulée « Confiance dans la configuration »| 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 |
Opérations
Section intitulée « Opérations »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é.
Connexion via Connect
Section intitulée « Connexion via Connect »- 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
- La personne approuve dans le navigateur. Le fournisseur revient vers Connect
- 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
- 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 - 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.
Renouveler la clé d’installation
Section intitulée « Renouveler la clé d’installation »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é
Codes d’état
Section intitulée « Codes d’état »| 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 |