Referința Control Center Connect
Control Center Connect rulează autentificările la provideri pentru serverele care
nu și-au înregistrat propriile aplicații. Un server folosește fie Connect-ul
găzduit al Control Center, fie un Connect pe care îl rulează organizația lui
(Rulează un server Connect),
fie niciunul. Alegerea se află în Setări → Server → Autentificare unică →
Control Center Connect, în cc_server connect sau în CC_CONNECT_URL. Un spațiu de lucru urmează această
alegere, cu excepția cazului în care un administrator alege altceva pentru el în
Setări → Spațiu de lucru → Integrări (Alegerea pe spațiu de lucru).
Sub Folosește aplicațiile mele (sau înainte ca cineva să aleagă), fiecare provider este o bandă, iar o bandă rulează pe aplicația proprie a serverului când una este configurată complet, altfel nu este disponibilă. Cu Control Center Connect sau cu un Connect propriu, Connect gestionează fiecare bandă pe care o servește: aplicațiile proprii ale serverului rămân salvate, dar nu sunt folosite, nici pentru autentificări, nici pentru automatizarea serverului, nici pentru starea raportată de server. Un spațiu de lucru care și-a făcut propria alegere rulează fiecare bandă după această alegere.
| Bandă | Aplicația proprie are nevoie de | Prin Connect |
|---|---|---|
github |
App id, cheie privată, client id și client secret | Oamenii se autentifică în GitHub App partajată |
google |
Client id și client secret | Oamenii conectează Google Calendar |
linear |
Client id | Oamenii se autentifică în Linear |
linear_app |
Client id | Un administrator al spațiului de lucru conectează actorul de aplicație Linear |
slack |
Conexiunea propriei aplicații Slack a unui spațiu de lucru | Un administrator al spațiului de lucru conectează Slack la aplicația Slack partajată |
klipy |
KLIPY_APP_KEY |
Căutare de GIF-uri, prin proxy-ul Connect |
O aplicație proprie configurată doar parțial face din banda ei o eroare, niciodată o revenire tăcută la Connect. Un spațiu de lucru pe Folosește aplicațiile mele nu trece niciodată prin aplicațiile serverului sau prin vreun Connect, pentru niciun provider. Schimbarea alegerii Connect a serverului nu deconectează pe nimeni dintr-un spațiu de lucru care și-a făcut propria alegere.
Ce vede Connect și ce nu vede niciodată
Secțiune intitulată „Ce vede Connect și ce nu vede niciodată”| Connect vede | Connect nu vede niciodată |
|---|---|
| ID-ul de instalare al serverului și semnăturile cererilor | Codul sursă, conținutul depozitelor, diff-urile sau textul pull request-urilor |
| Contul de provider care s-a autentificat, în timpul autentificării | Tichetele, transcrierile sau orice din baza de date a unui spațiu de lucru |
| Spațiul de lucru căruia îi aparține o acreditare, ca id opac în interiorul sigiliului | Secretele aplicațiilor proprii ale serverului: nu părăsesc niciodată serverul |
| Depozitul pentru care este emis un token GitHub pentru un singur depozit | Tokenurile de reîmprospătare în repaus: există doar în sigiliile pe care le păstrează serverul |
| Echipa Slack legată de server | Secretele Linear: serverul schimbă singur codul Linear |
| Termenii de căutare de GIF-uri, când face proxy pentru Klipy | Parole, chei de asociere sau chei ale providerilor de modele |
| Referințele evenimentelor Slack (echipă, canal, id de mesaj) și textul comenzilor slash | Textul mesajelor Slack: Connect îl elimină la sosire, iar serverul citește singur mesajul din Slack |
Connect păstrează autentificările în curs, nonce-urile și cache-urile cel mult 10
minute, iar contoarele de utilizare pe oră cel mult două ore. Un token GitHub
pentru un singur depozit emis ca persoană rămâne înregistrat, sigilat pentru
autentificarea care l-a cerut, până expiră (cel mult 8 ore), ca Connect să-l
poată emite din nou și să-l revoce la deconectare. Singurele lui înregistrări
durabile sunt legăturile Slack (ce server este legat de fiecare echipă Slack) și
ID-urile de instalare retrase. Erorile poartă un cod, niciodată răspunsul
providerului. Jurnalele înregistrează ID-urile de instalare doar ca hash-uri cu
cheie, iar un token GitHub doar ca hashed_token pe care îl arată jurnalul de
audit al organizației GitHub, ca proprietarul organizației să poată potrivi cele
două.
| Mod | Setare | Comportament |
|---|---|---|
| Nesetat | Server nou | Nicio bandă nu folosește Connect. Onboardingul îi cere proprietarului serverului să aleagă |
hosted |
Folosește aplicațiile Control Center | https://connect.usectrl.dev, cu o configurație semnată offline. Aplicațiile proprii ale serverului nu sunt folosite |
custom |
Folosește un server Connect propriu | Un Connect la un URL HTTPS (http doar pe loopback), de încredere la prima utilizare. Aplicațiile proprii ale serverului nu sunt folosite |
off |
Folosește aplicațiile mele | Nicio bandă nu folosește Connect. Doar aplicațiile proprii autentifică oamenii |
CC_CONNECT_URL în mediul serverului sau în .env blochează alegerea: hosted,
off sau un URL Connect. Setările afișează atunci blocarea și nu o pot schimba.
Această compilare nu conține nicio cheie de configurație găzduită, așa că modul
găzduit raportează hosted_unprovisioned și nu servește nicio bandă. Aplicațiile
proprii și un Connect propriu funcționează.
Connect-ul găzduit rulează într-un singur container. Cheia lui de sigilare și cheia privată a GitHub App partajate sunt variabile de mediu acolo, nu chei dintr-un vault care doar semnează sau decriptează, cum recomandă GitHub pentru cheia privată a unei App. Aceasta este o lacună cunoscută a configurației actuale.
Un server citește configurația Connect cel mult o dată la 10 minute și așteaptă cel mult 5 secunde pentru fiecare apel. Când Connect nu este accesibil, ultima configurație bună rămâne în uz, iar Setările o marchează ca învechită.
Alegerea pe spațiu de lucru
Secțiune intitulată „Alegerea pe spațiu de lucru”Setări → Spațiu de lucru → Integrări → Control Center Connect înlocuiește alegerea serverului pentru un spațiu de lucru. Fiecare membru vede alegerea și unde rulează fiecare autentificare; doar un administrator al spațiului de lucru o schimbă.
| Alegere | Comportament |
|---|---|
| Același ca acest server | Implicit. Spațiul de lucru rulează pe ce a ales proprietarul serverului; opțiunea arată care este |
| Folosește aplicațiile Control Center | Connect-ul găzduit al Control Center, oricare ar fi cel folosit de server |
| Folosește aplicațiile mele | Doar aplicațiile proprii ale spațiului de lucru: GitHub App, clientul Google, aplicația Linear, cheia Klipy și aplicația Slack. Un provider fără niciuna este oprit aici; unul configurat parțial este o eroare de configurare |
| Folosește un server Connect propriu | Un Connect la un URL HTTPS indicat de spațiul de lucru. Adresele din rețele private sau locale sunt refuzate |
- Orice alegere diferită de Același ca acest server ține autentificările în GitHub și Linear ale fiecărei persoane într-un slot propriu al spațiului de lucru, așa că nu se amestecă niciodată cu cele de la nivelul serverului
- Schimbarea cere confirmare mai întâi: toți din spațiul de lucru se autentifică din nou în GitHub, Linear și Google Calendar prin noile aplicații
- Conexiunea proprie a spațiului de lucru la Slack funcționează sub orice alegere; Adaugă Control Center în Slack urmează alegerea
CC_CONNECT_URLîmpiedică și ca spațiile de lucru să aibă un Connect propriu: ele pot urma serverul sau își pot folosi propriile aplicații- Connect-ul propriu al unui spațiu de lucru este considerat de încredere la prima utilizare, doar pentru acel spațiu de lucru: Acceptă aplicațiile noi acolo nu schimbă niciodată ce au încredere serverul sau alt spațiu de lucru
Identitatea instalării
Secțiune intitulată „Identitatea instalării”| Element | Ce este |
|---|---|
| Cheie de instalare | Un seed de 32 de octeți în fișierul de secrete al serverului (connect_install_key), separat de cheile de asociere ale dispozitivelor |
| Cheie per Connect | O cheie Ed25519 derivată din seed și din adresa Connect-ului. Fiecare cerere către Connect este semnată cu ea (RFC 9421) |
| ID de instalare | 26 de caractere derivate din acea cheie publică. Afișat în Setări și de cc_server connect status |
Același server are un ID de instalare diferit pentru fiecare adresă Connect. ID-ul se schimbă doar când cheia este schimbată.
Acreditări sigilate
Secțiune intitulată „Acreditări sigilate”O autentificare prin Connect returnează un sigiliu de acreditare: un blob criptat pe care îl poate deschide doar Connect-ul care l-a creat. Este legat de provider, de adresa Connect, de ID-ul de instalare, de spațiul de lucru, de contul de provider, de aplicație și de generația secretului.
- Serverul stochează sigiliul și ID-ul de instalare pentru care a fost sigilat. Tokenurile de acces rămân în memorie
- Pentru reîmprospătare, serverul trimite sigiliul înapoi și primește un nou token de acces și un nou sigiliu
- Un sigiliu al cărui ID de instalare sau adresă Connect nu se mai potrivește este șters la următoarea citire, iar persoana respectivă se autentifică din nou. Asta se întâmplă după o schimbare a cheii, o trecere la alt Connect sau un director de date restaurat pe un alt server
- Un sigiliu pe care Connect nu îl poate deschide este refuzat cu
access_denied
Instalări GitHub
Secțiune intitulată „Instalări GitHub”O instalare a aplicației GitHub partajate poate fi folosită de pe orice server. Connect nu ține evidența serverelor care pot folosi instalarea.
- Instalează aplicația GitHub din Setări → Spațiu de lucru → Integrări deschide pagina de instalare a aplicației pe GitHub. Serverul construiește linkul din numele aplicației din configurația Connect
- Un token pentru un singur depozit cere ca aplicația să fie instalată pe proprietarul depozitului și ca persoana autentificată să aibă acces la depozit. Este tokenul acelei persoane, limitat la rolul ei, niciodată mai mult
- O organizație îl limitează pe Control Center pe GitHub: prin eliminarea instalării, restrângerea depozitelor sau eliminarea persoanei
- Pentru apelurile pe care le poate face doar persoana, cum ar fi listarea instalărilor ei, Connect dă serverului tokenul de utilizator App al persoanei, nu un token pentru un singur depozit. Autentificarea pe un server înseamnă să ai încredere în acel server cu tokenul acesta
- O organizație care impune o listă de IP-uri permise pentru GitHub nu poate folosi Connect-ul găzduit, ale cărui adrese nu sunt fixe. Își înregistrează în schimb propria GitHub App, pe propriile servere sau pe un Connect pe care îl rulează
- Deconectează revocă doar acea autentificare: Connect își consumă tokenul de reîmprospătare o singură dată și șterge ce returnează acesta, șterge tokenul lui de utilizator și tokenurile pentru un singur depozit pe care Connect le-a emis pentru el. O copie a sigiliului său păstrată oriunde încetează să funcționeze. Autentificările persoanei pe alte servere și spații de lucru continuă să funcționeze. Ca să elimini Control Center complet dintr-un cont GitHub, revocă-l în GitHub la Setări → Aplicații → Aplicații GitHub autorizate → Revocă
Botul partajat
Secțiune intitulată „Botul partajat”Tokenurile emise ca botul App-ului (as: app) arată același bot pe GitHub pentru fiecare server care folosește același Connect: GitHub nu poate deosebi serverele acelea.
- Fiecare server poate avea botul care citește și comentează:
read,reviewșicomment(comentarii, etichete, responsabili și reacții pe issues și pull request-uri) - Revizuirea unui pull request ca bot (
bot, care scrie pull request-uri) este permisă doar pentru serverele pe care operatorul Connect le trece înCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Fiecare alt server primește răspunsulneeds_requesterși publică revizuirea pe tokenul propriu al persoanei responsabile, pe care GitHub îl limitează la acea persoană: revizuirea apare sub numele ei. Asta acoperă publicarea revizuirilor AI, comentariile de revizuire și cererile de revizori - Push-ul, crearea unei ramuri și deschiderea unui pull request (
write) nu sunt niciodată emise ca botul partajat. Folosesc întotdeauna autentificarea proprie a solicitantului - Aprobarea unui pull request nu este niciodată automatizată, pe niciun token
- Un server sau un spațiu de lucru cu propria aplicație GitHub păstrează botul pentru tot ce este mai sus, inclusiv revizuirile
Ce trebuie să știe proprietarii și membrii organizației
Secțiune intitulată „Ce trebuie să știe proprietarii și membrii organizației”- Un server pe care cineva se autentifică deține tokenul lui de utilizator App: până la 8 ore per token, reînnoit până când se deconectează. Poate acționa în numele lui pe fiecare depozit pe care aplicația partajată este instalată și la care el poate ajunge. Connect poate tăia definitiv un server (o instalare retrasă sau refuzată), dar un token deja emis rămâne valabil până expiră
- Instalarea aplicației GitHub partajate pe o organizație consimte pentru fiecare server Control Center pe care se autentifică un membru, nu pentru un singur server
- Botul este partajat, ca mai sus: o organizație nu poate spune pe GitHub ce server a acționat ca bot
- O organizație care vrea propria graniță își înregistrează propria aplicație GitHub și rulează propriul Connect (Rulează un server Connect) sau configurează aplicația pe propriile servere
Încrederea în configurație
Secțiune intitulată „Încrederea în configurație”| Connect | Cum are serverul încredere în configurația lui |
|---|---|
| Găzduit | Verifică o semnătură Ed25519 față de cheile compilate în build. Refuză o epocă mai mică decât cea mai mare pe care a văzut-o (rollback) |
| Propriu | Fixează la prima utilizare app id-ul și client id-ul GitHub, client id-urile Google și Linear și app id-ul și client id-ul Slack. O schimbare întrerupe autentificările prin Connect (pins_changed) până când proprietarul serverului apasă Acceptă aplicațiile noi |
Operații
Secțiune intitulată „Operații”Setările Connect ale serverului sunt rezervate proprietarului serverului.
| Operație | Ce face |
|---|---|
connect.status |
Modul, URL-ul, blocarea, ID-ul de instalare, starea, epoca configurației și sursa fiecărei benzi |
connect.configure |
Setează hosted, custom (cu url) sau off |
connect.test |
Preia din nou configurația și raportează starea |
connect.confirmPins |
Acceptă identificatorii schimbați ai unui Connect propriu |
connect.rotateKey |
Emite o nouă cheie de instalare și un nou ID de instalare (force îl înlocuiește chiar când un Connect nu a putut retrage vechiul); vezi Schimbă cheia de instalare |
Alegerea proprie a unui spațiu de lucru are propriile operații, fiecare numind spațiul de lucru:
| Operație | Cine | Ce face |
|---|---|---|
workspaceConnect.status |
Orice membru | Alegerea, la ce se rezolvă, starea și sursa fiecărui provider. ID-ul instalării și pinii în așteptare doar pentru administratori |
workspaceConnect.set |
Administrator al spațiului de lucru | Setează inherit, hosted, custom (cu url) sau own |
workspaceConnect.test |
Administrator al spațiului de lucru | Preia din nou configurația Connect a spațiului de lucru și raportează starea |
workspaceConnect.confirmPins |
Administrator al spațiului de lucru | Acceptă identificatorii schimbați ai Connect-ului propriu al spațiului de lucru |
Autentificările însele folosesc oauth.lanes, oauth.begin, oauth.status,
oauth.complete, oauth.connections și oauth.disconnect. Persoana este
întotdeauna apelantul autentificat.
Autentificarea prin Connect
Secțiune intitulată „Autentificarea prin Connect”- Serverul îi cere lui Connect să pornească banda și primește URL-ul de autorizare al providerului, pe care îl verifică înainte să-l afișeze. GitHub afișează întotdeauna selectorul de conturi
- Persoana aprobă în browser. Providerul se întoarce la Connect
- Connect arată ce va putea face serverul care a pornit autentificarea în numele persoanei și pentru cât timp. Connect nu poate spune cine rulează acel server, deci pagina cere persoanei să continue doar dacă a pornit singură autentificarea, și să o închidă dacă cineva i-a trimis linkul. Când browserul este pe altă rețea decât cea din care a fost pornită autentificarea, pagina spune asta: este normal pentru un server găzduit sau pentru alt dispozitiv și este totodată ceea ce arată un phishing. Anulează încheie autentificarea: codul providerului nu este folosit niciodată. Fiecare pagină răspunde o singură dată; un răspuns care nu a venit de la pagina pe care tocmai a arătat-o Connect este refuzat
- După Continuă, Connect afișează un cod de 8 caractere și un link
control-center://oauth-done. Oricine primește codul primește accesul tocmai aprobat, deci codul merge doar acolo unde a fost pornită autentificarea - Persoana tastează codul în aplicație sau urmează linkul. Serverul revendică autentificarea cu codul și cu propria dovadă a cererii
O autentificare expiră după 10 minute. Cinci coduri greșite o încheie. Un link pe
care această aplicație nu l-a pornit este refuzat cu Autentificare nepornită
de aici. Connect limitează câte autentificări poate porni o adresă de rețea și cât de des
se emit tokenurile GitHub per persoană și server, per persoană pe servere, per
adresă și pentru toată aplicația. Autentificările noi au un buget propriu, deci
nu blochează niciodată reînnoirile de care au nevoie alți oameni. Peste o limită,
un apel este refuzat cu rate_limited, iar serverul reîncearcă mai târziu fără
să deconecteze pe nimeni. O autentificare peste limita persoanei este anulată la
GitHub și refuzată.
Schimbă cheia de instalare
Secțiune intitulată „Schimbă cheia de instalare”Doar proprietarul serverului poate schimba cheia, cu Schimbă cheia de pe cardul Control Center Connect din Setări → Server → Autentificare unică. Nu există nicio comandă pentru asta. Schimbarea:
- Deconectează pe toți de pe fiecare bandă care rulează prin Connect. Pentru fiecare server Connect cu care a fost folosită vechea cheie, serverul revocă autentificările GitHub și Slack pe care le ține de acolo (o autentificare Google nu are nimic de revocat și expiră)
- Retrage vechiul ID de instalare la fiecare dintre acele servere Connect, semnat cu vechea cheie și dovedit cu un sigiliu de acreditare pe care serverul îl ține de la Connect-ul acela. De atunci Connect refuză orice cerere făcută cu vechea cheie, deci un sigiliu sau o copie a vechii chei luată de pe acest server este inutilă, iar spațiile de lucru Slack legate de vechiul ID sunt eliberate ca să se poată conecta din nou. Tokenurile deja emise rămân valabile până expiră (o oră pentru un token de bot, opt ore pentru cel al unei persoane). Un server Connect de la care acest server nu ține niciun sigiliu nu are ce retrage și este sărit
- Apoi îi dă serverului o nouă cheie de instalare și un nou ID de instalare
- Dacă un server Connect nu poate fi contactat sau refuză să retragă vechiul ID, se oprește înainte să schimbe cheile și afișează Connect nu a putut retrage cheia veche. Rotește oricum schimbă cheile indiferent de asta; vechiul ID de instalare rămâne atunci utilizabil la acel Connect până expiră tokenurile lui, cel mult 8 ore pentru GitHub
- Lasă neatinse autentificările prin aplicațiile proprii ale serverului
- Necesită adăugarea noului ID de instalare în lista de permisiuni a unui Connect propriu
Coduri de stare
Secțiune intitulată „Coduri de stare”| Cod | Semnificație |
|---|---|
hosted_unprovisioned |
Această compilare nu are o cheie de configurație găzduită |
signature |
Configurația găzduită nu a trecut verificarea semnăturii |
rollback |
Connect a servit o configurație mai veche decât cea pe care serverul a văzut-o deja |
unreachable |
Serverul nu poate ajunge la Connect |
install_blocked |
Connect nu permite acest ID de instalare, sau a fost retras |
pins_changed |
Un Connect propriu a anunțat alți identificatori de aplicație |
protocol |
Connect a răspuns într-o formă pe care acest server nu o înțelege |