Kjør en Connect-server
Control Center Connect kjører leverandørpålogginger (GitHub, Google Calendar, Linear, Slack) for servere som ikke har registrert egne apper. Denne veiledningen viser deg hvordan du kjører din egen Connect, slik at leverandørappene, hemmelighetene deres og listen over servere som får bruke dem, blir hos deg.
Hva Connect kan og ikke kan se, står i Connect-referansen. Les den først hvis du vurderer om du skal kjøre en.
Forutsetninger
Seksjon med tittelen «Forutsetninger»- En offentlig HTTPS-adresse for Connect, for eksempel
https://connect.example.com, bak en proxy som terminerer TLS. Vanlighttpgodtas bare på loopback - Docker, eller en
cc_serverdu kan starte på nytt med ekstra miljøvariabler - Tillatelse til å registrere apper hos hver leverandør du vil betjene
- Serverne som skal bruke den, med eierne deres for hånden: hver av dem har en installasjons-ID som du legger til i Connects tillatelsesliste
Trinn 1: Velg adressen
Seksjon med tittelen «Trinn 1: Velg adressen»Velg URL-en nå og behold den. CONNECT_PUBLIC_URL er en del av alt Connect gjør:
forespørselssignaturer, forseglet påloggingsinformasjon, leverandørenes
omdirigerings-URL-er og hver servers installasjons-ID er bundet til den. Å endre
den senere betyr å registrere omdirigeringene på nytt og at alle må logge inn på
nytt.
Trinn 2: Registrer leverandørappene
Seksjon med tittelen «Trinn 2: Registrer leverandørappene»Registrer bare leverandørene du vil betjene. En leverandør der variablene er
ufullstendige, utelates fra Connects konfigurasjon, og serverne ser den som
utilgjengelig. <base> nedenfor er din CONNECT_PUBLIC_URL.
| Leverandør | Registrer | Behold |
|---|---|---|
| GitHub App | Callback-URL <base>/oauth/github/callback. Setup-URL <base>/oauth/github/setup med Redirect on update slått på. La Request user authorization (OAuth) during installation være av: når den er på, ignorerer GitHub setup-URL-en. La Expire user authorization tokens stå på |
App-id, slug, client id, client secret, en privat nøkkel |
En OAuth-klient av typen Nettapplikasjon med omdirigerings-URI <base>/oauth/google/callback, og Google Calendar API aktivert |
Client id, client secret | |
| Linear | En OAuth-applikasjon med callback-URL-ene <base>/oauth/linear/callback og <base>/oauth/linear_app/callback |
Bare client id |
| Slack | Omdirigerings-URL-er <base>/oauth/slack_oidc/callback og <base>/oauth/slack/callback. Event Subscriptions på <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash-kommandoer på <base>/v1/hooks/slack/commands. Tokenrotasjon på |
App-id, client id, client secret, signing secret |
Gi GitHub App-en disse repotillatelsene: Metadata les, Contents les og skriv, Pull requests les og skriv, Issues les og skriv, Checks, Actions og Commit statuses les. Legg til Members for organisasjonen med lesetilgang for forespørsler om gjennomgang fra team. Webhooks kan være av: serverne poller.
Connect trenger den private nøkkelen til GitHub-appen (Generate a private key i appens innstillinger). Den signerer appens forespørsler som finner installasjonen som dekker et repo (eller, når repoet ikke har en, eierens installasjon) og utsteder et installasjonstoken for ett repo, hver bare etter at personen som spør, har bevist tilgang til repoet med sin egen pålogging.
Hver server på Connect-en din deler appens bot. Den kan lese, kommentere, sette etiketter og reagere som boten for alle dem. Å gjennomgå pull requests som boten er bare tillatt for serverne du lister i CONNECT_GITHUB_REVIEW_BOT_INSTALLS (installasjons-ID-ene deres, kommaseparert); alle andre servere publiserer gjennomganger med reviewerens egen token. Å pushe gjøres aldri som boten. For å la en server du eier, gjennomgå som boten, legg til installasjons-ID-en der og start på nytt. Behandle nøkkelfilen som en hemmelighet, som forseglingsnøkkelen. Linear trenger heller ingen hemmelighet: Connect gir koden tilbake til serveren, som fullfører utvekslingen selv.
Trinn 3: Samle inn installasjons-ID-ene
Seksjon med tittelen «Trinn 3: Samle inn installasjons-ID-ene»Connect svarer bare serverne på tillatelseslisten sin. På hver server peker du den mot Connect-en din og leser deretter av installasjons-ID-en:
- Gå til Innstillinger → Server → Enkel pålogging, åpne kortet Control Center Connect og velg Bruk en egen Connect-server
- Skriv inn URL-en din og lagre. Kortet viser serverens Installasjons-ID
Fra en terminal på serververten er det samme:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus skriver ut installasjons-ID-en. Den viser install_blocked til trinn 5
er fullført, og det er forventet.
En installasjons-ID avledes per Connect-adresse, så samme server har en annen ID for hver Connect den snakker med. Den endres bare når eieren bytter nøkkelen.
Trinn 4: Lag en seglnøkkel
Seksjon med tittelen «Trinn 4: Lag en seglnøkkel»Connect krypterer all påloggingsinformasjon den gir tilbake, med en seglnøkkel. Lag en og oppbevar den som en hemmelig fil:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysMister du seglnøkkelen, blir alle logget ut: ingen segl kan åpnes uten den.
Trinn 5: Start containeren
Seksjon med tittelen «Trinn 5: Start containeren»Hver utgivelse publiserer ghcr.io/samuelalev/cc-connect med byggeopprinnelse.
Fest en versjonstagg i produksjon.
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:latestPek reverse proxyen din mot port 8790, og sett CONNECT_TRUST_PROXY til antall proxyer foran Connect, slik at grensen per adresse ser hver klients adresse. Imaget kjører som en bruker uten privilegier, lagrer tilstanden sin i volumet /data og har en innebygd helsesjekk (cc-connect --healthcheck, som sjekker /healthz: prosessen svarer). /readyz sjekker også at tilstands- og bindingslagrene svarer, og at Redis, når den brukes, fortsatt kjører maxmemory-policy noeviction; pek en orkestrators klarhetssjekk dit.
Samtykkesiden for pålogging svarer med et skjema-post som Connect bare godtar fra sin egen side: Sec-Fetch-Site, når den sendes, må være same-origin, og Origin, når den sendes, må være opprinnelsen til CONNECT_PUBLIC_URL; en post med ingen av dem avvises. Proxyen må derfor sende begge headerne uendret videre, og CONNECT_PUBLIC_URL må være adressen folks nettlesere faktisk bruker. Hvis det å fortsette på den siden alltid viser «Denne lenken har utløpt», og loggen viser oauth.done_refused med årsak origin eller no_origin, er én av disse to feil.
Connect nekter å starte (avslutningskode 78) når konfigurasjonen er åpen,
utrygg eller halvferdig, og skriver ut hvilken variabel som er feil. En manglende
tillatelsesliste, en http-adresse utenfor loopback, en feilformatert
seglnøkkel eller at både NAME og NAME_FILE er satt, stopper den.
Sjekkpunkt: på hver server viser Connect-kortet Fungerer, og Hvor hver
pålogging kjøres nevner Connect for hver leverandør du har registrert.
cc_server connect status skriver ut Health: ok og de samme sporene.
Monter Connect i cc_server
Seksjon med tittelen «Monter Connect i cc_server»En server kan selv være vert for Connect i stedet for en separat container. Den monterte tjenesten er den samme som imaget kjører.
- Legg
CONNECT_*-variablene i serverens.env-fil, som i trinn 5. Serveren nekter å starte når en Connect-hemmelighet, inkludertCONNECT_SENTRY_DSN, er eksportert i miljøet - Legg til
CC_SERVER_CONNECT_HOST=on - Start serveren på nytt. Loggen 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 serveres da på <server>/connect:
CONNECT_PUBLIC_URLer som standard opprinnelsen til serverens offentlige URL pluss/connect. Sett den eksplisitt bak en proxy. Stien må være nøyaktig/connect, og den må være HTTPS med mindre den er loopback- Bare
CONNECT_*-variabler når den monterte tjenesten, så den låner aldri serverens egne leverandørapper CONNECT_ALLOWED_INSTALLSer fortsatt påkrevd, også for serveren som er vert- En feilkonfigurert montering stopper serveren fra å starte i stedet for å servere en åpen megler
- Demoserveren monterer den aldri
Registrer leverandørenes omdirigeringer mot https://<server>/connect, og pek
deretter serverne (inkludert verten) mot den URL-en som i trinn 3.
Konfigurasjonsreferanse
Seksjon med tittelen «Konfigurasjonsreferanse»Hver innstilling er en miljøvariabel. Enhver hemmelighet kan i stedet komme fra
en montert fil: sett NAME_FILE i stedet for NAME. Connect leser filen på nytt
høyst hvert 30. sekund og beholder den siste gode verdien. Hemmeligheter merket
dual godtar også NAME_PREVIOUS (eller NAME_PREVIOUS_FILE) under en
rotasjon.
Adresse og tilgang
Seksjon med tittelen «Adresse og tilgang»| Variabel | Standard | Betydning |
|---|---|---|
CONNECT_PUBLIC_URL |
påkrevd | Den kanoniske offentlige URL-en. HTTPS, eller http bare på loopback. En sti betyr en montering. Ingen spørring eller fragment |
CONNECT_ALLOWED_INSTALLS |
påkrevd | Kommaseparerte installasjons-ID-er. * godtas bare sammen med CONNECT_SIGNED_CONFIG_FILE |
CONNECT_DENY_INSTALLS |
Installasjons-ID-er som avvises selv når de er tillatt | |
CONNECT_GITHUB_ALLOWED_OWNERS |
Numeriske GitHub-eier-ID-er. Når den er satt, utstedes repotokener bare for repoer de eier. Den begrenser ikke hvem som logger inn: en person som har lov til å bruke denne Connect, får fortsatt sitt eget brukertoken for appen. For å betjene bare én organisasjon, hold appen privat for den | |
CONNECT_GITHUB_REVIEW_BOT_INSTALLS |
Installasjons-ID-er som kan la appens bot gjennomgå pull requests. Tom som standard; * avvises, og hver ID må også være tillatt |
|
CONNECT_HOST, CONNECT_PORT |
0.0.0.0, 8790 |
Bindingsadresse og port |
CONNECT_TRUST_PROXY |
0 |
Klarerte proxyhopp i X-Forwarded-For (0 til 8). Brukes til grensene per adresse, nettverkshintet på påloggingssiden og den loggførte adressen. Bak en proxy teller 0 hver klient som proxyen, og loggen sier det én gang |
Leverandørspor
Seksjon med tittelen «Leverandørspor»| Variabel | Standard | Betydning |
|---|---|---|
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID |
GitHub App-en | |
CONNECT_GITHUB_CLIENT_SECRET |
Hemmelighet, dual | |
CONNECT_GITHUB_APP_PRIVATE_KEY |
Hemmelighet. Appens private nøkkel (PEM) | |
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET |
Google-klienten. Hemmeligheten er dual | |
CONNECT_LINEAR_CLIENT_ID |
Linear-applikasjonen. Ingen hemmelighet | |
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID |
Slack-appen | |
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET |
Hemmeligheter, dual | |
CONNECT_KLIPY_APP_KEY |
Nøkkel for GIF-søk i Klipy. Hemmelighet, dual | |
CONNECT_KLIPY_MODE |
proxy |
proxy holder nøkkelen i Connect; key gir den til serverne |
CONNECT_<LANE>_SECRET_GENERATION |
1 |
GitHub, Google og Slack: generasjonen som registreres i nye segl |
CONNECT_<LANE>_MIN_SEAL_GENERATION |
1 |
GitHub, Google og Slack: eldre segl må logge inn på nytt |
CONNECT_<LANE>_ACCEPTS_NEW |
true |
Hvert spor: false stopper nye pålogginger mens eksisterende fortsetter å fornyes |
Segl, tilstand og lagring
Seksjon med tittelen «Segl, tilstand og lagring»| Variabel | Standard | Betydning |
|---|---|---|
CONNECT_SEAL_BACKEND |
local |
local eller gcp-kms |
CONNECT_SEAL_KEYS |
Hemmelighet, påkrevd for local. Kommaseparerte kid:key-oppføringer, nyeste først; eldre oppføringer dekrypterer fortsatt |
|
CONNECT_KMS_KEY |
projects/…/locations/…/keyRings/…/cryptoKeys/…, påkrevd for gcp-kms |
|
CONNECT_STATE |
memory |
memory for én instans, redis for flere. En full minnelagring avviser nye pålogginger og forespørsler i stedet for å glemme en levende oppføring |
CONNECT_REDIS_URL |
Hemmelighet. redis:// eller rediss://. Redis 6.2 eller nyere med maxmemory-policy noeviction, begge sjekkes ved oppstart |
|
CONNECT_REDIS_CA_FILE |
CA-pakke for rediss:// |
|
CONNECT_BINDINGS |
file |
Hvor bindinger til Slack-team ligger: file eller firestore |
CONNECT_DATA_DIR |
data (/data i imaget) |
Inneholder bindings.json. Låst av én Connect: en andre Connect på samme katalog starter ikke |
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE |
databasen (default) |
For CONNECT_BINDINGS=firestore. Connect starter ikke når Firestore ikke svarer |
Konfigurasjon, logger og grenser
Seksjon med tittelen «Konfigurasjon, logger og grenser»| Variabel | Standard | Betydning |
|---|---|---|
CONNECT_SIGNED_CONFIG_FILE |
En konfigurasjon signert offline, servert som den er. Brukes av den hostede Connect-tjenesten til Control Center | |
CONNECT_CONFIG_PUBLIC_KEYS |
Nøkler den signerte konfigurasjonen må verifiseres mot | |
CONNECT_CONFIG_EPOCH |
1 |
Epoken til konfigurasjonen en selvhostet Connect genererer |
CONNECT_LOG_HMAC_KEY |
tilfeldig per prosess | Hemmelighet. Sett den for å holde merkene som står for installasjons-ID-er, stabile på tvers av omstarter og instanser |
CONNECT_SENTRY_DSN |
Hemmelighet. En https-Sentry-DSN som feillinjer rapporteres til: feiltypen, stakkrammer, rute og forespørsels-id, aldri en melding, kropp eller header | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
Sentry-miljøet |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
Rapporteres av /v1/version |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
Forespørsler per installasjon |
CONNECT_RATE_IP_PER_MINUTE |
300 |
Forespørsler per adresse (en IPv6-adresse teller per /64) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
Forespørsler for hele instansen |
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE |
600 |
Slack-hendelser og -kommandoleveringer per adresse, talt separat fra andre forespørsler |
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND |
100 |
Slack-hendelser og -kommandoleveringer for hele instansen |
CONNECT_RATE_SLACK_TEAM_PER_MINUTE |
600 |
Slack-hendelser per team |
CONNECT_RATE_KLIPY_PER_MINUTE |
120 |
GIF-søk per installasjon |
CONNECT_RATE_KLIPY_IP_PER_MINUTE |
240 |
GIF-søk per adresse, på tvers av servere |
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES |
60 |
Pålogginger startet per adresse |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR |
30 |
GitHub-tokener utstedt per GitHub-konto på én server (pålogginger, fornyelser, repotokener) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
4 × over (120) |
Det samme per GitHub-konto på tvers av alle servere |
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR |
600 |
GitHub-tokener utstedt per adresse |
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR |
500 |
Nye GitHub-pålogginger for hele appen |
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR |
120 |
Bot-tokener per server |
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR |
240 |
Bot-tokener per spørrende GitHub-konto, på tvers av servere |
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR |
3000 |
Bot-tokener for hele appen |
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR |
1500 |
Fornyelser og repotokener for hele appen. Nye pålogginger har sin egen grense over |
CONNECT_GITHUB_TOKEN_CAP_WARN |
10 |
Levende repotokener én GitHub-konto kan ha før Connect logger en advarsel |
CONNECT_RATE_RETIRE_IP_PER_HOUR |
10 |
Installasjons-ID-er pensjonert per adresse (per /48 for IPv6) |
Et kall som går over en grense, får svaret rate_limited. Servere prøver igjen senere og logger aldri noen ut på grunn av det.
Kjør mer enn én instans
Seksjon med tittelen «Kjør mer enn én instans»Én instans med CONNECT_STATE=memory er nok for de fleste organisasjoner. Flere
instanser bak én adresse trenger CONNECT_STATE=redis og CONNECT_BINDINGS=firestore, slik at en pålogging som startet på én instans, kan fullføres på en annen, og alle instanser ser de samme Slack-bindingene og pensjonerte installasjons-ID-ene. En delt CONNECT_DATA_DIR fungerer ikke: den første Connect låser den. Forespørselsgrensene per installasjon, per adresse og per instans er per instans; grensene for pålogginger, GitHub-tokener, bot-tokener, GIF-søk per adresse, pensjoneringer og Slack-team deles gjennom tilstandslageret.
Roter en leverandørhemmelighet
Seksjon med tittelen «Roter en leverandørhemmelighet»Ingen blir logget ut:
- Opprett den nye hemmeligheten hos leverandøren og behold den gamle
- Flytt den gamle verdien til
NAME_PREVIOUS, legg den nye iNAME, og økCONNECT_<LANE>_SECRET_GENERATION. Monterte filer plukkes opp innen 30 sekunder - Vent til påloggingene er fornyet, slett deretter den gamle hemmeligheten hos
leverandøren og fjern
NAME_PREVIOUS
For å rotere en seglnøkkel legger du en ny cc-connect-config seal-key-oppføring
først i CONNECT_SEAL_KEYS og beholder den gamle oppføringen til seglene dens er
fornyet.
Endre en app
Seksjon med tittelen «Endre en app»Serverne husker app- og client-id-ene Connect-en din kunngjorde første gang de brukte den. Hvis du bytter ut en app, viser Connect-kortet på hver server Appene til Connect er endret, og pålogginger via Connect settes på pause til eieren trykker Stol på nye apper. Si fra til servereierne før du bytter, slik at de vet at meldingen kommer fra deg.
Blokker en server
Seksjon med tittelen «Blokker en server»Legg installasjons-ID-en til i CONNECT_DENY_INSTALLS og start på nytt. Eieren
ser «Connect har blokkert installasjons-ID-en til denne serveren. Kontakt den som driver Connect-serveren din.», og hver
Connect-pålogging på den stopper.
En server pensjonerer også sin egen gamle installasjons-ID når eieren bytter nøkkel. Den beviser at ID-en er dens egen med ett seglet legitimasjon som denne Connect laget for den, så bare en server som har logget noen inn, kan pensjonere en ID. Connect beholder pensjonerte ID-er for godt, så den gamle nøkkelen og hvert segl laget for den slutter å virke, og Slack-arbeidsområdene bundet til den gamle ID-en frigjøres. Tokener som allerede er utstedt, utløper av seg selv: innen 8 timer for en persons, og 1 time for en bots. Connect holder høyst 100 000 pensjonerte ID-er; over det avvises en bytte av nøkkel, og loggen sier det på feilnivå.
Feilsøking
Seksjon med tittelen «Feilsøking»En server sier at Connect har blokkert den
Seksjon med tittelen «En server sier at Connect har blokkert den»Installasjons-ID-en står ikke i CONNECT_ALLOWED_INSTALLS, den står i CONNECT_DENY_INSTALLS, eller den ble pensjonert av en nøkkelbytte. ID-en endres når eieren bytter nøkkelen; be om den nye.
Alle pålogginger til én leverandør feiler
Seksjon med tittelen «Alle pålogginger til én leverandør feiler»En av variablene kan mangle, så Connect utelot sporet. Sjekk oppstartsloggen og tabellene over. GitHub trenger alle fem: app-id, slug, client id, client secret og privat nøkkel; Google trenger både client id og hemmelighet.
Pålogginger feiler med en omdirigeringsfeil
Seksjon med tittelen «Pålogginger feiler med en omdirigeringsfeil»Omdirigeringen som er registrert hos leverandøren, samsvarer ikke nøyaktig med
CONNECT_PUBLIC_URL. Sammenlign skjema, vert, port og, for en montert Connect,
stien /connect.
Alle måtte logge inn på nytt
Seksjon med tittelen «Alle måtte logge inn på nytt»Seglnøkkelen ble endret eller mistet, en server byttet nøkkelen sin, eller dataene til en server ble gjenopprettet på en annen maskin. Forseglet påloggingsinformasjon åpnes bare for installasjonen og den Connect som laget den.