Přeskočit na obsah

Spusťte server Connect

Control Center Connect provádí přihlášení k poskytovatelům (GitHub, Google Calendar, Linear, Slack) pro servery, které si nezaregistrovaly vlastní aplikace. Tenhle návod ukazuje, jak provozovat vlastní Connect, aby aplikace poskytovatelů, jejich tajemství i seznam serverů, které je smějí používat, zůstaly u tebe.

Co Connect vidí a co ne, popisuje reference Connect. Přečti si ji nejdřív, pokud se rozhoduješ, jestli ho provozovat.

  • Veřejná adresa HTTPS pro Connect, například https://connect.example.com, za proxy, která ukončuje TLS. Obyčejné http se přijme jen na loopbacku
  • Docker, nebo cc_server, který můžeš restartovat s dalšími proměnnými prostředí
  • Oprávnění registrovat aplikace u každého poskytovatele, kterého chceš obsluhovat
  • Servery, které ho budou používat, a jejich vlastníky po ruce: každý má ID instalace, které přidáš na seznam povolených v Connect

URL vyber teď a už ji neměň. CONNECT_PUBLIC_URL je součástí všeho, co Connect dělá: podpisy požadavků, zapečetěná pověření, URL přesměrování poskytovatelů i ID instalace každého serveru jsou na ni vázané. Pozdější změna znamená znovu zaregistrovat přesměrování a znovu přihlásit všechny lidi.

Krok 2: Zaregistruj aplikace poskytovatelů

Sekce “Krok 2: Zaregistruj aplikace poskytovatelů”

Registruj jen poskytovatele, které chceš obsluhovat. Poskytovatel s neúplnými proměnnými se z konfigurace Connect vynechá a servery ho vidí jako nedostupného. <base> níže je tvoje CONNECT_PUBLIC_URL.

Poskytovatel Co zaregistrovat Co si nechat
GitHub App Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup se zapnutým Redirect on update. Request user authorization (OAuth) during installation nech vypnuté: když je zapnuté, GitHub setup URL ignoruje. Expire user authorization tokens nech zapnuté App id, slug, client id, client secret, soukromý klíč
Google Klient OAuth typu Web application s URI přesměrování <base>/oauth/google/callback a zapnuté Google Calendar API Client id, client secret
Linear Aplikace OAuth s callback URL <base>/oauth/linear/callback a <base>/oauth/linear_app/callback Jen client id
Slack Redirect URL <base>/oauth/slack_oidc/callback a <base>/oauth/slack/callback. Event Subscriptions na <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash příkazy na <base>/v1/hooks/slack/commands. Zapnutá rotace tokenů App id, client id, client secret, signing secret

Dej GitHub App tato oprávnění k repozitářům: Metadata pro čtení, Contents pro čtení a zápis, Pull requests pro čtení a zápis, Issues pro čtení a zápis, Checks, Actions a Commit statuses pro čtení. Pro žádosti o kontrolu od týmů přidej organizační oprávnění Members pro čtení. Webhooky můžou zůstat vypnuté: servery se dotazují samy.

Connect potřebuje soukromý klíč GitHub App (Vygenerovat soukromý klíč v nastavení App). Podepisuje požadavky App, které najdou instalaci pokrývající repozitář (a když ji repozitář nemá, instalaci vlastníka), a vydává jednorepozitářový token instalace, pokaždé až poté, co přihlášení daného člověka prokáže přístup k tomuto repozitáři.

Každý server na tvém Connectu sdílí bota App. Může jako bot číst, komentovat, označovat štítky a reagovat u kteréhokoli z nich. Revidovat pull requesty jako bot smějí jen servery, které uvedeš v CONNECT_GITHUB_REVIEW_BOT_INSTALLS (jejich ID instalací, oddělená čárkou); každý další server zveřejňuje revize tokenem samotného revidujícího. Push se nikdy nedělá jako bot. Aby mohl revidovat jako bot tvůj vlastní server, přidej jeho ID instalace tam a restartuj. Soubor s klíčem drž jako tajemství, stejně jako klíč pečetí. Linear nepotřebuje žádné tajemství: Connect vrátí kód serveru, který výměnu dokončí sám.

Krok 3: Posbírej ID instalací

Sekce “Krok 3: Posbírej ID instalací”

Connect odpovídá jen serverům ze svého seznamu povolených. Na každém serveru ho nasměruj na svůj Connect a pak přečti jeho ID instalace:

  1. Jdi do Nastavení → Server → Jednotné přihlášení, otevři kartu Control Center Connect a zvol Použít vlastní server Connect
  2. Zadej svou URL a ulož. Karta ukáže ID instalace serveru

Z terminálu na hostiteli serveru je to totéž:

Terminál
cc_server connect enable --url https://connect.example.com
cc_server connect status

status vypíše ID instalace. Dokud nedokončíš krok 5, ukazuje install_blocked, a to se čeká.

ID instalace se odvozuje pro každou adresu Connect zvlášť, takže tentýž server má pro každý Connect, se kterým mluví, jiné ID. Změní se jen tehdy, když vlastník vymění klíč.

Krok 4: Vytvoř klíč pečetí

Sekce “Krok 4: Vytvoř klíč pečetí”

Connect každé pověření, které vrací, zašifruje klíčem pečetí. Vytvoř ho a drž ho jako soubor s tajemstvím:

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

Ztráta klíče pečetí odhlásí všechny: bez něj žádnou pečeť otevřít nejde.

Krok 5: Spusť kontejner

Sekce “Krok 5: Spusť kontejner”

Každé vydání publikuje ghcr.io/samuelalev/cc-connect s provenancí sestavení. V produkci připni tag verze.

Terminál
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

Reverzní proxy nasměruj na port 8790 a nastav CONNECT_TRUST_PROXY na počet proxy před Connectem, aby jeho limit na adresu viděl adresu každého klienta. Obraz běží jako neprivilegovaný uživatel, stav drží ve svazku /data a má vestavěnou kontrolu stavu (cc-connect --healthcheck, která se ptá /healthz: proces odpovídá). /readyz navíc ověřuje, že jeho úložiště stavu a vazeb odpovídají a že Redis, pokud se používá, stále běží s maxmemory-policy noeviction; na ni nasměruj kontrolu připravenosti orchestrátoru.

Stránka se souhlasem s přihlášením odpovídá formulářovým POSTem, který Connect přijme jen ze své vlastní stránky: Sec-Fetch-Site, když je odeslána, musí být same-origin, a Origin, když je odeslána, musí být origin CONNECT_PUBLIC_URL; POST bez obojího se odmítne. Proxy proto musí obě hlavičky předávat beze změny a CONNECT_PUBLIC_URL musí být adresa, kterou lidé v prohlížeči opravdu používají. Když na té stránce pokračování pořád ukazuje „Platnost tohoto odkazu vypršela“ a log ukazuje oauth.done_refused s důvodem origin nebo no_origin, je jedna z těchto dvou věcí vypnutá.

Connect odmítne nastartovat (exit kód 78), když je jeho konfigurace otevřená, nebezpečná nebo nedokončená, a vypíše, která proměnná je špatně. Zastaví ho chybějící seznam povolených, adresa http mimo loopback, poškozený klíč pečetí nebo současně nastavené NAME a NAME_FILE.

Kontrolní bod: na každém serveru karta Connect hlásí Funguje a Kde probíhá každé přihlášení u každého zaregistrovaného poskytovatele jmenuje Connect. cc_server connect status vypíše Health: ok a stejné dráhy.

Vestav Connect do cc_server

Sekce “Vestav Connect do cc_server”

Server může Connect hostovat sám, místo samostatného kontejneru. Vestavěná služba je tatáž, jakou spouští obraz.

  1. Dej proměnné CONNECT_* do souboru .env serveru, jako v kroku 5. Server odmítne nastartovat, když je v jeho prostředí exportované některé tajemství Connectu, včetně CONNECT_SENTRY_DSN
  2. Přidej CC_SERVER_CONNECT_HOST=on
  3. Restartuj server. Jeho log vypíše embedded Connect at <url>
Terminál
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 se pak obsluhuje na <server>/connect:

  • CONNECT_PUBLIC_URL je ve výchozím stavu origin veřejné URL serveru plus /connect. Za proxy ho nastav výslovně. Jeho cesta musí být přesně /connect a musí jít o HTTPS, pokud nejde o loopback
  • K vestavěné službě se dostanou jen proměnné CONNECT_*, takže si nikdy nepůjčí vlastní aplikace poskytovatelů serveru
  • CONNECT_ALLOWED_INSTALLS je pořád povinné, i pro samotný hostující server
  • Špatně nastavená vestavba zabrání serveru nastartovat, místo aby obsluhoval otevřeného brokera
  • Demo server ho nikdy nevestaví

Přesměrování u poskytovatelů zaregistruj proti https://<server>/connect a pak na tu URL nasměruj servery (i ten hostující), stejně jako v kroku 3.

Referenční přehled konfigurace

Sekce “Referenční přehled konfigurace”

Každé nastavení je proměnná prostředí. Kterékoli tajemství může místo toho přijít z připojeného souboru: místo NAME nastav NAME_FILE. Connect soubor čte znovu nejvýš každých 30 sekund a drží si poslední dobrou hodnotu. Tajemství označená dual během rotace přijímají i NAME_PREVIOUS (nebo NAME_PREVIOUS_FILE).

Proměnná Výchozí Význam
CONNECT_PUBLIC_URL povinná Kanonická veřejná URL. HTTPS, nebo http jen na loopbacku. Cesta znamená vestavbu. Bez query a fragmentu
CONNECT_ALLOWED_INSTALLS povinná ID instalací oddělená čárkou. * se přijme jen spolu s CONNECT_SIGNED_CONFIG_FILE
CONNECT_DENY_INSTALLS ID instalací, která se odmítnou, i když jsou povolená
CONNECT_GITHUB_ALLOWED_OWNERS Číselná id vlastníků na GitHubu. Když je nastavené, tokeny repozitářů se vydávají jen pro repozitáře, které vlastní. Nelimituje, kdo se přihlásí: člověk, který smí tento Connect používat, dostane pořád svůj vlastní uživatelský token App. Chceš-li obsluhovat jen jednu organizaci, drž App jen pro ni
CONNECT_GITHUB_REVIEW_BOT_INSTALLS ID instalací, které smí nechat bota App revidovat pull requesty. Ve výchozím stavu prázdné; * se odmítne a každé ID musí být také povolené
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Adresa a port, na které se váže
CONNECT_TRUST_PROXY 0 Důvěryhodné skoky proxy v X-Forwarded-For (0 až 8). Použije se jen pro limity na adresu, pro síťovou nápovědu na přihlašovací stránce a pro zalogovanou adresu. Za proxy 0 počítá každého klienta jako proxy a log to jednou řekne
Proměnná Výchozí Význam
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID GitHub App
CONNECT_GITHUB_CLIENT_SECRET Tajemství, dual
CONNECT_GITHUB_APP_PRIVATE_KEY Tajemství. Soukromý klíč App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Klient Google. Tajemství je dual
CONNECT_LINEAR_CLIENT_ID Aplikace Linear. Bez tajemství
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID Aplikace Slack
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Tajemství, dual
CONNECT_KLIPY_APP_KEY Klíč Klipy pro hledání GIF. Tajemství, dual
CONNECT_KLIPY_MODE proxy proxy drží klíč v Connect; key ho předá serverům
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google a Slack: generace zapisovaná do nových pečetí
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google a Slack: se staršími pečetěmi se je nutné přihlásit znovu
CONNECT_<LANE>_ACCEPTS_NEW true Každá dráha: false zastaví nová přihlášení, zatímco stávající se dál obnovují

Pečetě, stav a úložiště

Sekce “Pečetě, stav a úložiště”
Proměnná Výchozí Význam
CONNECT_SEAL_BACKEND local local nebo gcp-kms
CONNECT_SEAL_KEYS Tajemství, povinné pro local. Položky kid:key oddělené čárkou, nejnovější první; starší pořád dešifrují
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, povinné pro gcp-kms
CONNECT_STATE memory memory pro jednu instanci, redis pro několik. Plné paměťové úložiště odmítne nová přihlášení a požadavky, místo aby zapomnělo živý záznam
CONNECT_REDIS_URL Tajemství. redis:// nebo rediss://. Redis 6.2 nebo novější s maxmemory-policy noeviction, obojí se ověří při startu
CONNECT_REDIS_CA_FILE Balík CA pro rediss://
CONNECT_BINDINGS file Kde leží vazby týmů Slacku: file nebo firestore
CONNECT_DATA_DIR data (/data v obrazu) Obsahuje bindings.json. Zamyká ho jeden Connect: druhý nad stejným adresářem nenastartuje
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE databáze (default) Pro CONNECT_BINDINGS=firestore. Connect nenastartuje, když Firestore neodpovídá

Konfigurace, logy a limity

Sekce “Konfigurace, logy a limity”
Proměnná Výchozí Význam
CONNECT_SIGNED_CONFIG_FILE Offline podepsaná konfigurace, obsluhovaná tak, jak je. Používá ji hostovaný Connect od Control Center
CONNECT_CONFIG_PUBLIC_KEYS Klíče, proti kterým se podepsaná konfigurace musí ověřit
CONNECT_CONFIG_EPOCH 1 Epocha konfigurace, kterou generuje Connect hostovaný u tebe
CONNECT_LOG_HMAC_KEY náhodný pro každý proces Tajemství. Nastav ho, aby značky zastupující ID instalací zůstaly stejné napříč restarty a instancemi
CONNECT_SENTRY_DSN Tajemství. https DSN Sentry, kam se hlásí chybové řádky: typ chyby, rámce zásobníku, trasa a id požadavku, nikdy zpráva, tělo ani hlavička
CONNECT_SENTRY_ENVIRONMENT self-hosted Prostředí Sentry
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Hlásí je /v1/version
CONNECT_RATE_INSTALL_PER_MINUTE 600 Požadavky na instalaci
CONNECT_RATE_IP_PER_MINUTE 300 Požadavky na adresu (adresa IPv6 se počítá na /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Požadavky na celou instanci
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Doručení událostí a příkazů Slacku na adresu, počítané odděleně od ostatních požadavků
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Doručení událostí a příkazů Slacku pro celou instanci
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Události Slacku na tým
CONNECT_RATE_KLIPY_PER_MINUTE 120 Hledání GIF na instalaci
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 Hledání GIF na adresu, napříč servery
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Zahájená přihlášení na adresu
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 GitHub tokeny vydané jednomu účtu GitHubu na jednom serveru (přihlášení, obnovení, tokeny repozitářů)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × výše (120) Totéž pro účet GitHubu napříč všemi servery
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 GitHub tokeny vydané na adresu
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Nová přihlášení GitHubem pro celou aplikaci
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Tokeny bota na server
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Tokeny bota na žádající účet GitHubu, napříč servery
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Tokeny bota pro celou aplikaci
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Obnovení a tokeny repozitářů pro celou aplikaci. Nová přihlášení mají vlastní limit výše
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Živé tokeny repozitářů, které může mít jeden účet GitHubu, než Connect zaloguje varování
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Vyřazená ID instalací na adresu (pro IPv6 na /48)

Volání nad limit dostane odpověď rate_limited. Servery to zkusí později a nikoho kvůli tomu neodhlásí.

Provozuj víc než jednu instanci

Sekce “Provozuj víc než jednu instanci”

Většině organizací stačí jedna instance s CONNECT_STATE=memory. Několik instancí za jednou adresou potřebuje CONNECT_STATE=redis a CONNECT_BINDINGS=firestore, aby přihlášení zahájené na jedné instanci šlo dokončit na jiné a každá instance viděla tytéž vazby Slacku a stejná vyřazená ID instalací. Sdílený CONNECT_DATA_DIR nefunguje: první Connect ho zamkne. Limity na instalaci, na adresu a na instanci požadavků platí pro každou instanci zvlášť; limity na přihlášení, tokeny GitHubu, tokeny bota, hledání GIF na adresu, vyřazení a týmy Slacku se sdílejí přes úložiště stavu.

Obměň tajemství poskytovatele

Sekce “Obměň tajemství poskytovatele”

Nikdo se neodhlásí:

  1. U poskytovatele vytvoř nové tajemství a staré si nech
  2. Starou hodnotu přesuň do NAME_PREVIOUS, novou dej do NAME a zvyš CONNECT_<LANE>_SECRET_GENERATION. Připojené soubory se převezmou do 30 sekund
  3. Počkej, až se přihlášení obnoví, pak staré tajemství u poskytovatele smaž a odeber NAME_PREVIOUS

Klíč pečetí obměníš tak, že novou položku z cc-connect-config seal-key dáš v CONNECT_SEAL_KEYS na první místo a starou necháš, dokud se její pečetě neobnoví.

Servery si pamatují id aplikací a klientů, které tvůj Connect ohlásil, když ho použily poprvé. Když aplikaci vyměníš, karta Connect na každém serveru ukáže Aplikace Connect se změnily a přihlášení přes Connect se pozastaví, dokud jeho vlastník nestiskne Důvěřovat novým aplikacím. Vlastníkům serverů to řekni předem, aby věděli, že výzva je od tebe.

Přidej jeho ID instalace do CONNECT_DENY_INSTALLS a restartuj. Jeho vlastník uvidí „Connect zablokoval ID instalace tohoto serveru. Obraťte se na provozovatele svého serveru Connect.“ a každé přihlášení přes Connect na něm skončí.

Server také vyřadí své vlastní staré ID instalace, když jeho vlastník vymění klíč. Dokáže, že ID je jeho, jedinou pečetí přihlašovacího údaje, kterou pro něj tento Connect vytvořil, takže vyřadit ID může jen server, který někoho přihlásil. Connect vyřazená ID drží natrvalo, takže starý klíč a každá pečeť k němu vytvořená přestanou fungovat, a uvolní týmy Slacku navázané na staré ID. Tokeny už vydané vyprší samy: do 8 hodin u osobních, do 1 hodiny u botových. Connect drží nejvýš 100 000 vyřazených ID; nad tím se rotace odmítne a log to zapíše na úrovni error.

Server hlásí, že ho Connect zablokoval

Sekce “Server hlásí, že ho Connect zablokoval”

Jeho ID instalace není v CONNECT_ALLOWED_INSTALLS, je v CONNECT_DENY_INSTALLS, nebo ho vyřadila výměna klíče. ID se změní, když vlastník vymění klíč; požádej o nové.

Každé přihlášení k jednomu poskytovateli selže

Sekce “Každé přihlášení k jednomu poskytovateli selže”

Může chybět některá z jeho proměnných, takže Connect dráhu vynechal. Projdi log při startu a tabulky výše. GitHub potřebuje všech pět: app id, slug, client id, client secret a soukromý klíč; Google potřebuje client id i secret.

Přihlášení selhávají na nesouladu přesměrování

Sekce “Přihlášení selhávají na nesouladu přesměrování”

Přesměrování zaregistrované u poskytovatele přesně neodpovídá CONNECT_PUBLIC_URL. Porovnej schéma, hostitele, port a u vestavěného Connect cestu /connect.

Všichni se museli přihlásit znovu

Sekce “Všichni se museli přihlásit znovu”

Klíč pečetí se změnil nebo ztratil, některý server vyměnil svůj klíč, nebo se data serveru obnovila na jiný stroj. Zapečetěné pověření se otevře jen pro instalaci a Connect, které ho vytvořily.