Hoppa till innehåll

Referens för Control Center Connect

Control Center Connect kör leverantörsinloggningar för servrar som inte har registrerat egna appar. En server använder antingen Control Centers hostade Connect, en Connect som organisationen kör (Kör en Connect-server), eller ingen alls. Valet görs under Inställningar → Server → Enkel inloggning → Control Center Connect, med cc_server connect eller med CC_CONNECT_URL. En arbetsyta följer det, om inte en administratör valt något annat för just den arbetsytan under Inställningar → Arbetsyta → Integrationer (Arbetsytans eget val).

Under Använd mina egna appar (eller innan någon har valt) körs ett spår på serverns egen app när en sådan är fullständigt konfigurerad, annars är det otillgängligt. Med Control Center Connect eller en egen Connect betjänar Connect varje spår det hanterar: serverns egna appar förblir sparade men används inte, varken för inloggningar, serverautomatisering eller den status servern rapporterar. En arbetsyta som valt ett eget läge kör varje spår enligt det valet i stället.

Spår En egen app behöver Via Connect
github App-ID, privat nyckel, klient-ID och klienthemlighet Personer loggar in i den delade GitHub-appen
google Klient-ID och klienthemlighet Personer ansluter Google Calendar
linear Klient-ID Personer loggar in på Linear
linear_app Klient-ID En administratör för arbetsytan ansluter Linears appaktör
slack En arbetsytas egen anslutning till en Slack-app En administratör för arbetsytan ansluter Slack till den delade Slack-appen
klipy KLIPY_APP_KEY GIF-sökning, med Connect som proxy

En egen app som bara är delvis konfigurerad gör sitt spår till ett fel, aldrig till en tyst återgång till Connect. En arbetsyta som väljer Använd mina egna appar går aldrig via serverns appar eller någon Connect, för någon leverantör. Byte av serverns Connect-val loggar ingen ut från en arbetsyta som gjort ett eget val.

Connect ser Connect ser aldrig
Serverns installations-id och begärandesignaturer Källkod, repoinnehåll, diffar eller text i pull requests
Leverantörskontot som loggade in, under inloggningen Ärenden, transkript eller något i en arbetsytas databas
Vilken arbetsyta en inloggningsuppgift tillhör, som ett ogenomskinligt id inuti sigillet Serverns egna app-hemligheter: de lämnar aldrig servern
Repot som en GitHub-token för ett enda repo utfärdas för Uppdateringstoken i vila: de finns bara inuti sigill som servern behåller
Slack-teamet bundet till servern Linear-hemligheter: servern byter själv Linears kod
GIF-söktermer, när den är proxy för Klipy Lösenord, parkopplingsnycklar eller nycklar till modelleverantörer
Referenser till Slack-händelser (team, kanal, meddelande-id) och text i slash-kommandon Text i Slack-meddelanden: Connect släpper den när den kommer in, och servern läser meddelandet direkt från Slack

Connect behåller påbörjade inloggningar, nonces och cachar i högst 10 minuter, och timvisa användningsräknare i högst två timmar. En GitHub-token för ett enda repo som utfärdats som person ligger kvar registrerad, förseglad till inloggningen som bad om den, tills den går ut (högst 8 timmar), så att Connect kan lämna ut den igen och återkalla den vid frånkoppling. Dess enda varaktiga poster är Slack-bindningar (vilken server varje Slack-team är bundet till) och utfasade installations-id:n. Fel bär en kod, aldrig leverantörens svar. Loggarna registrerar installations-id:n bara som nyckelade hashar, och en GitHub-token bara som den hashed_token som GitHubs granskningslogg för organisationen visar för den, så att en organisationsägare kan matcha de två.

Läge Inställning Beteende
Ej angivet Ny server Inget spår använder Connect. Introduktionen ber serverns ägare att välja
hosted Använd Control Centers appar https://connect.usectrl.dev, med en konfiguration som signerats offline. Serverns egna appar används inte
custom Använd en egen Connect-server En Connect på en HTTPS-URL (http bara på loopback), betrodd vid första användningen. Serverns egna appar används inte
off Använd mina egna appar Inget spår använder Connect. Bara egna appar loggar in personer

CC_CONNECT_URL i serverns miljö eller .env låser valet: hosted, off eller en Connect-URL. Inställningarna visar då låset och kan inte ändra det.

Den här byggnaden har ingen nyckel för den hostade konfigurationen inkompilerad, så hostat läge rapporterar hosted_unprovisioned och betjänar inget spår. Egna appar och en egen Connect fungerar.

Den hostade Connect körs i en enda container. Dess sigillnyckel och den delade GitHub-appens privata nyckel är miljövariabler där, inte nycklar i ett valv som bara signerar eller dekrypterar, som GitHub rekommenderar för en apps privata nyckel. Det är en känd brist i den nuvarande uppställningen.

En server läser Connects konfiguration högst var 10:e minut och väntar högst 5 sekunder på varje anrop. När Connect inte går att nå används den senaste fungerande konfigurationen, och inställningarna markerar den som inaktuell.

Inställningar → Arbetsyta → Integrationer → Control Center Connect åsidosätter serverns val för en arbetsyta. Varje medlem ser det och var varje inloggning körs; bara en administratör för arbetsytan ändrar det.

Val Beteende
Samma som den här servern Standardvalet. Arbetsytan kör på det serverägaren valt; alternativet anger vilket det är
Använd Control Centers appar Control Centers hostade Connect, oavsett vad servern använder
Använd mina egna appar Bara arbetsytans egna appar: dess GitHub-app, Google-klient, Linear-applikation, Klipy-nyckel och Slack-app. En leverantör utan egen app är av här; en delvis konfigurerad är ett installationsfel
Använd en egen Connect-server En Connect på en HTTPS-adress som arbetsytan anger. Adresser på ett privat eller lokalt nätverk avvisas
  • Alla val utom Samma som den här servern håller varje persons GitHub- och Linear-inloggningar i en egen plats för arbetsytan, så de aldrig blandas med de serveromfattande
  • Byte frågar först: alla i arbetsytan loggar in på GitHub, Linear och Google Calendar igen via de nya apparna
  • Arbetsytans egna Slack-appanslutning fungerar under alla val; Lägg till Control Center i Slack följer valet
  • CC_CONNECT_URL låser också ute arbetsytor från en egen Connect: de kan följa servern eller använda sina egna appar
  • En arbetsytas egna Connect litas på första användningen för just den arbetsytan: Lita på nya appar där ändrar aldrig vad servern eller någon annan arbetsyta litar på
Post Vad det är
Installationsnyckel Ett frö på 32 byte i serverns hemlighetsfil (connect_install_key), skilt från nycklarna för enhetsparkoppling
Nyckel per Connect En Ed25519-nyckel härledd från fröet och Connects adress. Varje begäran till Connect signeras med den (RFC 9421)
Installations-id 26 tecken härledda från den publika nyckeln. Visas i inställningarna och av cc_server connect status

Samma server har ett annat installations-id för varje Connect-adress. Id:t ändras bara när nyckeln byts.

En inloggning via Connect returnerar ett sigill för inloggningsuppgiften: en krypterad blob som bara den Connect som skapade den kan öppna. Den är bunden till leverantören, Connect-adressen, installations-id:t, arbetsytan, leverantörskontot, appen och hemlighetens generation.

  • Servern lagrar sigillet och installations-id:t det förseglades för. Åtkomsttoken stannar i minnet
  • För att förnya skickar servern tillbaka sigillet och får en ny åtkomsttoken och ett nytt sigill
  • Ett sigill vars installations-id eller Connect-adress inte längre stämmer tas bort nästa gång det läses, och den personen loggar in igen. Det händer efter ett nyckelbyte, ett byte till en annan Connect, eller en datakatalog som återställts på en annan server
  • Ett sigill som Connect inte kan öppna avvisas med access_denied

En installation av den delade GitHub-appen kan användas från varje server. Connect för ingen förteckning över vilken server som får använda den.

  • Installera GitHub-appen under Inställningar → Arbetsyta → Integrationer öppnar appens installationssida på GitHub. Servern bygger länken från appens namn i Connects konfiguration
  • En token för ett enda repo kräver att appen är installerad hos repots ägare och att den inloggade personen har åtkomst till repot. Det är personens egen token, begränsad till personens roll, aldrig mer
  • En organisation begränsar Control Center på GitHub: genom att ta bort installationen, begränsa repos eller ta bort personen
  • För anrop som bara personen kan göra, som att lista dess installationer, ger Connect servern personens egna App-användartoken, inte en token för ett enda repo. Att logga in på en server är att lita på den servern med den token
  • En organisation som tillämpar en IP-tillåtelselista för GitHub kan inte använda den hostade Connect, vars adresser inte är fasta. Den registrerar i stället sin egen GitHub-app, på sina servrar eller på en Connect den kör
  • Koppla från återkallar bara den inloggningen: Connect använder sin uppdateringstoken en gång och tar bort det som den ger tillbaka, tar bort sin användartoken och de tokens för ett enda repo som Connect utfärdat åt den. En kopia av dess sigill som någonstans sparats slutar fungera. Personens inloggningar på andra servrar och arbetsytor fortsätter att fungera. För att ta bort Control Center från ett GitHub-konto helt, återkalla det på GitHub under Settings → Applications → Authorized GitHub Apps → Revoke

Tokens utfärdade som appens bot (as: app) visar samma bot på GitHub för varje server som använder samma Connect: GitHub kan inte skilja de servrarna åt.

  • Varje server får låta boten läsa och kommentera: read, review och comment (kommentarer, etiketter, tilldelningar och reaktioner på ärenden och pull requests)
  • Att granska en pull request som boten (bot, som skriver pull requests) är bara tillåtet för servrar som Connect-operatören listar i CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Varje annan server får svaret needs_requester och publicerar granskningen med den ansvariga personens egen token, som GitHub begränsar till den personen: granskningen visas under hens namn. Det gäller publicering av AI-granskning, granskningskommentarer och granskarbegäranden
  • Att pusha, skapa en gren och öppna en pull request (write) utfärdas aldrig som den delade boten. De använder alltid den begärandes egen inloggning
  • Att godkänna en pull request är aldrig automatiserat, med någon token
  • En server eller arbetsyta med en egen GitHub-app behåller boten för allt detta, granskningar inräknade
  • En server som någon loggar in på håller deras App-användartoken: upp till 8 timmar per token, förnyad tills de kopplar från. Den kan agera som dem på varje repo som den delade appen är installerad på och som de kan nå. Connect kan stänga av en server för gott (en utfasad eller nekad installation), men en token som redan lämnats ut förblir giltig tills den går ut
  • Att installera den delade GitHub-appen på en organisation ger samtycke för varje Control Center-server som någon medlem loggar in på, inte för en server
  • Boten är delad, enligt ovan: en organisation kan inte se på GitHub vilken server som agerade som boten
  • En organisation som vill ha en egen gräns registrerar sin egen GitHub-app och kör sin egen Connect (Kör en Connect-server), eller konfigurerar appen på sina egna servrar
Connect Hur servern litar på dess konfiguration
Hostad Verifierar en Ed25519-signatur mot nycklar som är inkompilerade i byggnaden. Avvisar en epok som är lägre än den högsta den har sett (rollback)
Egen Låser GitHub-appens app-ID och klient-ID, klient-id:na för Google och Linear, och Slack-appens app- och klient-id:n vid första användningen. En ändring pausar Connect-inloggningar (pins_changed) tills serverns ägare trycker på Lita på nya appar

Serverns Connect-inställningar är bara för serverns ägare.

Åtgärd Gör
connect.status Läge, URL, lås, installations-id, hälsa, konfigurationens epok och varje spårs källa
connect.configure Anger hosted, custom (med url) eller off
connect.test Hämtar konfigurationen igen och rapporterar hälsan
connect.confirmPins Godtar en egen Connects ändrade identifierare
connect.rotateKey Skapar en ny installationsnyckel och ett nytt installations-id (force ersätter det även när en Connect inte kunde fasa ut den gamla); se Byt installationsnyckeln

Arbetsytans eget val har egna åtgärder, som var och en anger arbetsytan:

Åtgärd Vem Gör
workspaceConnect.status Vilken medlem som helst Valet, vad det löser till, hälsa och varje leverantörs källa. Installations-id och väntande fästen bara för administratörer
workspaceConnect.set Administratör för arbetsytan Anger inherit, hosted, custom (med url) eller own
workspaceConnect.test Administratör för arbetsytan Hämtar arbetsytans Connect-konfiguration igen och rapporterar hälsan
workspaceConnect.confirmPins Administratör för arbetsytan Godtar arbetsytans egna Connect-servers ändrade identifierare

Själva inloggningarna använder oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections och oauth.disconnect. Personen är alltid den inloggade anroparen.

  1. Servern ber Connect att starta spåret och får leverantörens auktoriserings-URL, som den kontrollerar innan den visar den. GitHub visar alltid sin kontoväljare
  2. Personen godkänner i webbläsaren. Leverantören återvänder till Connect
  3. Connect visar vad servern som startade inloggningen kommer att kunna göra som personen, och hur länge. Connect kan inte avgöra vem som kör den servern, så sidan ber personen fortsätta bara om hen startade inloggningen själv, och att stänga den om någon skickade länken. När webbläsaren är på ett annat nätverk än det inloggningen startades från säger sidan det: det är normalt för en hostad server eller en annan enhet, och det är också vad nätfiske ser ut som. Avbryt avslutar inloggningen: leverantörens kod används aldrig. Varje sida svarar en gång; ett svar som inte kom från sidan Connect just visade avvisas
  4. Efter Fortsätt visar Connect en kod på 8 tecken och en länk control-center://oauth-done. Den som får koden får den just godkända åtkomsten, så den går bara dit inloggningen startades
  5. Personen skriver in koden i appen eller följer länken. Servern hämtar inloggningen med koden och sitt eget bevis på begäran

En inloggning går ut efter 10 minuter. Fem felaktiga koder avslutar den. En länk som den här appen inte startade avvisas med Inloggningen startades inte här. Connect begränsar hur många inloggningar en nätadress kan starta, och hur ofta GitHub-tokens utfärdas per person och server, per person över servrar, per adress och för hela appen. Nya inloggningar har en egen budget, så de aldrig håller upp förnyelser som andra behöver. Över en gräns nekas ett anrop med rate_limited, och servern försöker igen senare utan att logga ut någon. En inloggning över personens gräns ångras hos GitHub och avvisas.

Bara serverägaren kan byta nyckeln, med Byt nyckel på kortet Control Center Connect under Inställningar → Server → Enkel inloggning. Det finns inget kommando för det. Vid byte:

  • Loggas alla ut från varje spår som körs via Connect. För varje Connect-server som den gamla nyckeln användes med återkallar servern de GitHub- och Slack-inloggningar den har därifrån (en Google-inloggning har inget att återkalla och förfaller)
  • Fasas det gamla installations-id:t ut hos var och en av dessa Connect-servrar, signerat med den gamla nyckeln och styrkt med ett sigill som servern har från den Connect. Därefter avvisar Connect varje begäran som görs med den gamla nyckeln, så ett sigill eller en kopia av den gamla nyckeln som tagits från den här servern är värdelös, och de Slack-arbetsytor som var bundna till det gamla id:t frigörs så att de kan ansluta igen. Tokens som redan lämnats ut förblir giltiga tills de går ut (en timme för en bot-token, åtta timmar för en persons). En Connect-server som servern inte har något sigill från har inget att fasa ut och hoppas över
  • Ger sedan servern en ny installationsnyckel och ett nytt installations-id
  • Om en Connect-server inte går att nå, eller vägrar fasa ut det gamla id:t, stoppas bytet innan nycklarna byts och visar Connect kunde inte fasa ut den gamla nyckeln. Rotera ändå byter nycklar oavsett; det gamla installations-id:t förblir då användbart hos den Connect tills dess tokens går ut, högst 8 timmar för GitHub
  • Lämnar inloggningar via serverns egna appar orörda
  • Kräver att det nya installations-id:t läggs till i en egen Connects tillåtelselista
Kod Betydelse
hosted_unprovisioned Den här byggnaden har ingen nyckel för den hostade konfigurationen
signature Den hostade konfigurationen klarade inte signaturkontrollen
rollback Connect serverade en äldre konfiguration än servern redan har sett
unreachable Servern kan inte nå Connect
install_blocked Connect tillåter inte det här installations-id:t, eller så har det fasats ut
pins_changed En egen Connect annonserade andra app-identifierare
protocol Connect svarade i en form som den här servern inte förstår