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.
Vad Connect ser och aldrig ser
Avsnitt med rubriken “Vad Connect ser och aldrig ser”| 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.
Arbetsytans eget val
Avsnitt med rubriken “Arbetsytans eget val”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_URLlå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å
Installationsidentitet
Avsnitt med rubriken “Installationsidentitet”| 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.
Förseglade inloggningsuppgifter
Avsnitt med rubriken “Förseglade inloggningsuppgifter”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
GitHub-installationer
Avsnitt med rubriken “GitHub-installationer”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
Den delade boten
Avsnitt med rubriken “Den delade boten”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,reviewochcomment(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 iCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Varje annan server får svaretneeds_requesteroch 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
Vad organisationsägare och medlemmar bör veta
Avsnitt med rubriken “Vad organisationsägare och medlemmar bör veta”- 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
Förtroende för konfigurationen
Avsnitt med rubriken “Förtroende för konfigurationen”| 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 |
Åtgärder
Avsnitt med rubriken “Åtgärder”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.
Inloggning via Connect
Avsnitt med rubriken “Inloggning via Connect”- 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
- Personen godkänner i webbläsaren. Leverantören återvänder till Connect
- 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
- 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 - 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.
Byt installationsnyckeln
Avsnitt med rubriken “Byt installationsnyckeln”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
Statuskoder
Avsnitt med rubriken “Statuskoder”| 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 |