Kör en Connect-server
Control Center Connect kör leverantörsinloggningar (GitHub, Google Calendar, Linear, Slack) för servrar som inte har registrerat egna appar. Den här guiden visar hur du kör din egen Connect, så att leverantörsapparna, deras hemligheter och listan över servrar som får använda dem stannar hos dig.
Vad Connect kan och inte kan se står i Connect-referensen. Läs den först om du funderar på om du ska köra en.
Förutsättningar
Avsnitt med rubriken “Förutsättningar”- En offentlig HTTPS-adress för Connect, till exempel
https://connect.example.com, bakom en proxy som terminerar TLS. Vanlighttpaccepteras bara på loopback - Docker, eller en
cc_serversom du kan starta om med extra miljövariabler - Behörighet att registrera appar hos varje leverantör som du vill betjäna
- Servrarna som ska använda den, med deras ägare till hands: var och en har ett installations-id som du lägger till i Connects tillåtelselista
Steg 1: Välj adressen
Avsnitt med rubriken “Steg 1: Välj adressen”Välj URL:en nu och behåll den. CONNECT_PUBLIC_URL ingår i allt Connect gör:
begärandesignaturer, förseglade inloggningsuppgifter, leverantörernas
omdirigerings-URL:er och varje servers installations-id är bundna till den. Att
ändra den senare innebär att registrera omdirigeringarna igen och att alla måste
logga in igen.
Steg 2: Registrera leverantörsapparna
Avsnitt med rubriken “Steg 2: Registrera leverantörsapparna”Registrera bara de leverantörer som du vill betjäna. En leverantör vars variabler
är ofullständiga utelämnas ur Connects konfiguration, och servrarna ser den som
otillgänglig. <base> nedan är din CONNECT_PUBLIC_URL.
| Leverantör | Registrera | Spara |
|---|---|---|
| GitHub App | Callback-URL <base>/oauth/github/callback. Setup-URL <base>/oauth/github/setup med Redirect on update påslaget. Låt Request user authorization (OAuth) during installation vara avstängt: när det är på ignorerar GitHub setup-URL:en. Låt Expire user authorization tokens vara påslaget |
App-ID, slug, klient-ID, klienthemlighet, en privat nyckel |
En OAuth-klient av typen Web application med omdirigerings-URI <base>/oauth/google/callback, och Google Calendar API aktiverat |
Klient-ID, klienthemlighet | |
| Linear | En OAuth-applikation med callback-URL:erna <base>/oauth/linear/callback och <base>/oauth/linear_app/callback |
Bara klient-ID |
| Slack | Omdirigerings-URL:er <base>/oauth/slack_oidc/callback och <base>/oauth/slack/callback. Event Subscriptions på <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash-kommandon på <base>/v1/hooks/slack/commands. Tokenrotation påslagen |
App-ID, klient-ID, klienthemlighet, signing secret |
Ge GitHub-appen de här repobehörigheterna: Metadata läsa, Contents läsa och skriva, Pull requests läsa och skriva, Issues läsa och skriva, Checks, Actions och Commit statuses läsa. Lägg till Members för organisationen med läsrätt för granskningsbegäranden till team. Webhooks kan vara avstängda: servrarna pollar.
Connect behöver GitHub-appens privata nyckel (Skapa en privat nyckel i appens inställningar). Den signerar appens förfrågningar som hittar installationen som täcker ett repo (eller, när repot saknar en, ägarens installation) och utfärdar en installationstoken för ett enda repo, var och en först efter att personen som frågar har bevisat sin egen inloggning och åtkomst till repot.
Varje server på din Connect delar appens bot. Den får läsa, kommentera, sätta etiketter
och reagera som boten för vilken som helst av dem. Att granska pull requests som boten
är bara tillåtet för de servrar du listar i CONNECT_GITHUB_REVIEW_BOT_INSTALLS (deras
installations-id:n, kommaseparerade); varje annan server publicerar granskningar med
granskarens egen token. Pushar görs aldrig som boten. För att låta en server du själv
driver granska som boten, lägg till dess installations-id där och starta om. Behåll
nyckelfilen som en hemlighet, precis som sigillnyckeln. Linear behöver ingen hemlighet:
Connect lämnar tillbaka koden till servern, som slutför utbytet själv.
Steg 3: Samla in installations-id:na
Avsnitt med rubriken “Steg 3: Samla in installations-id:na”Connect svarar bara servrarna på sin tillåtelselista. På varje server pekar du den mot din Connect och läser sedan av dess installations-id:
- Gå till Inställningar → Server → Enkel inloggning, öppna kortet Control Center Connect och välj Använd en egen Connect-server
- Ange din URL och spara. Kortet visar serverns Installations-id
Från en terminal på servervärden är samma sak:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus skriver ut installations-id:t. Det visar install_blocked tills steg 5
är klart, och det är väntat.
Ett installations-id härleds per Connect-adress, så samma server har ett annat id för varje Connect den pratar med. Det ändras bara när ägaren byter nyckeln.
Steg 4: Skapa en sigillnyckel
Avsnitt med rubriken “Steg 4: Skapa en sigillnyckel”Connect krypterar varje inloggningsuppgift som den lämnar tillbaka med en sigillnyckel. Skapa en och förvara den som en hemlig fil:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysFörlorar du sigillnyckeln loggas alla ut: inget sigill kan öppnas utan den.
Steg 5: Starta containern
Avsnitt med rubriken “Steg 5: Starta containern”Varje release publicerar ghcr.io/samuelalev/cc-connect med byggproveniens.
Lås en versionstagg i produktion.
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:latestPeka din omvända proxy mot port 8790, och sätt CONNECT_TRUST_PROXY till antalet
proxyer framför Connect, så att dess gräns per adress ser varje klients adress.
Avbildningen körs som en användare utan privilegier, sparar sitt tillstånd i volymen
/data och har en inbyggd hälsokontroll (cc-connect --healthcheck, som kontrollerar
/healthz: processen svarar). /readyz kontrollerar dessutom att dess tillstånds- och
bindningslager svarar och att Redis, när den används, fortfarande kör
maxmemory-policy noeviction; peka en orkestrerares beredskapskontroll dit.
Sidan för inloggningsgodkännandet svarar med ett formulär-POST som Connect bara accepterar
från sin egen sida: Sec-Fetch-Site, när den skickas, måste vara same-origin, och
Origin, när den skickas, måste vara ursprunget för CONNECT_PUBLIC_URL; en POST med
ingetdera nekas. Så proxyn måste vidarebefordra båda headerna oförändrade, och
CONNECT_PUBLIC_URL måste vara den adress folks webbläsare faktiskt använder. Om det
alltid visas “Länken har gått ut” på den sidan, och loggen visar oauth.done_refused
med orsaken origin eller no_origin, är ett av de två fel.
Connect vägrar starta (avslutningskod 78) när dess konfiguration är öppen,
osäker eller halvfärdig, och skriver ut vilken variabel som är fel. En saknad
tillåtelselista, en http-adress utanför loopback, en felformaterad sigillnyckel
eller att både NAME och NAME_FILE är angivna stoppar den.
Kontrollpunkt: på varje server visar Connect-kortet Fungerar, och Var
varje inloggning körs nämner Connect för varje leverantör som du har
registrerat. cc_server connect status skriver ut Health: ok och samma spår.
Montera Connect i cc_server
Avsnitt med rubriken “Montera Connect i cc_server”En server kan själv vara värd för Connect i stället för en separat container. Den monterade tjänsten är samma som avbildningen kör.
- Lägg
CONNECT_*-variablerna i serverns.env-fil, som i steg 5. Servern vägrar starta när en Connect-hemlighet,CONNECT_SENTRY_DSNinräknad, är exporterad i dess miljö - Lägg till
CC_SERVER_CONNECT_HOST=on - Starta om servern. Dess logg skriver ut
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 serveras då på <server>/connect:
CONNECT_PUBLIC_URLär som standard ursprunget för serverns offentliga URL plus/connect. Ange den uttryckligen bakom en proxy. Sökvägen måste vara exakt/connect, och den måste vara HTTPS om den inte är loopback- Bara
CONNECT_*-variabler når den monterade tjänsten, så den lånar aldrig serverns egna leverantörsappar CONNECT_ALLOWED_INSTALLSkrävs fortfarande, även för servern som är värd- En felkonfigurerad montering hindrar servern från att starta i stället för att servera en öppen mäklare
- Demoservern monterar den aldrig
Registrera leverantörernas omdirigeringar mot https://<server>/connect och peka
sedan servrarna (även värden) mot den URL:en som i steg 3.
Konfigurationsreferens
Avsnitt med rubriken “Konfigurationsreferens”Varje inställning är en miljövariabel. Varje hemlighet kan i stället komma från
en monterad fil: ange NAME_FILE i stället för NAME. Connect läser om filen
högst var 30:e sekund och behåller det senaste fungerande värdet. Hemligheter
markerade dual accepterar också NAME_PREVIOUS (eller NAME_PREVIOUS_FILE)
under en rotation.
Adress och åtkomst
Avsnitt med rubriken “Adress och åtkomst”| Variabel | Standard | Betydelse |
|---|---|---|
CONNECT_PUBLIC_URL |
krävs | Den kanoniska offentliga URL:en. HTTPS, eller http bara på loopback. En sökväg innebär en montering. Ingen fråga eller fragment |
CONNECT_ALLOWED_INSTALLS |
krävs | Kommaseparerade installations-id:n. * accepteras bara tillsammans med CONNECT_SIGNED_CONFIG_FILE |
CONNECT_DENY_INSTALLS |
Installations-id:n som avvisas även när de är tillåtna | |
CONNECT_GITHUB_ALLOWED_OWNERS |
Numeriska GitHub-ägar-id:n. När den är angiven utfärdas repotoken bara för repos som de äger. Den begränsar inte vem som loggar in: en person som får använda denna Connect får ändå sin egen App-användartoken. Vill du betjäna en enda organisation, håll appen privat för den | |
CONNECT_GITHUB_REVIEW_BOT_INSTALLS |
Installations-id:n som får låta appens bot granska pull requests. Tom som standard; * nekas, och varje id måste också vara tillåtet |
|
CONNECT_HOST, CONNECT_PORT |
0.0.0.0, 8790 |
Bindningsadress och port |
CONNECT_TRUST_PROXY |
0 |
Betrodda proxyhopp i X-Forwarded-For (0 till 8). Används för gränserna per adress, sidan för inloggningsgodkännandets nätverkstips och den loggade adressen. Bakom en proxy räknar 0 varje klient som proxyn, och loggen säger det en gång |
Leverantörsspår
Avsnitt med rubriken “Leverantörsspår”| Variabel | Standard | Betydelse |
|---|---|---|
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID |
GitHub-appen | |
CONNECT_GITHUB_CLIENT_SECRET |
Hemlighet, dual | |
CONNECT_GITHUB_APP_PRIVATE_KEY |
Hemlighet. Appens privata nyckel (PEM) | |
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET |
Google-klienten. Hemligheten är dual | |
CONNECT_LINEAR_CLIENT_ID |
Linear-applikationen. Ingen hemlighet | |
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID |
Slack-appen | |
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET |
Hemligheter, dual | |
CONNECT_KLIPY_APP_KEY |
Nyckel för GIF-sökning i Klipy. Hemlighet, dual | |
CONNECT_KLIPY_MODE |
proxy |
proxy behåller nyckeln i Connect; key lämnar den till servrarna |
CONNECT_<LANE>_SECRET_GENERATION |
1 |
GitHub, Google och Slack: generationen som registreras i nya sigill |
CONNECT_<LANE>_MIN_SEAL_GENERATION |
1 |
GitHub, Google och Slack: äldre sigill måste logga in igen |
CONNECT_<LANE>_ACCEPTS_NEW |
true |
Varje spår: false stoppar nya inloggningar medan befintliga fortsätter att förnyas |
Sigill, tillstånd och lagring
Avsnitt med rubriken “Sigill, tillstånd och lagring”| Variabel | Standard | Betydelse |
|---|---|---|
CONNECT_SEAL_BACKEND |
local |
local eller gcp-kms |
CONNECT_SEAL_KEYS |
Hemlighet, krävs för local. Kommaseparerade kid:key-poster, nyaste först; äldre poster dekrypterar fortfarande |
|
CONNECT_KMS_KEY |
projects/…/locations/…/keyRings/…/cryptoKeys/…, krävs för gcp-kms |
|
CONNECT_STATE |
memory |
memory för en instans, redis för flera. En full minnesbutik nekar nya inloggningar och förfrågningar i stället för att glömma en levande post |
CONNECT_REDIS_URL |
Hemlighet. redis:// eller rediss://. Redis 6.2 eller senare med maxmemory-policy noeviction, båda kontrolleras vid start |
|
CONNECT_REDIS_CA_FILE |
CA-paket för rediss:// |
|
CONNECT_BINDINGS |
file |
Var bindningar till Slack-team finns: file eller firestore |
CONNECT_DATA_DIR |
data (/data i avbildningen) |
Innehåller bindings.json. Låst av en Connect: en andra Connect på samma katalog startar inte |
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE |
databasen (default) |
För CONNECT_BINDINGS=firestore. Connect startar inte när Firestore inte svarar |
Konfiguration, loggar och gränser
Avsnitt med rubriken “Konfiguration, loggar och gränser”| Variabel | Standard | Betydelse |
|---|---|---|
CONNECT_SIGNED_CONFIG_FILE |
En konfiguration signerad offline, serverad som den är. Används av Control Centers hostade Connect | |
CONNECT_CONFIG_PUBLIC_KEYS |
Nycklar som den signerade konfigurationen måste verifieras mot | |
CONNECT_CONFIG_EPOCH |
1 |
Epoken för konfigurationen som en egenhostad Connect genererar |
CONNECT_LOG_HMAC_KEY |
slumpmässig per process | Hemlighet. Ange den för att hålla taggarna som står för installations-id:n stabila över omstarter och instanser |
CONNECT_SENTRY_DSN |
Hemlighet. En https-Sentry-DSN som felrader rapporteras till: feltypen, stackramar, rutt och begär-id, aldrig ett meddelande, en kropp eller en header | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
Sentry-miljön |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
Rapporteras av /v1/version |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
Begäranden per installation |
CONNECT_RATE_IP_PER_MINUTE |
300 |
Begäranden per adress (en IPv6-adress räknas per /64) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
Begäranden för hela instansen |
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE |
600 |
Slack-händelse- och kommandoleveranser per adress, räknade separat från andra begäranden |
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND |
100 |
Slack-händelse- och kommandoleveranser för hela instansen |
CONNECT_RATE_SLACK_TEAM_PER_MINUTE |
600 |
Slack-händelser per team |
CONNECT_RATE_KLIPY_PER_MINUTE |
120 |
GIF-sökningar per installation |
CONNECT_RATE_KLIPY_IP_PER_MINUTE |
240 |
GIF-sökningar per adress, över alla servrar |
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES |
60 |
Startade inloggningar per adress |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR |
30 |
GitHub-tokens utfärdade per GitHub-konto på en server (inloggningar, förnyelser, repotokens) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
4 × ovanstående (120) |
Samma per GitHub-konto över alla servrar |
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR |
600 |
GitHub-tokens utfärdade per adress |
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR |
500 |
Nya GitHub-inloggningar för hela appen |
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR |
120 |
Bot-tokens per server |
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR |
240 |
Bot-tokens per frågande GitHub-konto, över servrar |
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR |
3000 |
Bot-tokens för hela appen |
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR |
1500 |
Förnyelser och repotokens för hela appen. Nya inloggningar har sin egen gräns ovan |
CONNECT_GITHUB_TOKEN_CAP_WARN |
10 |
Levande repotokens ett GitHub-konto får ha innan Connect loggar en varning |
CONNECT_RATE_RETIRE_IP_PER_HOUR |
10 |
Retirerade installations-id:n per adress (per /48 för IPv6) |
Ett anrop över en gräns besvaras med rate_limited. Servrar försöker igen senare och loggar aldrig ut någon för det.
Kör mer än en instans
Avsnitt med rubriken “Kör mer än en instans”En instans med CONNECT_STATE=memory räcker för de flesta organisationer. Flera
instanser bakom en adress behöver CONNECT_STATE=redis och CONNECT_BINDINGS=firestore,
så att en inloggning som startade på en instans kan slutföras på en annan och varje
instans ser samma Slack-bindningar och retirerade installations-id:n. En delad
CONNECT_DATA_DIR fungerar inte: den första Connect låser den. Gränserna per
installation, per adress och för instansens förfrågningar gäller per instans; gränserna
för inloggningar, GitHub-tokens, bot-tokens, GIF-sökningar per adress, retirering och
Slack-team delas genom tillståndslagret.
Rotera en leverantörshemlighet
Avsnitt med rubriken “Rotera en leverantörshemlighet”Ingen loggas ut:
- Skapa den nya hemligheten hos leverantören och behåll den gamla
- Flytta det gamla värdet till
NAME_PREVIOUS, lägg det nya iNAMEoch höjCONNECT_<LANE>_SECRET_GENERATION. Monterade filer plockas upp inom 30 sekunder - Vänta tills inloggningarna har förnyats, ta sedan bort den gamla hemligheten
hos leverantören och ta bort
NAME_PREVIOUS
För att rotera en sigillnyckel lägger du en ny cc-connect-config seal-key-post
först i CONNECT_SEAL_KEYS och behåller den gamla posten tills dess sigill har
förnyats.
Ändra en app
Avsnitt med rubriken “Ändra en app”Servrarna kommer ihåg app- och klient-id:na som din Connect annonserade första gången de använde den. Om du byter ut en app visar Connect-kortet på varje server Connects appar har ändrats, och inloggningar via Connect pausas tills ägaren trycker på Lita på nya appar. Säg till serverägarna innan du byter, så att de vet att meddelandet kommer från dig.
Blockera en server
Avsnitt med rubriken “Blockera en server”Lägg till dess installations-id i CONNECT_DENY_INSTALLS och starta om. Ägaren
ser ”Connect har blockerat den här serverns installations-id. Kontakta den som driver din Connect-server.”, och varje
Connect-inloggning på den stoppas.
En server retirerar också sitt eget gamla installations-id när dess ägare roterar nyckeln. Den bevisar att id:t är dess eget med ett enda inloggningssigill som den här Connect gjorde åt den, så bara en server som har loggat in någon kan retirera ett id. Connect behåller retirerade id:n för gott, så den gamla nyckeln och varje sigill som gjorts för den slutar fungera, och Connect släpper de Slack-arbetsytor som var bundna till det gamla id:t. Tokens som redan har utfärdats går ut av sig själva: inom 8 timmar för en persons, 1 timme för en bots. Connect håller högst 100 000 retirerade id:n; över det vägras en rotation, och loggen säger det på felnivå.
Felsökning
Avsnitt med rubriken “Felsökning”En server säger att Connect har blockerat den
Avsnitt med rubriken “En server säger att Connect har blockerat den”Dess installations-id finns inte i CONNECT_ALLOWED_INSTALLS, det finns i
CONNECT_DENY_INSTALLS, eller så retirerades det av en nyckelrotation. Id:t ändras när
ägaren byter nyckeln; be om det nya.
Alla inloggningar till en leverantör misslyckas
Avsnitt med rubriken “Alla inloggningar till en leverantör misslyckas”En av dess variabler kanske saknas, så Connect utelämnade spåret. Kontrollera startloggen och tabellerna ovan. GitHub behöver alla fem: app-ID, slug, klient-ID, klienthemlighet och privat nyckel; Google behöver både klient-ID och hemlighet.
Inloggningar misslyckas med en omdirigeringskonflikt
Avsnitt med rubriken “Inloggningar misslyckas med en omdirigeringskonflikt”Omdirigeringen som registrerats hos leverantören stämmer inte exakt med
CONNECT_PUBLIC_URL. Jämför schema, värd, port och, för en monterad Connect,
sökvägen /connect.
Alla var tvungna att logga in igen
Avsnitt med rubriken “Alla var tvungna att logga in igen”Sigillnyckeln ändrades eller förlorades, en server bytte sin nyckel, eller en servers data återställdes på en annan maskin. En förseglad inloggningsuppgift öppnas bara för den installation och den Connect som skapade den.