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.
Předpoklady
Sekce “Předpoklady”- Veřejná adresa HTTPS pro Connect, například
https://connect.example.com, za proxy, která ukončuje TLS. Obyčejnéhttpse 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
Krok 1: Zvol adresu
Sekce “Krok 1: Zvol adresu”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íč |
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:
- Jdi do Nastavení → Server → Jednotné přihlášení, otevři kartu Control Center Connect a zvol Použít vlastní server Connect
- Zadej svou URL a ulož. Karta ukáže ID instalace serveru
Z terminálu na hostiteli serveru je to totéž:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus 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:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysZtrá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.
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:latestReverzní 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.
- Dej proměnné
CONNECT_*do souboru.envserveru, jako v kroku 5. Server odmítne nastartovat, když je v jeho prostředí exportované některé tajemství Connectu, včetněCONNECT_SENTRY_DSN - Přidej
CC_SERVER_CONNECT_HOST=on - Restartuj server. Jeho log vypíše
embedded Connect at <url>
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_GITHUB_CLIENT_SECRET=<secret>CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pemConnect se pak obsluhuje na <server>/connect:
CONNECT_PUBLIC_URLje 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ě/connecta 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_INSTALLSje 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).
Adresa a přístup
Sekce “Adresa a přístup”| 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 |
Dráhy poskytovatelů
Sekce “Dráhy poskytovatelů”| 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í:
- U poskytovatele vytvoř nové tajemství a staré si nech
- Starou hodnotu přesuň do
NAME_PREVIOUS, novou dej doNAMEa zvyšCONNECT_<LANE>_SECRET_GENERATION. Připojené soubory se převezmou do 30 sekund - 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í.
Změň aplikaci
Sekce “Změň aplikaci”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.
Zablokuj server
Sekce “Zablokuj server”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.
Řešení problémů
Sekce “Řešení problémů”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.