Zum Inhalt springen

Einen Connect-Server betreiben

Control Center Connect führt Anbieter-Anmeldungen (GitHub, Google Calendar, Linear, Slack) für Server aus, die keine eigenen Apps registriert haben. Diese Anleitung zeigt, wie du dein eigenes Connect betreibst, sodass die Anbieter-Apps, ihre Secrets und die Liste der Server, die sie nutzen dürfen, alle bei dir bleiben.

Was Connect sehen kann und was nicht, steht in der Connect-Referenz. Lies sie zuerst, wenn du entscheidest, ob du eines betreiben willst.

  • Eine öffentliche HTTPS-Adresse für Connect, etwa https://connect.example.com, hinter einem Proxy, der TLS terminiert. Reines http wird nur auf Loopback angenommen
  • Docker, oder ein cc_server, den du mit zusätzlichen Umgebungsvariablen neu starten kannst
  • Die Berechtigung, bei jedem Anbieter, den du bedienen willst, Apps zu registrieren
  • Die Server, die es nutzen werden, und ihre Eigentümer in Reichweite: Jeder hat eine Installations-ID, die du in die Zulassungsliste von Connect einträgst

Wähle die URL jetzt und behalte sie. CONNECT_PUBLIC_URL steckt in allem, was Connect tut: Anfragesignaturen, versiegelte Zugangsdaten, Redirect-URLs der Anbieter und die Installations-ID jedes Servers sind daran gebunden. Sie später zu ändern heißt, die Redirects neu zu registrieren und dass sich alle erneut anmelden.

Registriere nur die Anbieter, die du bedienen willst. Ein Anbieter, dessen Variablen unvollständig sind, fehlt in der Konfiguration von Connect, und Server sehen ihn als nicht verfügbar. <base> ist unten deine CONNECT_PUBLIC_URL.

Anbieter Registrieren Behalten
GitHub App Callback-URL <base>/oauth/github/callback. Setup-URL <base>/oauth/github/setup mit eingeschaltetem Redirect on update. Lass Request user authorization (OAuth) during installation aus: Ist es an, ignoriert GitHub die Setup-URL. Lass Expire user authorization tokens an App-ID, Slug, Client-ID, Client-Secret, ein privater Schlüssel
Google Ein OAuth-Client vom Typ Webanwendung mit dem Redirect-URI <base>/oauth/google/callback, und die Google Calendar API aktiviert Client-ID, Client-Secret
Linear Eine OAuth-Anwendung mit den Callback-URLs <base>/oauth/linear/callback und <base>/oauth/linear_app/callback Nur die Client-ID
Slack Redirect-URLs <base>/oauth/slack_oidc/callback und <base>/oauth/slack/callback. Event Subscriptions unter <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash-Befehle unter <base>/v1/hooks/slack/commands. Token-Rotation an App-ID, Client-ID, Client-Secret, Signing Secret

Gib der GitHub App diese Repository-Berechtigungen: Metadata lesen, Contents lesen und schreiben, Pull requests lesen und schreiben, Issues lesen und schreiben, Checks, Actions und Commit statuses lesen. Füge für Review-Anfragen an Teams Members der Organisation mit Lesezugriff hinzu. Webhooks können aus bleiben: Server pollen.

Connect braucht den privaten Schlüssel der GitHub App (Privaten Schlüssel generieren in den Einstellungen der App). Damit signiert es die Anfragen der App, die die Installation finden, welche ein Repository abdeckt (oder, wenn das Repository keine hat, die Installation des Eigentümers), und stellt ein Installations-Token für ein einzelnes Repository aus, jeweils erst, nachdem die eigene Anmeldung der anfragenden Person den Zugriff auf dieses Repository belegt hat.

Jeder Server auf deinem Connect teilt sich den Bot der App. Er darf als Bot für jeden von ihnen lesen, kommentieren, Labels setzen und reagieren. Pull Requests als Bot zu prüfen, ist nur für die Server erlaubt, die du in CONNECT_GITHUB_REVIEW_BOT_INSTALLS aufführst (deren Installations-IDs, durch Kommas getrennt); jeder andere Server veröffentlicht Reviews mit dem eigenen Token des Prüfers. Pushen geschieht nie als Bot. Damit ein eigener Server als Bot prüfen darf, trage seine Installations-ID dort ein und starte neu. Behandle die Schlüsseldatei wie ein Geheimnis, so wie den Siegelschlüssel. Linear braucht kein Geheimnis: Connect gibt den Code an den Server zurück, der den Austausch selbst abschließt.

Connect antwortet nur den Servern auf seiner Zulassungsliste. Richte jeden Server auf dein Connect aus und lies dann seine Installations-ID ab:

  1. Geh zu Einstellungen → Server → Single sign-on, öffne die Karte Control Center Connect und wähle Eigenen Connect-Server verwenden
  2. Gib deine URL ein und speichere. Die Karte zeigt die Installations-ID des Servers

In einem Terminal auf dem Server-Host geht dasselbe so:

Terminalfenster
cc_server connect enable --url https://connect.example.com
cc_server connect status

status gibt die Installations-ID aus. Bis Schritt 5 erledigt ist, zeigt es install_blocked, und das ist erwartet.

Eine Installations-ID wird je Connect-Adresse abgeleitet, derselbe Server hat also für jedes Connect, mit dem er spricht, eine andere ID. Sie ändert sich nur, wenn ihr Eigentümer den Schlüssel rotiert.

Connect verschlüsselt jedes Zugangsdatum, das es zurückgibt, mit einem Siegelschlüssel. Erzeuge einen und bewahre ihn als geheime Datei auf:

Terminalfenster
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

Geht der Siegelschlüssel verloren, sind alle abgemeldet: Ohne ihn lässt sich kein Siegel öffnen.

Jedes Release veröffentlicht ghcr.io/samuelalev/cc-connect mit Build-Provenienz. Pinne in der Produktion einen Versions-Tag.

Terminalfenster
docker run -d --name cc-connect -p 8790:8790 \
-e CONNECT_PUBLIC_URL=https://connect.example.com \
-e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \
-e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \
-v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \
-e CONNECT_GITHUB_APP_ID=123456 \
-e CONNECT_GITHUB_APP_SLUG=acme-control-center \
-e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \
-e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \
-v "$PWD/github_secret:/run/secrets/github:ro" \
-e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \
-v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \
-v cc-connect-data:/data \
ghcr.io/samuelalev/cc-connect:latest

Richte deinen Reverse Proxy auf Port 8790 aus, und setze CONNECT_TRUST_PROXY auf die Anzahl der Proxys vor Connect, damit dessen Limit je Adresse jede Client-Adresse richtig sieht. Das Image läuft als unprivilegierter Benutzer, hält seinen Zustand im Volume /data und hat einen eingebauten Health-Check (cc-connect --healthcheck, der /healthz abfragt: Der Prozess antwortet). /readyz prüft außerdem, dass seine Zustands- und Bindungsspeicher antworten und dass Redis, falls genutzt, noch maxmemory-policy noeviction verwendet; richte die Bereitschaftsprüfung eines Orchestrators dorthin.

Die Zustimmungsseite der Anmeldung antwortet mit einem Formular-POST, den Connect nur von seiner eigenen Seite annimmt: Sec-Fetch-Site, wenn gesendet, muss same-origin sein, und Origin, wenn gesendet, muss der Origin von CONNECT_PUBLIC_URL sein; ein POST ohne beides wird abgelehnt. Der Proxy muss beide Header also unverändert durchreichen, und CONNECT_PUBLIC_URL muss die Adresse sein, die die Browser der Personen tatsächlich nutzen. Zeigt die Fortsetzung auf dieser Seite immer „Dieser Link ist abgelaufen“ und das Log oauth.done_refused mit dem Grund origin oder no_origin, ist eines dieser beiden Dinge falsch eingestellt.

Connect verweigert den Start (Exit-Code 78), wenn seine Konfiguration offen, unsicher oder halb fertig ist, und nennt die falsche Variable. Eine fehlende Zulassungsliste, eine http-Adresse außerhalb von Loopback, ein fehlerhafter Siegelschlüssel oder gleichzeitig gesetzte NAME und NAME_FILE halten es alle an.

Kontrolle: Auf jedem Server zeigt die Connect-Karte Funktioniert, und Wo jede Anmeldung läuft nennt Connect für jeden Anbieter, den du registriert hast. cc_server connect status gibt Health: ok und dieselben Spuren aus.

Ein Server kann Connect selbst hosten, statt einen eigenen Container zu nutzen. Der eingehängte Dienst ist derselbe, den das Image ausführt.

  1. Trag die Variablen CONNECT_* in die .env-Datei des Servers ein, wie in Schritt 5. Der Server startet nicht, wenn ein Connect-Geheimnis, CONNECT_SENTRY_DSN eingeschlossen, in seiner Umgebung exportiert ist
  2. Füge CC_SERVER_CONNECT_HOST=on hinzu
  3. Starte den Server neu. Sein Log zeigt embedded Connect at <url>
Terminalfenster
CC_SERVER_CONNECT_HOST=on
CONNECT_ALLOWED_INSTALLS=<install id>
CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>
CONNECT_GITHUB_APP_ID=123456
CONNECT_GITHUB_APP_SLUG=acme-control-center
CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd
CONNECT_GITHUB_CLIENT_SECRET=<secret>
CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pem

Connect wird dann unter <server>/connect ausgeliefert:

  • CONNECT_PUBLIC_URL ist standardmäßig der Origin der öffentlichen URL des Servers plus /connect. Setze sie hinter einem Proxy ausdrücklich. Ihr Pfad muss genau /connect sein, und sie muss HTTPS sein, außer auf Loopback
  • Nur Variablen CONNECT_* erreichen den eingehängten Dienst, er leiht sich also nie die eigenen Anbieter-Apps des Servers
  • CONNECT_ALLOWED_INSTALLS ist weiterhin Pflicht, auch für den hostenden Server selbst
  • Ein falsch konfiguriertes Einhängen hindert den Server am Start, statt einen offenen Broker auszuliefern
  • Der Demo-Server hängt es nie ein

Registriere die Redirects der Anbieter gegen https://<server>/connect und richte die Server (den hostenden eingeschlossen) dann wie in Schritt 3 auf diese URL aus.

Jede Einstellung ist eine Umgebungsvariable. Jedes Secret kann stattdessen aus einer eingehängten Datei kommen: Setze NAME_FILE statt NAME. Connect liest die Datei höchstens alle 30 Sekunden neu und behält den letzten gültigen Wert. Mit dual markierte Secrets nehmen während einer Rotation außerdem NAME_PREVIOUS (oder NAME_PREVIOUS_FILE).

Variable Vorgabe Bedeutung
CONNECT_PUBLIC_URL Pflicht Die kanonische öffentliche URL. HTTPS, oder http nur auf Loopback. Ein Pfad bedeutet Einhängen. Keine Query und kein Fragment
CONNECT_ALLOWED_INSTALLS Pflicht Kommagetrennte Installations-IDs. * wird nur zusammen mit CONNECT_SIGNED_CONFIG_FILE angenommen
CONNECT_DENY_INSTALLS Installations-IDs, die auch bei Zulassung abgewiesen werden
CONNECT_GITHUB_ALLOWED_OWNERS Numerische GitHub-Owner-IDs. Ist sie gesetzt, werden Repository-Tokens nur für Repositorys ausgestellt, die ihnen gehören. Sie begrenzt nicht, wer sich anmelden darf: Eine Person, die dieses Connect nutzen darf, erhält weiterhin ihr eigenes App-Benutzer-Token. Um nur eine Organisation zu bedienen, halte die App privat für sie
CONNECT_GITHUB_REVIEW_BOT_INSTALLS Installations-IDs, die Pull Requests vom Bot der App prüfen lassen dürfen. Standardmäßig leer; * wird abgelehnt, und jede ID muss außerdem zugelassen sein
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Bind-Adresse und Port
CONNECT_TRUST_PROXY 0 Vertrauenswürdige Proxy-Hops in X-Forwarded-For (0 bis 8). Nur für die Limits je Adresse, den Netzwerkhinweis der Anmeldeseite und die protokollierte Adresse genutzt. Hinter einem Proxy zählt 0 jeden Client als den Proxy, und das Log sagt das einmal
Variable Vorgabe Bedeutung
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID Die GitHub App
CONNECT_GITHUB_CLIENT_SECRET Secret, dual
CONNECT_GITHUB_APP_PRIVATE_KEY Secret. Der private Schlüssel der App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Der Google-Client. Das Secret ist dual
CONNECT_LINEAR_CLIENT_ID Die Linear-Anwendung. Ohne Secret
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID Die Slack-App
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Secrets, dual
CONNECT_KLIPY_APP_KEY Schlüssel für die GIF-Suche von Klipy. Secret, dual
CONNECT_KLIPY_MODE proxy proxy behält den Schlüssel in Connect; key gibt ihn an Server weiter
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google und Slack: die Generation, die in neuen Siegeln steht
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google und Slack: ältere Siegel müssen sich erneut anmelden
CONNECT_<LANE>_ACCEPTS_NEW true Jede Spur: false stoppt neue Anmeldungen, bestehende werden weiter erneuert
Variable Vorgabe Bedeutung
CONNECT_SEAL_BACKEND local local oder gcp-kms
CONNECT_SEAL_KEYS Secret, Pflicht für local. Kommagetrennte Einträge kid:key, der neueste zuerst; ältere Einträge entschlüsseln weiterhin
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, Pflicht für gcp-kms
CONNECT_STATE memory memory für eine Instanz, redis für mehrere. Eine volle Speicherung im Speicher lehnt neue Anmeldungen und Anfragen ab, statt einen laufenden Eintrag zu vergessen
CONNECT_REDIS_URL Secret. redis:// oder rediss://. Redis 6.2 oder neuer mit maxmemory-policy noeviction, beides wird beim Start geprüft
CONNECT_REDIS_CA_FILE CA-Bundle für rediss://
CONNECT_BINDINGS file Wo die Slack-Team-Bindungen liegen: file oder firestore
CONNECT_DATA_DIR data (/data im Image) Enthält bindings.json. Von einem Connect gesperrt: Ein zweites auf demselben Verzeichnis startet nicht
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE Datenbank (default) Für CONNECT_BINDINGS=firestore. Connect startet nicht, wenn Firestore nicht antwortet
Variable Vorgabe Bedeutung
CONNECT_SIGNED_CONFIG_FILE Eine offline signierte Konfiguration, unverändert ausgeliefert. Vom gehosteten Connect von Control Center genutzt
CONNECT_CONFIG_PUBLIC_KEYS Schlüssel, gegen die sich die signierte Konfiguration verifizieren muss
CONNECT_CONFIG_EPOCH 1 Die Epoche der Konfiguration, die ein selbst gehostetes Connect erzeugt
CONNECT_LOG_HMAC_KEY zufällig je Prozess Secret. Setze ihn, damit die Kennungen, die für Installations-IDs stehen, über Neustarts und Instanzen hinweg stabil bleiben
CONNECT_SENTRY_DSN Secret. Eine https-Sentry-DSN, an die Fehlerzeilen gemeldet werden: der Fehlertyp, Stack-Frames, Route und Request-ID, nie eine Nachricht, ein Body oder ein Header
CONNECT_SENTRY_ENVIRONMENT self-hosted Die Sentry-Umgebung
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Von /v1/version gemeldet
CONNECT_RATE_INSTALL_PER_MINUTE 600 Anfragen je Installation
CONNECT_RATE_IP_PER_MINUTE 300 Anfragen je Adresse (eine IPv6-Adresse zählt je /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Anfragen für die ganze Instanz
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Slack-Ereignis- und Befehlszustellungen je Adresse, getrennt von anderen Anfragen
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Slack-Ereignis- und Befehlszustellungen für die ganze Instanz
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Slack-Ereignisse je Team
CONNECT_RATE_KLIPY_PER_MINUTE 120 GIF-Suchen je Installation
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 GIF-Suchen je Adresse, über alle Server hinweg
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Begonnene Anmeldungen je Adresse
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 GitHub-Tokens je GitHub-Konto auf einem Server (Anmeldungen, Erneuerungen, Repository-Tokens)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × der obige Wert (120) Dasselbe je GitHub-Konto über alle Server hinweg
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 GitHub-Tokens je Adresse
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Neue GitHub-Anmeldungen für die ganze App
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Bot-Tokens je Server
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Bot-Tokens je anfragendem GitHub-Konto, über alle Server hinweg
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Bot-Tokens für die ganze App
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Erneuerungen und Repository-Tokens für die ganze App. Neue Anmeldungen haben ihr eigenes Limit oben
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Live-Repository-Tokens, die ein GitHub-Konto halten darf, bevor Connect eine Warnung protokolliert
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Ausgemusterte Installations-IDs je Adresse (bei IPv6 je /48)

Ein Aufruf über einem Limit wird mit rate_limited beantwortet. Server versuchen es später erneut und melden niemanden deswegen ab.

Eine Instanz mit CONNECT_STATE=memory reicht für die meisten Organisationen. Mehrere Instanzen hinter einer Adresse brauchen CONNECT_STATE=redis und CONNECT_BINDINGS=firestore, damit eine Anmeldung, die auf einer Instanz beginnt, auf einer anderen enden kann und jede Instanz dieselben Slack-Bindungen und ausgemusterten Installations-IDs sieht. Ein gemeinsames CONNECT_DATA_DIR funktioniert nicht: Das erste Connect sperrt es. Die Limits je Installation, je Adresse und für die Instanz gelten je Instanz; die Limits für Anmeldungen, GitHub-Tokens, Bot-Tokens, GIF-Suchen je Adresse, Ausmusterungen und Slack-Teams werden über den Zustandsspeicher geteilt.

Niemand wird abgemeldet:

  1. Erzeuge das neue Secret beim Anbieter und behalte das alte
  2. Verschiebe den alten Wert nach NAME_PREVIOUS, setze den neuen in NAME und erhöhe CONNECT_<LANE>_SECRET_GENERATION. Eingehängte Dateien werden innerhalb von 30 Sekunden übernommen
  3. Warte, bis sich die Anmeldungen erneuert haben, lösche dann das alte Secret beim Anbieter und entferne NAME_PREVIOUS

Um einen Siegelschlüssel zu rotieren, setze einen neuen Eintrag aus cc-connect-config seal-key an den Anfang von CONNECT_SEAL_KEYS und behalte den alten Eintrag, bis sich seine Siegel erneuert haben.

Server merken sich die App- und Client-IDs, die dein Connect angekündigt hat, als sie es zum ersten Mal genutzt haben. Ersetzt du eine App, zeigt die Connect-Karte jedes Servers Die Apps von Connect haben sich geändert, und Anmeldungen über Connect pausieren, bis ihr Eigentümer auf Neuen Apps vertrauen klickt. Sag den Server-Eigentümern vor dem Wechsel Bescheid, damit sie wissen, dass die Rückfrage von dir kommt.

Füge seine Installations-ID zu CONNECT_DENY_INSTALLS hinzu und starte neu. Sein Eigentümer sieht „Connect hat die Installations-ID dieses Servers gesperrt. Wende dich an den Betreiber deines Connect-Servers.“, und jede Connect-Anmeldung darauf stoppt.

Ein Server ersetzt auch seine eigene alte Installations-ID, wenn sein Eigentümer den Schlüssel rotiert. Er belegt, dass die ID seine eigene ist, mit einem Siegel für Zugangsdaten, das dieses Connect für ihn erzeugt hat; daher kann nur ein Server, der jemanden angemeldet hat, eine ID ausmustern. Connect behält ausgemusterte IDs dauerhaft, sodass der alte Schlüssel und jedes für ihn erzeugte Siegel nicht mehr funktionieren, und gibt die Slack-Arbeitsbereiche frei, die an die alte ID gebunden waren. Bereits ausgegebene Tokens laufen von selbst ab: innerhalb von 8 Stunden die einer Person, innerhalb von 1 Stunde die eines Bots. Connect hält höchstens 100.000 ausgemusterte IDs; darüber hinaus wird eine Rotation abgelehnt, und das Log sagt es auf Fehlerebene.

Seine Installations-ID steht nicht in CONNECT_ALLOWED_INSTALLS, sie steht in CONNECT_DENY_INSTALLS, oder sie wurde durch eine Schlüsselrotation ausgemustert. Die ID ändert sich, wenn ihr Eigentümer den Schlüssel rotiert; frag nach der neuen.

Eine seiner Variablen fehlt möglicherweise, deshalb hat Connect die Spur weggelassen. Prüfe das Startlog und die Tabellen oben. GitHub braucht alle fünf: App-ID, Slug, Client-ID, Client-Secret und privaten Schlüssel; Google braucht Client-ID und Secret.

Anmeldungen scheitern an einem nicht passenden Redirect

Abschnitt betitelt „Anmeldungen scheitern an einem nicht passenden Redirect“

Der beim Anbieter registrierte Redirect stimmt nicht genau mit CONNECT_PUBLIC_URL überein. Vergleiche Schema, Host, Port und bei einem eingehängten Connect den Pfad /connect.

Der Siegelschlüssel hat sich geändert oder ging verloren, ein Server hat seinen Schlüssel rotiert, oder die Daten eines Servers wurden auf einer anderen Maschine wiederhergestellt. Ein versiegeltes Zugangsdatum öffnet sich nur für die Installation und das Connect, die es erzeugt haben.