Salta ai contenuti

Riferimento di Control Center Connect

Control Center Connect esegue gli accessi ai provider per i server che non hanno registrato app proprie. Un server usa il Connect ospitato da Control Center, un Connect gestito dalla sua organizzazione (Esegui un server Connect), oppure nessuno. La scelta si trova in Impostazioni → Server → Accesso single sign-on → Control Center Connect, in cc_server connect o in CC_CONNECT_URL. Uno spazio di lavoro segue la scelta, a meno che un amministratore non scelga altro per quello spazio di lavoro in Impostazioni → Spazio di lavoro → Integrazioni (Scelta per spazio di lavoro).

Ogni provider è un canale. Con Usa le mie app (o finché nessuno ha scelto), un canale usa l’app del server quando è configurata per intero, altrimenti non è disponibile. Con Connect di Control Center o un Connect personalizzato, Connect gestisce ogni canale che serve: le app del server restano salvate ma non sono usate per gli accessi, l’automazione del server o lo stato che il server riporta. Uno spazio di lavoro che ha scelto la propria opzione esegue ogni canale secondo quella scelta.

Canale Un’app propria richiede Tramite Connect
github Id app, chiave privata, client id e client secret Le persone accedono alla GitHub App condivisa
google Client id e client secret Le persone collegano Google Calendar
linear Client id Le persone accedono a Linear
linear_app Client id Un amministratore dello spazio di lavoro collega l’attore app di Linear
slack Il collegamento all’app Slack propria di uno spazio di lavoro Un amministratore dello spazio di lavoro collega Slack all’app Slack condivisa
klipy KLIPY_APP_KEY La ricerca di GIF, tramite proxy di Connect

Un’app propria configurata solo in parte mette il suo canale in errore, mai in un ripiego silenzioso su Connect. Uno spazio di lavoro su Usa le mie app non passa mai dalle app del server né da alcun Connect, per nessun provider. Cambiare la scelta di Connect del server non disconnette nessuno da uno spazio di lavoro che ha fatto la sua scelta.

Connect vede Connect non vede mai
L’id di installazione del server e le firme delle richieste Codice sorgente, contenuto dei repository, diff o testo delle pull request
L’account del provider che ha effettuato l’accesso, durante l’accesso Ticket, trascrizioni o qualsiasi cosa nel database di uno spazio di lavoro
A quale spazio di lavoro appartiene una credenziale, come id opaco dentro il sigillo I segreti delle app proprie del server: non lasciano mai il server
Il repository per cui viene emesso un token GitHub limitato a un repository I token di aggiornamento a riposo: esistono solo dentro i sigilli che il server conserva
Il team Slack associato al server I segreti di Linear: il server scambia da sé il codice di Linear
I termini di ricerca delle GIF, quando fa da proxy a Klipy Password, chiavi di abbinamento o chiavi dei fornitori di modelli
I riferimenti agli eventi Slack (team, canale, id del messaggio) e il testo degli slash command Il testo dei messaggi Slack: Connect lo scarta all’arrivo e il server legge il messaggio direttamente da Slack

Connect conserva accessi in sospeso, nonce e cache per al massimo 10 minuti, e contatori d’uso orari per al massimo due ore. Un token GitHub limitato a un repository emesso come persona resta registrato, sigillato all’accesso che l’ha richiesto, finché non scade (al massimo 8 ore), così Connect può riemetterlo e revocarlo alla disconnessione. I suoi unici record duraturi sono le associazioni Slack (a quale server è associato ogni team Slack) e gli id di installazione ritirati. Gli errori riportano un codice, mai la risposta del provider. I log registrano gli id di installazione solo come hash con chiave, e un token GitHub solo come hashed_token che il registro di audit dell’organizzazione GitHub mostra per esso, così un proprietario dell’organizzazione può far corrispondere i due.

Modalità Impostazione Comportamento
Non impostata Server nuovo Nessun canale usa Connect. L’onboarding chiede al proprietario del server di scegliere
hosted Usa le app di Control Center https://connect.usectrl.dev, con una configurazione firmata offline. Le app del server non sono usate
custom Usa un server Connect personalizzato Un Connect a un URL HTTPS (http solo su loopback), considerato attendibile al primo uso. Le app del server non sono usate
off Usa le mie app Nessun canale usa Connect. Solo le app proprie fanno accedere le persone

CC_CONNECT_URL nell’ambiente del server o nel suo .env blocca la scelta: hosted, off o un URL Connect. Impostazioni mostra allora il blocco e non può modificarlo.

Questa build non include alcuna chiave di configurazione ospitata, quindi la modalità ospitata riporta hosted_unprovisioned e non serve alcun canale. Le app proprie e un Connect personalizzato funzionano.

Il Connect ospitato gira in un singolo container. La sua chiave di sigillo e la chiave privata della GitHub App condivisa sono variabili d’ambiente lì, non chiavi in un vault che firma o decifra soltanto, come raccomanda GitHub per la chiave privata di un’App. È una lacuna nota della configurazione attuale.

Un server legge la configurazione di Connect al massimo ogni 10 minuti e attende al massimo 5 secondi per ogni chiamata. Quando Connect non è raggiungibile, resta in uso l’ultima configurazione valida e Impostazioni la segnala come non aggiornata.

Impostazioni → Spazio di lavoro → Integrazioni → Control Center Connect sostituisce la scelta del server per un solo spazio di lavoro. Ogni membro la vede e vede dove gira ogni accesso; solo un amministratore dello spazio di lavoro può cambiarla.

Scelta Comportamento
Come questo server Il default. Lo spazio di lavoro usa qualunque cosa abbia scelto il proprietario del server; l’opzione lo indica
Usa le app di Control Center Il Connect ospitato da Control Center, qualunque cosa usi il server
Usa le mie app Solo le app dello spazio di lavoro: la sua GitHub App, il client Google, l’applicazione Linear, la chiave Klipy e l’app Slack. Un provider senza app qui è disattivato; un’app parziale è un errore di configurazione
Usa un server Connect personalizzato Un Connect a un indirizzo HTTPS che lo spazio di lavoro indica. Gli indirizzi su rete privata o locale vengono rifiutati
  • Qualunque scelta diversa da Come questo server mantiene per ogni persona gli accessi a GitHub e Linear in uno slot dello spazio di lavoro, quindi non si mescolano mai con quelli a livello di server
  • Il cambio chiede prima conferma: tutti nello spazio di lavoro accedono di nuovo a GitHub, Linear e Google Calendar tramite le nuove app
  • La connessione all’app Slack propria dello spazio di lavoro funziona con ogni scelta; Aggiungi Control Center a Slack segue la scelta
  • CC_CONNECT_URL blocca anche la possibilità, per gli spazi di lavoro, di avere un Connect proprio: possono seguire il server o usare le proprie app
  • Il Connect personalizzato di uno spazio di lavoro è considerato attendibile al primo uso solo per quello spazio di lavoro: Considera attendibili le nuove app lì non cambia mai ciò che considerano attendibile il server o un altro spazio di lavoro
Elemento Cos’è
Chiave di installazione Un seed di 32 byte nel file dei segreti del server (connect_install_key), separato dalle chiavi di abbinamento dei dispositivi
Chiave per Connect Una chiave Ed25519 derivata dal seed e dall’indirizzo del Connect. Ogni richiesta a Connect è firmata con essa (RFC 9421)
Id di installazione 26 caratteri derivati da quella chiave pubblica. Mostrato in Impostazioni e da cc_server connect status

Lo stesso server ha un id di installazione diverso per ogni indirizzo Connect. L’id cambia solo quando la chiave viene ruotata.

Un accesso tramite Connect restituisce un sigillo della credenziale: un blob cifrato che solo il Connect che l’ha creato può aprire. È legato al provider, all’indirizzo di Connect, all’id di installazione, allo spazio di lavoro, all’account del provider, all’app e alla generazione del segreto.

  • Il server conserva il sigillo e l’id di installazione per cui è stato sigillato. I token di accesso restano in memoria
  • Per aggiornare, il server rimanda il sigillo e riceve un nuovo token di accesso e un nuovo sigillo
  • Un sigillo il cui id di installazione o indirizzo di Connect non corrisponde più viene eliminato alla lettura successiva, e quella persona accede di nuovo. Succede dopo una rotazione della chiave, un passaggio a un altro Connect o una directory dati ripristinata su un server diverso
  • Un sigillo che Connect non riesce ad aprire viene rifiutato con access_denied

Un’installazione della GitHub App condivisa è utilizzabile da ogni server. Connect non conserva alcun record di quale server possa usarla.

  • Installa l’app GitHub in Impostazioni → Spazio di lavoro → Integrazioni apre la pagina di installazione dell’app su GitHub. Il server costruisce il link dal nome dell’app nella configurazione di Connect
  • Un token limitato a un repository richiede che l’app sia installata presso il proprietario del repository e che la persona che ha effettuato l’accesso abbia accesso al repository. È un token proprio di quella persona, limitato al suo ruolo, mai di più
  • Un’organizzazione limita Control Center su GitHub: rimuovendo l’installazione, restringendo i suoi repository o rimuovendo la persona
  • Per le chiamate che solo la persona può fare, come elencare le sue installazioni, Connect consegna al server il token utente della App della persona, non un token limitato a un repository. Accedere su un server significa fidarsi di quel server con quel token
  • Un’organizzazione che impone una lista di IP consentiti per GitHub non può usare il Connect ospitato, i cui indirizzi non sono fissi. Registra invece una propria GitHub App, sui propri server o su un Connect che gestisce
  • Disconnetti revoca solo quell’accesso: Connect usa il suo token di aggiornamento una volta e cancella ciò che quella richiesta restituisce, cancella il proprio token utente e i token limitati a un repository che Connect ha emesso per lui. Una copia del suo sigillo conservata altrove smette di funzionare. Gli accessi della persona su altri server e spazi di lavoro continuano a funzionare. Per rimuovere del tutto Control Center da un account GitHub, revocalo su GitHub in Impostazioni → Applicazioni → App GitHub autorizzate → Revoca

I token emessi come bot della App (as: app) mostrano lo stesso bot su GitHub per ogni server che usa lo stesso Connect: GitHub non può distinguere quei server.

  • Ogni server può far leggere e commentare il bot: read, review e comment (commenti, etichette, assegnatari e reazioni su issue e pull request)
  • Revisionare una pull request come bot (bot, che scrive sulle pull request) è consentito solo per i server che l’operatore di Connect elenca in CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Ogni altro server riceve needs_requester e pubblica la revisione con il token personale della persona responsabile, che GitHub limita a quella persona: la revisione compare con il suo nome. Questo riguarda la pubblicazione delle revisioni AI, i commenti di revisione e le richieste di revisori
  • Push, creazione di un branch e apertura di una pull request (write) non vengono mai emessi come bot condiviso. Usano sempre l’accesso proprio di chi ha fatto la richiesta
  • Approvare una pull request non è mai automatizzato, con nessun token
  • Un server o uno spazio di lavoro con una propria GitHub App mantiene il bot per tutto questo, revisioni comprese

Cosa devono sapere proprietari e membri dell’organizzazione

Sezione intitolata “Cosa devono sapere proprietari e membri dell’organizzazione”
  • Un server su cui qualcuno accede detiene il suo token utente della App: fino a 8 ore per token, rinnovato finché non si disconnette. Può agire come lui su ogni repository su cui è installata la App condivisa e a cui lui può accedere. Connect può tagliare fuori un server in modo definitivo (un’installazione ritirata o negata), ma un token già consegnato resta valido finché non scade
  • Installare la GitHub App condivisa su un’organizzazione dà il consenso per ogni server Control Center su cui un membro accede, non per un solo server
  • Il bot è condiviso, come sopra: un’organizzazione non può distinguere su GitHub quale server ha agito come bot
  • Un’organizzazione che vuole un proprio confine registra una propria GitHub App ed esegue il proprio Connect (Esegui un server Connect), oppure configura la App sui propri server
Connect Come il server si fida della sua configurazione
Ospitato Verifica una firma Ed25519 rispetto a chiavi compilate nella build. Rifiuta un’epoca inferiore alla più alta che ha visto (rollback)
Personalizzato Al primo uso fissa l’id app e il client id di GitHub, i client id di Google e Linear, e gli id app e client di Slack. Un cambiamento sospende gli accessi tramite Connect (pins_changed) finché il proprietario del server non preme Considera attendibili le nuove app

Le impostazioni Connect del server sono riservate al proprietario del server.

Operazione Effetto
connect.status Modalità, URL, blocco, id di installazione, stato di salute, epoca della configurazione e origine di ogni canale
connect.configure Imposta hosted, custom (con url) o off
connect.test Recupera di nuovo la configurazione e riporta lo stato di salute
connect.confirmPins Accetta gli identificatori modificati di un Connect personalizzato
connect.rotateKey Emette una nuova chiave di installazione e un nuovo id di installazione (force lo sostituisce anche quando un Connect non riesce a ritirare la vecchia chiave); vedi Ruota la chiave di installazione

Le scelte di uno spazio di lavoro hanno le proprie operazioni, ciascuna con il nome dello spazio di lavoro:

Operazione Chi Effetto
workspaceConnect.status Qualsiasi membro La scelta, cosa risolve, stato di salute e origine di ogni provider. Id di installazione e pin in sospeso solo per gli amministratori
workspaceConnect.set Amministratore dello spazio di lavoro Imposta inherit, hosted, custom (con url) o own
workspaceConnect.test Amministratore dello spazio di lavoro Recupera di nuovo la configurazione Connect dello spazio di lavoro e riporta lo stato di salute
workspaceConnect.confirmPins Amministratore dello spazio di lavoro Accetta gli identificatori modificati del Connect personalizzato dello spazio di lavoro

Gli accessi stessi usano oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections e oauth.disconnect. La persona è sempre il chiamante che ha effettuato l’accesso.

  1. Il server chiede a Connect di avviare il canale e riceve l’URL di autorizzazione del provider, che verifica prima di mostrarlo. GitHub mostra sempre il selettore di account
  2. La persona approva nel browser. Il provider torna a Connect
  3. Connect mostra cosa il server che ha avviato l’accesso potrà fare come la persona, e per quanto tempo. Connect non può sapere chi gestisce quel server, quindi la pagina chiede alla persona di continuare solo se è lei ad aver avviato l’accesso, e di chiuderla se qualcuno le ha inviato il link. Quando il browser è su una rete diversa da quella da cui è stato avviato l’accesso, la pagina lo dice: è normale per un server ospitato o un altro dispositivo, ed è anche ciò che assomiglia a un phishing. Annulla termina l’accesso: il codice del provider non viene mai usato. Ogni pagina risponde una sola volta: una risposta che non arriva dalla pagina che Connect ha appena mostrato viene rifiutata
  4. Dopo Continua, Connect mostra un codice di 8 caratteri e un link control-center://oauth-done. Chi ottiene il codice ottiene l’accesso appena approvato, quindi va condiviso solo dove l’accesso è stato avviato
  5. La persona digita il codice nell’app, oppure segue il link. Il server rivendica l’accesso con il codice e la propria prova della richiesta

Un accesso scade dopo 10 minuti. Cinque codici errati lo interrompono. Un link che questa app non ha avviato viene rifiutato con Accesso non avviato qui. Connect limita quanti accessi può avviare un indirizzo di rete, e con quale frequenza vengono emessi token GitHub per persona e server, per persona su più server, per indirizzo e per l’intera app. I nuovi accessi hanno un budget proprio, così non bloccano mai i rinnovi di cui hanno bisogno altre persone. Oltre un limite una chiamata viene rifiutata con rate_limited, e il server riprova più tardi senza disconnettere nessuno. Un accesso oltre il limite della persona viene annullato su GitHub e rifiutato.

Solo il proprietario del server può ruotare la chiave, con Ruota la chiave nella scheda Control Center Connect in Impostazioni → Server → Accesso single sign-on. Non esiste un comando per farlo. Ruotare:

  • Disconnette tutti da ogni canale che passa da Connect. Per ogni server Connect con cui è stata usata la vecchia chiave, il server revoca gli accessi GitHub e Slack che vi detiene (un accesso Google non ha nulla da revocare e decade)
  • Ritira il vecchio id di installazione presso ciascuno di quei server Connect, firmato con la vecchia chiave e provato con un sigillo di credenziale che il server detiene da quel Connect. Da allora Connect rifiuta ogni richiesta fatta con la vecchia chiave, quindi un sigillo o una copia della vecchia chiave presa da questo server non serve a nulla, e gli spazi di lavoro Slack associati al vecchio id vengono liberati così da poter connettersi di nuovo. I token già consegnati restano validi finché non scadono (un’ora per un token del bot, otto ore per quello di una persona). Un server Connect da cui questo server non detiene alcun sigillo non ha nulla da ritirare e viene saltato
  • Poi dà al server una nuova chiave di installazione e un nuovo id di installazione
  • Se un server Connect non è raggiungibile, o rifiuta di ritirare il vecchio id, si ferma prima di cambiare chiave e mostra Connect non è riuscito a ritirare la vecchia chiave. Rigenera comunque cambia chiave in ogni caso; il vecchio id di installazione resta poi utilizzabile presso quel Connect finché i suoi token non scadono, al massimo 8 ore per GitHub
  • Lascia intatti gli accessi tramite le app del server
  • Richiede di aggiungere il nuovo id di installazione alla lista di autorizzazione di un Connect personalizzato
Codice Significato
hosted_unprovisioned Questa build non ha alcuna chiave di configurazione ospitata
signature La configurazione ospitata non ha superato la verifica della firma
rollback Connect ha servito una configurazione più vecchia di quella già vista dal server
unreachable Il server non riesce a raggiungere Connect
install_blocked Connect non consente questo id di installazione, oppure è stato ritirato
pins_changed Un Connect personalizzato ha annunciato identificatori di app diversi
protocol Connect ha risposto in una forma che questo server non comprende