Referenz zu Control Center Connect
Control Center Connect führt Anbieter-Anmeldungen für Server aus, die keine
eigenen Apps registriert haben. Ein Server nutzt entweder das gehostete Connect
von Control Center, ein Connect, das seine Organisation betreibt
(Einen Connect-Server betreiben),
oder keines. Die Wahl liegt unter Einstellungen → Server → Single sign-on →
Control Center Connect, bei cc_server connect oder in CC_CONNECT_URL. Ein Arbeitsbereich folgt ihr, außer ein Administrator wählt für ihn unter Einstellungen → Arbeitsbereich → Integrationen etwas anderes (Die Wahl je Arbeitsbereich).
Jeder Anbieter ist eine Spur. Unter Eigene Apps verwenden (oder bevor jemand eine Wahl trifft) läuft eine Spur über die eigene App des Servers, wenn sie vollständig konfiguriert ist, sonst ist sie nicht verfügbar. Mit Apps von Control Center oder einem eigenen Connect-Server läuft Connect jede Spur, die es bedient: Die eigenen Apps des Servers bleiben gespeichert, werden aber weder für Anmeldungen, Automatisierung auf dem Server noch für den Status genutzt, den der Server meldet. Ein Arbeitsbereich mit eigener Wahl führt jede Spur nach dieser Wahl aus.
| Spur | Eigene App braucht | Über Connect |
|---|---|---|
github |
App-ID, privaten Schlüssel, Client-ID und Client-Secret | Personen melden sich bei der gemeinsamen GitHub App an |
google |
Client-ID und Client-Secret | Personen verbinden Google Calendar |
linear |
Client-ID | Personen melden sich bei Linear an |
linear_app |
Client-ID | Ein Administrator des Arbeitsbereichs verbindet den App-Akteur von Linear |
slack |
Die Verbindung eines Arbeitsbereichs zu seiner eigenen Slack-App | Ein Administrator des Arbeitsbereichs verbindet Slack mit der gemeinsamen Slack-App |
klipy |
KLIPY_APP_KEY |
GIF-Suche, über Connect weitergeleitet |
Eine eigene App, die nur teilweise konfiguriert ist, macht ihre Spur zu einem Fehler, nie zu einem stillen Rückfall auf Connect. Ein Arbeitsbereich mit Eigene Apps verwenden geht nie über die Apps des Servers oder über irgendeinen Connect, für keinen Anbieter. Ein Wechsel der Connect-Wahl des Servers meldet niemanden aus einem Arbeitsbereich ab, der seine eigene Wahl getroffen hat.
Was Connect sieht und nie sieht
Abschnitt betitelt „Was Connect sieht und nie sieht“| Connect sieht | Connect sieht nie |
|---|---|
| Die Installations-ID des Servers und die Signaturen der Anfragen | Quellcode, Repository-Inhalte, Diffs oder Text von Pull Requests |
| Das Anbieterkonto, das sich anmeldet, während der Anmeldung | Tickets, Transkripte oder irgendetwas in einer Datenbank eines Arbeitsbereichs |
| Zu welchem Arbeitsbereich ein Zugangsdatum gehört, als opake ID im Siegel | Die eigenen App-Geheimnisse des Servers: Sie verlassen den Server nie |
| Das Repository, für das ein GitHub-Token für ein einzelnes Repository ausgestellt wird | Gespeicherte Refresh-Tokens: Sie existieren nur in Siegeln, die der Server aufbewahrt |
| Das Slack-Team, das an den Server gebunden ist | Linear-Secrets: Der Server tauscht den Code von Linear selbst aus |
| Suchbegriffe für GIFs, wenn es Klipy weiterleitet | Passwörter, Kopplungsschlüssel oder Schlüssel von Modellanbietern |
| Verweise auf Slack-Ereignisse (Team, Kanal, Nachrichten-ID) und den Text von Slash-Befehlen | Den Text von Slack-Nachrichten: Connect verwirft ihn beim Eintreffen, und der Server liest die Nachricht selbst bei Slack |
Connect hält vorbereitete Anmeldungen, Nonces und Caches höchstens 10 Minuten
und stündliche Nutzungszähler höchstens zwei Stunden. Ein GitHub-Token für ein
einzelnes Repository, das als Person ausgestellt wurde, bleibt, an die Anmeldung
gesiegelt, die es angefordert hat, bis es abläuft (höchstens 8 Stunden), damit
Connect es erneut ausgeben und beim Trennen widerrufen kann. Seine einzigen
dauerhaften Einträge sind Slack-Bindungen (an welchen Server jedes Slack-Team
gebunden ist) und zurückgezogene Installations-IDs. Fehler tragen einen Code,
nie die Antwort des Anbieters. Logs halten Installations-IDs nur als
schlüsselbasierte Hashes fest, und ein GitHub-Token nur als den hashed_token,
den das Audit-Protokoll der GitHub-Organisation dafür zeigt, damit ein
Organisationsinhaber beides zuordnen kann.
| Modus | Einstellung | Verhalten |
|---|---|---|
| Nicht gesetzt | Neuer Server | Keine Spur nutzt Connect. Das Onboarding bittet den Server-Eigentümer um eine Wahl |
hosted |
Apps von Control Center verwenden | https://connect.usectrl.dev, mit einer offline signierten Konfiguration. Die eigenen Apps des Servers werden nicht genutzt |
custom |
Eigenen Connect-Server verwenden | Ein Connect unter einer HTTPS-URL (http nur auf Loopback), beim ersten Gebrauch vertraut. Die eigenen Apps des Servers werden nicht genutzt |
off |
Eigene Apps verwenden | Keine Spur nutzt Connect. Nur eigene Apps melden Personen an |
CC_CONNECT_URL in der Umgebung oder der .env des Servers legt die Wahl fest:
hosted, off oder eine Connect-URL. Die Einstellungen zeigen die Sperre dann
an und können sie nicht ändern.
In diesen Build ist kein Schlüssel für die gehostete Konfiguration einkompiliert,
deshalb meldet der gehostete Modus hosted_unprovisioned und bedient keine Spur.
Eigene Apps und ein eigenes Connect funktionieren.
Das gehostete Connect läuft in einem einzelnen Container. Sein Siegelschlüssel und der private Schlüssel der gemeinsamen GitHub App sind dort Umgebungsvariablen, keine Schlüssel in einem Tresor, der nur signiert oder entschlüsselt, wie GitHub es für den privaten Schlüssel einer App empfiehlt. Das ist eine bekannte Lücke der aktuellen Einrichtung.
Ein Server liest die Konfiguration von Connect höchstens alle 10 Minuten und wartet auf jeden Aufruf höchstens 5 Sekunden. Ist Connect nicht erreichbar, bleibt die letzte gültige Konfiguration in Gebrauch, und die Einstellungen markieren sie als veraltet.
Die Wahl je Arbeitsbereich
Abschnitt betitelt „Die Wahl je Arbeitsbereich“Einstellungen → Arbeitsbereich → Integrationen → Control Center Connect überschreibt die Wahl des Servers für einen Arbeitsbereich. Jedes Mitglied sieht die Wahl und wo jede Anmeldung läuft; nur ein Administrator des Arbeitsbereichs ändert sie.
| Wahl | Verhalten |
|---|---|
| Wie auf diesem Server | Der Standard. Der Arbeitsbereich läuft mit dem, was der Server-Eigentümer gewählt hat; die Option nennt es |
| Apps von Control Center verwenden | Connect von Control Center, egal was der Server nutzt |
| Eigene Apps verwenden | Nur die eigenen Apps des Arbeitsbereichs: seine GitHub App, sein Google-Client, seine Linear-Anwendung, sein Klipy-Schlüssel und seine Slack-App. Ein Anbieter ohne eigene App ist hier aus, eine teilweise App ist ein Setup-Fehler |
| Eigenen Connect-Server verwenden | Ein Connect unter einer HTTPS-Adresse, die der Arbeitsbereich angibt. Adressen in einem privaten oder lokalen Netz werden abgelehnt |
- Jede Wahl außer Wie auf diesem Server hält die GitHub- und Linear-Anmeldungen jeder Person in einem eigenen Bereich des Arbeitsbereichs, damit sie sich nicht mit den serverweiten mischen
- Ein Wechsel fragt vorher nach: Alle im Arbeitsbereich melden sich bei GitHub, Linear und Google Calendar erneut über die neuen Apps an
- Die eigene Slack-App-Verbindung eines Arbeitsbereichs funktioniert unter jeder Wahl; Control Center zu Slack hinzufügen folgt der Wahl
CC_CONNECT_URLsperrt Arbeitsbereiche ebenfalls von einem eigenen Connect aus: Sie können dem Server folgen oder ihre eigenen Apps nutzen- Ein eigener Connect-Server eines Arbeitsbereichs wird nur für diesen Arbeitsbereich beim ersten Gebrauch als vertrauenswürdig eingestuft: Neuen Apps vertrauen ändert dort nie, was der Server oder ein anderer Arbeitsbereich vertraut
Installationsidentität
Abschnitt betitelt „Installationsidentität“| Element | Was es ist |
|---|---|
| Installationsschlüssel | Ein 32-Byte-Seed in der Geheimnisdatei des Servers (connect_install_key), getrennt von den Kopplungsschlüsseln der Geräte |
| Schlüssel je Connect | Ein Ed25519-Schlüssel, abgeleitet aus dem Seed und der Adresse des Connect. Jede Anfrage an Connect wird damit signiert (RFC 9421) |
| Installations-ID | 26 Zeichen, abgeleitet aus diesem öffentlichen Schlüssel. Angezeigt in den Einstellungen und von cc_server connect status |
Derselbe Server hat für jede Connect-Adresse eine andere Installations-ID. Die ID ändert sich nur, wenn der Schlüssel rotiert wird.
Versiegelte Zugangsdaten
Abschnitt betitelt „Versiegelte Zugangsdaten“Eine Anmeldung über Connect gibt ein Zugangsdaten-Siegel zurück: einen verschlüsselten Blob, den nur das Connect öffnen kann, das ihn erzeugt hat. Er ist an den Anbieter, die Connect-Adresse, die Installations-ID, den Arbeitsbereich, das Anbieterkonto, die App und die Secret-Generation gebunden.
- Der Server speichert das Siegel und die Installations-ID, für die es versiegelt wurde. Access-Tokens bleiben im Arbeitsspeicher
- Zum Erneuern schickt der Server das Siegel zurück und erhält ein neues Access-Token und ein neues Siegel
- Ein Siegel, dessen Installations-ID oder Connect-Adresse nicht mehr passt, wird beim nächsten Lesen gelöscht, und diese Person meldet sich erneut an. Das passiert nach einer Schlüsselrotation, einem Wechsel zu einem anderen Connect oder einem Datenverzeichnis, das auf einem anderen Server wiederhergestellt wurde
- Ein Siegel, das Connect nicht öffnen kann, wird mit
access_deniedabgelehnt
GitHub-Installationen
Abschnitt betitelt „GitHub-Installationen“Eine Installation der gemeinsamen GitHub App ist von jedem Server aus nutzbar. Connect führt keinen Eintrag darüber, welcher Server sie nutzen darf.
- GitHub-App installieren unter Einstellungen → Arbeitsbereich → Integrationen öffnet die Installationsseite der App auf GitHub. Der Server baut den Link aus dem App-Namen in der Konfiguration von Connect
- Ein Token für ein einzelnes Repository braucht die App auf dem Konto, dem das Repository gehört, und den Zugriff der angemeldeten Person auf dieses Repository. Es ist das eigene Token dieser Person, auf ihre Rolle begrenzt, nie mehr
- Eine Organisation begrenzt Control Center auf GitHub: durch Entfernen der Installation, Verengen ihrer Repositories oder Entfernen der Person
- Für Aufrufe, die nur die Person selbst machen kann, etwa das Auflisten ihrer Installationen, gibt Connect dem Server das eigene App-Benutzertoken der Person aus, nicht ein Token für ein einzelnes Repository. Sich auf einem Server anzumelden heißt, diesem Server dieses Token anzuvertrauen.
- Eine Organisation, die eine GitHub-IP-Allowlist erzwingt, kann das gehostete Connect nicht nutzen, dessen Adressen nicht fest sind. Sie registriert stattdessen eine eigene GitHub App, auf ihren Servern oder auf einem Connect, das sie betreibt.
- Trennen widerruft nur diese Anmeldung: Connect verbraucht sein Refresh-Token einmal und löscht, was dabei zurückkommt, löscht sein Benutzertoken und die Tokens für einzelne Repositorys, die Connect dafür ausgestellt hat. Eine Kopie seines Siegels, wo auch immer sie liegt, funktioniert nicht mehr. Die Anmeldungen der Person auf anderen Servern und in anderen Arbeitsbereichen funktionieren weiter. Um Control Center ganz von einem GitHub-Konto zu entfernen, widerrufe es in GitHub unter Einstellungen → Anwendungen → Autorisierte GitHub Apps → Widerrufen.
Der geteilte Bot
Abschnitt betitelt „Der geteilte Bot“Tokens, die als Bot der App (as: app) ausgestellt werden, zeigen auf GitHub für jeden Server, der dasselbe Connect nutzt, denselben Bot: GitHub kann diese Server nicht unterscheiden.
- Jeder Server darf den Bot lesen und kommentieren lassen:
read,reviewundcomment(Kommentare, Labels, Zuweisungen und Reaktionen an Issues und Pull Requests) - Einen Pull Request als Bot zu reviewen (
bot, was Pull Requests schreibt) ist nur für Server erlaubt, die der Connect-Betreiber inCONNECT_GITHUB_REVIEW_BOT_INSTALLSauflistet. Jeder andere Server bekommtneeds_requesterals Antwort und veröffentlicht das Review über das eigene Token der verantwortlichen Person, das GitHub auf diese Person begrenzt: Das Review erscheint unter ihrem Namen. Das betrifft die Veröffentlichung von KI-Reviews, Review-Kommentare und Reviewer-Anfragen - Pushen, einen Branch anlegen und einen Pull Request öffnen (
write) werden nie als geteilter Bot ausgestellt. Sie nutzen immer die eigene Anmeldung des Anfragenden - Einen Pull Request zu genehmigen ist nie automatisiert, mit keinem Token
- Ein Server oder Arbeitsbereich mit einer eigenen GitHub App behält den Bot für all das, einschließlich der Reviews
Was Organisationsinhaber und Mitglieder wissen sollten
Abschnitt betitelt „Was Organisationsinhaber und Mitglieder wissen sollten“- Ein Server, auf dem sich jemand anmeldet, hält dessen App-Benutzertoken: bis zu 8 Stunden je Token, erneuert, bis die Person sich trennt. Damit kann er als die Person auf jedem Repository handeln, auf dem die geteilte App installiert ist und das die Person erreicht. Connect kann einen Server endgültig abschneiden (eine zurückgezogene oder verweigerte Installation), aber ein bereits ausgegebenes Token bleibt gültig, bis es abläuft
- Die Installation der geteilten GitHub App auf einer Organisation stimmt für jeden Control-Center-Server zu, auf dem sich ein Mitglied anmeldet, nicht nur für einen Server
- Der Bot ist geteilt, wie oben: Eine Organisation kann auf GitHub nicht erkennen, welcher Server als Bot gehandelt hat
- Eine Organisation, die eine eigene Grenze will, registriert eine eigene GitHub App und betreibt ein eigenes Connect (Einen Connect-Server betreiben), oder konfiguriert die App auf ihren eigenen Servern
Vertrauen in die Konfiguration
Abschnitt betitelt „Vertrauen in die Konfiguration“| Connect | Wie der Server seiner Konfiguration vertraut |
|---|---|
| Gehostet | Verifiziert eine Ed25519-Signatur gegen Schlüssel, die in den Build einkompiliert sind. Lehnt eine Epoche ab, die niedriger ist als die höchste bisher gesehene (rollback) |
| Eigenes | Pinnt beim ersten Gebrauch die App-ID und Client-ID von GitHub, die Client-IDs von Google und Linear sowie die App- und Client-IDs von Slack. Eine Änderung pausiert Anmeldungen über Connect (pins_changed), bis der Server-Eigentümer auf Neuen Apps vertrauen klickt |
Operationen
Abschnitt betitelt „Operationen“Die Connect-Einstellungen des Servers sind dem Server-Eigentümer vorbehalten.
| Operation | Wirkung |
|---|---|
connect.status |
Modus, URL, Sperre, Installations-ID, Zustand, Epoche der Konfiguration und die Quelle jeder Spur |
connect.configure |
Setzt hosted, custom (mit url) oder off |
connect.test |
Holt die Konfiguration erneut und meldet den Zustand |
connect.confirmPins |
Akzeptiert die geänderten Kennungen eines eigenen Connect |
connect.rotateKey |
Erzeugt einen neuen Installationsschlüssel und eine neue Installations-ID (force ersetzt sie, auch wenn ein Connect die alte nicht zurückziehen konnte); siehe Den Installationsschlüssel rotieren |
Die eigene Wahl eines Arbeitsbereichs hat eigene Operationen, jede nennt den Arbeitsbereich:
| Operation | Wer | Wirkung |
|---|---|---|
workspaceConnect.status |
Jedes Mitglied | Wahl, Auflösung, Zustand und die Quelle jedes Anbieters. Installations-ID und ausstehende Pins nur für Administratoren |
workspaceConnect.set |
Administrator des Arbeitsbereichs | Setzt inherit, hosted, custom (mit url) oder own |
workspaceConnect.test |
Administrator des Arbeitsbereichs | Holt die Connect-Konfiguration des Arbeitsbereichs erneut und meldet den Zustand |
workspaceConnect.confirmPins |
Administrator des Arbeitsbereichs | Akzeptiert die geänderten Kennungen des eigenen Connect-Servers des Arbeitsbereichs |
Die Anmeldungen selbst nutzen oauth.lanes, oauth.begin, oauth.status,
oauth.complete, oauth.connections und oauth.disconnect. Die Person ist
immer der angemeldete Aufrufer.
Anmeldung über Connect
Abschnitt betitelt „Anmeldung über Connect“- Der Server bittet Connect, die Spur zu starten, und erhält die Autorisierungs-URL des Anbieters, die er prüft, bevor er sie anzeigt. GitHub zeigt immer seine Kontoauswahl
- Die Person bestätigt im Browser. Der Anbieter kehrt zu Connect zurück
- Connect zeigt, was der Server, der die Anmeldung gestartet hat, als die Person tun kann und wie lange. Connect kann nicht erkennen, wer diesen Server betreibt; deshalb bittet die Seite die Person nur dann um Fortsetzung, wenn sie die Anmeldung selbst gestartet hat, und sonst die Seite zu schließen, falls ihr jemand den Link geschickt hat. Liegt der Browser in einem anderen Netz als dem, in dem die Anmeldung gestartet wurde, sagt die Seite das: Bei einem gehosteten Server oder einem anderen Gerät ist das normal, und genau so sieht auch Phishing aus. Abbrechen beendet die Anmeldung: Der Code des Anbieters wird nie verwendet. Jede Seite antwortet einmal; eine Antwort, die nicht von der Seite kam, die Connect gerade gezeigt hat, wird abgelehnt
- Nach Weiter zeigt Connect einen 8-stelligen Code und einen Link
control-center://oauth-done. Wer den Code bekommt, erhält den eben bestätigten Zugriff, daher geht er nur dorthin, wo die Anmeldung gestartet wurde - Die Person tippt den Code in die App ein oder folgt dem Link. Der Server übernimmt die Anmeldung mit dem Code und seinem eigenen Nachweis der Anfrage
Eine Anmeldung läuft nach 10 Minuten ab. Fünf falsche Codes beenden sie. Einen
Link, den diese App nicht gestartet hat, lehnt sie mit Anmeldung nicht hier
gestartet ab. Connect begrenzt, wie viele Anmeldungen eine Netzwerkadresse
starten kann, und wie oft GitHub-Tokens ausgestellt werden: je Person und
Server, je Person über alle Server, je Adresse und für die ganze App. Neue
Anmeldungen haben ein eigenes Budget, damit sie die Erneuerungen anderer
Personen nie aufhalten. Über einem Limit wird ein Aufruf mit rate_limited
abgelehnt, und der Server versucht es später erneut, ohne jemanden abzumelden.
Eine Anmeldung über dem Limit der Person wird bei GitHub rückgängig gemacht und
abgelehnt.
Den Installationsschlüssel rotieren
Abschnitt betitelt „Den Installationsschlüssel rotieren“Nur der Serverinhaber kann den Schlüssel rotieren, mit Schlüssel rotieren auf der Karte Control Center Connect unter Einstellungen → Server → Single sign-on. Dafür gibt es keinen Befehl. Das Rotieren:
- Meldet alle von jeder Spur ab, die über Connect läuft. Für jeden Connect-Server, mit dem der alte Schlüssel genutzt wurde, widerruft der Server die GitHub- und Slack-Anmeldungen, die er von dort hält (eine Google-Anmeldung hat nichts zu widerrufen und läuft aus)
- Zieht die alte Installations-ID bei jedem dieser Connect-Server zurück, signiert mit dem alten Schlüssel und nachgewiesen mit einem Zugangsdaten-Siegel, das der Server von diesem Connect hält. Ab dann lehnt Connect jede Anfrage mit dem alten Schlüssel ab, daher ist ein Siegel oder eine Kopie des alten Schlüssels von diesem Server nutzlos, und die Slack-Arbeitsbereiche, die an die alte ID gebunden waren, werden frei, damit sie sich erneut verbinden können. Bereits ausgegebene Tokens bleiben gültig, bis sie ablaufen (eine Stunde für ein Bot-Token, acht Stunden für das einer Person). Ein Connect-Server, von dem dieser Server kein Siegel hält, hat nichts zurückzuziehen und wird übersprungen
- Gibt dem Server danach einen neuen Installationsschlüssel und eine neue Installations-ID
- Ist ein Connect-Server nicht erreichbar oder verweigert er das Zurückziehen der alten ID, hält der Vorgang an, bevor die Schlüssel gewechselt werden, und zeigt Connect konnte den alten Schlüssel nicht deaktivieren. Trotzdem erneuern wechselt die Schlüssel in jedem Fall; die alte Installations-ID bleibt dann bei diesem Connect nutzbar, bis ihre Tokens ablaufen, bei GitHub höchstens 8 Stunden
- Lässt Anmeldungen über die eigenen Apps des Servers unberührt
- Erfordert, dass die neue Installations-ID in die Zulassungsliste eines eigenen Connect eingetragen wird
Statuscodes
Abschnitt betitelt „Statuscodes“| Code | Bedeutung |
|---|---|
hosted_unprovisioned |
Dieser Build hat keinen Schlüssel für die gehostete Konfiguration |
signature |
Die gehostete Konfiguration hat ihre Signaturprüfung nicht bestanden |
rollback |
Connect hat eine ältere Konfiguration ausgeliefert, als der Server schon gesehen hat |
unreachable |
Der Server erreicht Connect nicht |
install_blocked |
Connect lässt diese Installations-ID nicht zu, oder sie wurde zurückgezogen |
pins_changed |
Ein eigenes Connect hat andere App-Kennungen angekündigt |
protocol |
Connect hat in einer Form geantwortet, die dieser Server nicht versteht |