Přeskočit na obsah

Reference Control Center Connect

Control Center Connect provádí přihlášení k poskytovatelům pro servery, které si nezaregistrovaly vlastní aplikace. Server používá buď hostovaný Connect od Control Center, Connect, který provozuje jeho organizace (Spusťte server Connect), nebo žádný. Volba leží v Nastavení → Server → Jednotné přihlášení → Control Center Connect, v cc_server connect nebo v CC_CONNECT_URL. Pracovní prostor ji následuje, pokud admin pro něj nezvolí jinou v Nastavení → Pracovní prostor → Integrace (Volba pro každý pracovní prostor).

Každý poskytovatel je dráha. Při Použít vlastní aplikace (nebo dřív, než si někdo vybere) dráha běží na vlastní aplikaci serveru, když je úplně nastavená, jinak není dostupná. S Control Center nebo vlastním Connect obsluhuje Connect každou dráhu, kterou nabízí: vlastní aplikace serveru zůstávají uložené, ale nepoužijí se ani pro přihlášení, ani pro automatizaci serveru, ani pro stav, který server hlásí. Pracovní prostor, který zvolil vlastní volbu, běží na každé dráze podle té volby.

Dráha Vlastní aplikace potřebuje Přes Connect
github App id, soukromý klíč, client id a client secret Lidé se přihlašují ke sdílené GitHub App
google Client id a client secret Lidé připojují Google Calendar
linear Client id Lidé se přihlašují k Linear
linear_app Client id Admin pracovního prostoru připojí aktéra aplikace Linear
slack Spojení vlastní aplikace Slack pracovního prostoru Admin pracovního prostoru připojí Slack ke sdílené aplikaci Slack
klipy KLIPY_APP_KEY Hledání GIF přes proxy Connect

Vlastní aplikace, která je nastavená jen částečně, z dráhy udělá chybu, nikdy tichý přechod na Connect. Pracovní prostor na Použít vlastní aplikace nikdy nejde přes aplikace serveru ani přes jakýkoli Connect, u žádného poskytovatele. Změna volby Connect na serveru nikoho neodhlásí z pracovního prostoru, který zvolil vlastní volbu.

Co Connect vidí a co nikdy

Sekce “Co Connect vidí a co nikdy”
Connect vidí Connect nikdy nevidí
ID instalace serveru a podpisy požadavků Zdrojový kód, obsah repozitářů, diffy ani text pull requestů
Účet u poskytovatele, který se přihlásil, během přihlášení Tickety, přepisy ani nic v databázi pracovního prostoru
Ke kterému pracovnímu prostoru pověření patří, jako neprůhledné id uvnitř pečetě Tajemství vlastních aplikací serveru: nikdy neopouštějí server
Repozitář, pro který se vydává token GitHubu pro jediný repozitář Obnovovací tokeny v klidu: existují jen uvnitř pečetí, které drží server
Tým Slacku vázaný na server Tajemství Linear: kód od Linear vyměňuje server sám
Hledané výrazy GIF, když dělá proxy pro Klipy Hesla, párovací klíče ani klíče poskytovatelů modelů
Odkazy na události Slacku (tým, kanál, id zprávy) a text slash příkazů Text zpráv Slacku: Connect ho při příchodu zahodí a server si zprávu přečte ze Slacku sám

Rozpracovaná přihlášení, nonce a mezipaměti drží Connect nejvýš 10 minut a hodinová počítadla použití nejvýš dvě hodiny. Token GitHubu pro jediný repozitář vydaný jako člověk zůstává zaznamenaný, zapečetěný k přihlášení, které o něj požádalo, dokud nevyprší (nejvýš 8 hodin), takže ho Connect může znovu vydat a odvolat při odpojení. Jediné trvalé záznamy jsou vazby Slacku (ke kterému serveru je vázaný každý tým Slacku) a vyřazená ID instalací. Chyby nesou kód, nikdy odpověď poskytovatele. Logy zapisují ID instalací jen jako klíčované hashe a token GitHubu jen jako hashed_token, který pro něj ukazuje auditní log organizace na GitHubu, takže vlastník organizace může obě položky spárovat.

Režim Nastavení Chování
Nenastaveno Čerstvý server Žádná dráha Connect nepoužívá. Onboarding vyzve vlastníka serveru k volbě
hosted Použít aplikace Control Center https://connect.usectrl.dev, s offline podepsanou konfigurací. Vlastní aplikace serveru se nepoužijí
custom Použít vlastní server Connect Connect na URL s HTTPS (http jen na loopbacku), důvěryhodný od prvního použití. Vlastní aplikace serveru se nepoužijí
off Použít vlastní aplikace Žádná dráha Connect nepoužívá. Lidi přihlašují jen vlastní aplikace

CC_CONNECT_URL v prostředí serveru nebo v .env volbu zamkne: hosted, off nebo URL Connect. Nastavení pak zámek ukáže a volbu změnit nemůže.

Tohle sestavení nemá zakompilovaný žádný klíč hostované konfigurace, takže hostovaný režim hlásí hosted_unprovisioned a neobsluhuje žádnou dráhu. Vlastní aplikace a vlastní Connect fungují.

Hostovaný Connect běží v jediném kontejneru. Jeho klíč pro pečetě a soukromý klíč sdílené GitHub App jsou tam proměnné prostředí, ne klíče v trezoru, který jen podepisuje nebo dešifruje, jak GitHub doporučuje pro soukromý klíč App. To je známá mezera současného nastavení.

Server čte konfiguraci Connect nejvýš každých 10 minut a na každé volání čeká nejvýš 5 sekund. Když je Connect nedostupný, zůstává v platnosti poslední dobrá konfigurace a Nastavení ji označí jako zastaralou.

Volba pro každý pracovní prostor

Sekce “Volba pro každý pracovní prostor”

Nastavení → Pracovní prostor → Integrace → Control Center Connect přepíše volbu serveru pro jeden pracovní prostor. Každý člen vidí volbu a to, kde běží každé přihlášení; měnit ji smí jen admin pracovního prostoru.

Volba Chování
Stejné jako tento server Výchozí. Pracovní prostor běží na tom, co zvolil vlastník serveru; volba to pojmenuje
Použít aplikace Control Center Hostovaný Connect od Control Center, ať server používá cokoli
Použít vlastní aplikace Jen vlastní aplikace pracovního prostoru: jeho GitHub App, klient Google, aplikace Linear, klíč Klipy a aplikace Slack. Poskytovatel bez ní tu není dostupný; částečně vyplněná je chyba nastavení
Použít vlastní server Connect Connect na adrese HTTPS, kterou pracovní prostor zadá. Adresy v privátní nebo lokální síti jsou odmítnuty
  • Každá volba jiná než Stejné jako tento server drží přihlášení ke GitHubu a Linear každého člověka v pozici patřící pracovnímu prostoru, takže se nemíchají s těmi na úrovni serveru
  • Přepnutí se nejdřív zeptá: všichni v pracovním prostoru se znovu přihlásí ke GitHubu, Linear a Google Calendar přes nové aplikace
  • Vlastní připojení aplikace Slack pracovního prostoru funguje při každé volbě; Přidat Control Center do Slacku volbu následuje
  • CC_CONNECT_URL také zamkne pracovní prostory, aby neměly vlastní Connect: mohou následovat server nebo použít vlastní aplikace
  • Vlastní Connect pracovního prostoru se důvěřuje při prvním použití jen pro ten pracovní prostor: Důvěřovat novým aplikacím tam nikdy nemění, čemu důvěřuje server nebo jiný pracovní prostor
Položka Co to je
Instalační klíč 32bajtové semínko v souboru secrets serveru (connect_install_key), oddělené od párovacích klíčů zařízení
Klíč pro daný Connect Klíč Ed25519 odvozený ze semínka a adresy Connect. Každý požadavek na Connect se jím podepisuje (RFC 9421)
ID instalace 26 znaků odvozených z toho veřejného klíče. Ukazuje ho Nastavení a cc_server connect status

Tentýž server má pro každou adresu Connect jiné ID instalace. ID se změní jen při výměně klíče.

Zapečetěná pověření

Sekce “Zapečetěná pověření”

Přihlášení přes Connect vrátí pečeť pověření: zašifrovaný blob, který umí otevřít jen Connect, který ho vytvořil. Je vázaná na poskytovatele, adresu Connect, ID instalace, pracovní prostor, účet u poskytovatele, aplikaci a generaci tajemství.

  • Server uloží pečeť a ID instalace, pro které byla zapečetěná. Přístupové tokeny zůstávají v paměti
  • Při obnově server pečeť pošle zpět a dostane nový přístupový token a novou pečeť
  • Pečeť, jejíž ID instalace nebo adresa Connect už nesedí, se při dalším čtení smaže a ten člověk se přihlásí znovu. Stane se to po výměně klíče, po přechodu na jiný Connect nebo po obnovení datového adresáře na jiný server
  • Pečeť, kterou Connect otevřít nedokáže, se odmítne s access_denied

Instalaci sdílené GitHub App může použít každý server. Connect nevede záznam o tom, který server ji smí používat.

  • Nainstalovat aplikaci GitHub v Nastavení → Pracovní prostor → Integrace otevře stránku instalace aplikace na GitHubu. Server sestaví odkaz z názvu aplikace v konfiguraci Connect
  • Token pro jediný repozitář potřebuje aplikaci nainstalovanou u vlastníka repozitáře a přístup přihlášené osoby k tomu repozitáři. Je to vlastní token té osoby, omezený na její roli, nikdy víc
  • Organizace omezuje Control Center na GitHubu: odebráním instalace, zúžením jejích repozitářů nebo odebráním osoby
  • Pro volání, která může udělat jen člověk, například výpis jeho instalací, Connect serveru předá uživatelský token App toho člověka, ne token pro jeden repozitář. Přihlášení na serveru znamená, že tomuto serveru ten token svěřuješ
  • Organizace, která vynucuje seznam povolených IP adres GitHubu, nemůže použít hostovaný Connect, jehož adresy nejsou pevné. Místo něj zaregistruje vlastní GitHub App, na svých serverech nebo na Connectu, který provozuje
  • Odpojit odvolá jen toto přihlášení: Connect spotřebuje obnovovací token jednou a smaže to, co tím dostane, smaže svůj uživatelský token a tokeny pro jeden repozitář, které pro něj vydal. Kopie jeho pečeti kdekoli uložená přestane fungovat. Přihlášení téhož člověka na jiných serverech a v jiných pracovních prostorech dál funguje. Chcete-li Control Center z účtu na GitHubu odebrat úplně, odvolejte ho na GitHubu v Nastavení → Aplikace → Autorizované aplikace GitHub → Odvolat

Tokeny vydané jako bot App (as: app) ukazují na GitHubu stejného bota pro každý server, který používá stejný Connect: GitHub ty servery nerozliší.

  • Každý server smí botovi číst a komentovat: read, review a comment (komentáře, štítky, přiřazené osoby a reakce u issues a pull requestů)
  • Revidovat pull request jako bot (bot, který zapisuje do pull requestů) smí jen servery, které provozovatel Connectu uvede v CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Každý jiný server dostane odpověď needs_requester a revizi zveřejní přes token odpovědné osoby, který GitHub omezí na tuhle osobu: revize se zobrazí pod jejím jménem. Týká se to zveřejňování AI review, komentářů k revizi a žádostí o revizi
  • Push, vytvoření větve a otevření pull requestu (write) se nikdy nevydávají jako sdílený bot. Vždy používají vlastní přihlášení žadatele
  • Schválení pull requestu se neautomatizuje nikdy, na žádném tokenu
  • Server nebo pracovní prostor s vlastní GitHub App si bota pro všechno z toho ponechá, včetně revizí

Co by měli vlastníci a členové organizace vědět

Sekce “Co by měli vlastníci a členové organizace vědět”
  • Server, na kterém se někdo přihlásil, drží jeho uživatelský token App: až 8 hodin na token, obnovovaný, dokud se člověk neodpojí. Může jednat jeho jménem v každém repozitáři, na který je sdílená App nainstalovaná a který dosáhne. Connect může server odříznout nadobro (vyřazená nebo zamítnutá instalace), ale token, který už byl vydán, platí až do vypršení
  • Instalace sdílené GitHub App v organizaci dává souhlas pro každý server Control Center, na který se kterýkoli člen přihlásí, ne pro jeden server
  • Bot je sdílený, jak je popsáno výše: organizace na GitHubu nepozná, který server jednal jako bot
  • Organizace, která chce vlastní hranici, zaregistruje vlastní GitHub App a provozuje vlastní Connect (Spusťte server Connect), nebo nakonfiguruje App na vlastních serverech
Connect Jak server důvěřuje jeho konfiguraci
Hostovaný Ověří podpis Ed25519 proti klíčům zakompilovaným do sestavení. Odmítne epochu nižší, než jakou už viděl (rollback)
Vlastní Při prvním použití si připne app id a client id GitHubu, client id Google a Linear a app id a client id Slacku. Změna pozastaví přihlášení přes Connect (pins_changed), dokud vlastník serveru nestiskne Důvěřovat novým aplikacím

Nastavení Connect na serveru smí měnit jen vlastník serveru.

Operace Co dělá
connect.status Režim, URL, zámek, ID instalace, stav, epocha konfigurace a zdroj každé dráhy
connect.configure Nastaví hosted, custom (s url) nebo off
connect.test Znovu stáhne konfiguraci a ohlásí stav
connect.confirmPins Přijme změněné identifikátory vlastního Connect
connect.rotateKey Vystaví nový instalační klíč a nové ID instalace (force ho nahradí, i když Connect nemohl starý vyřadit); viz Vyměňte instalační klíč

Vlastní volba pracovního prostoru má vlastní operace, každá pojmenovává pracovní prostor:

Operace Kdo Co dělá
workspaceConnect.status Kterýkoli člen Volba, na co se přeloží, stav a zdroj každého poskytovatele. ID instalace a čekající připnutí jen pro adminy
workspaceConnect.set Admin pracovního prostoru Nastaví inherit, hosted, custom (s url) nebo own
workspaceConnect.test Admin pracovního prostoru Znovu stáhne konfiguraci Connect pracovního prostoru a ohlásí stav
workspaceConnect.confirmPins Admin pracovního prostoru Přijme změněné identifikátory vlastního Connect pracovního prostoru

Samotná přihlášení používají oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections a oauth.disconnect. Člověkem je vždy přihlášený volající.

Přihlášení přes Connect

Sekce “Přihlášení přes Connect”
  1. Server požádá Connect o spuštění dráhy a dostane autorizační URL poskytovatele, kterou si ověří, než ji ukáže. GitHub vždy ukáže výběr účtu
  2. Člověk to schválí v prohlížeči. Poskytovatel se vrátí na Connect
  3. Connect ukáže, co bude moci server, který přihlášení spustil, dělat jako člověk, a jak dlouho. Connect nepozná, kdo ten server provozuje, takže stránka žádá člověka, aby pokračoval, jen když přihlášení spustil sám, a aby ji zavřel, když mu odkaz poslal někdo jiný. Když je prohlížeč na jiné síti, než ze které přihlášení začalo, stránka to řekne: u hostovaného serveru nebo jiného zařízení je to normální, ale přesně tak vypadá phishing. Zrušit přihlášení ukončí: kód poskytovatele se nikdy nepoužije. Každá stránka odpoví jednou; odpověď, která nepřišla ze stránky, kterou Connect právě ukázal, se odmítne
  4. Po Pokračovat ukáže Connect 8místný kód a odkaz control-center://oauth-done. Kdo kód dostane, dostane přístup, který se právě schválil, takže ho posílejte jen tam, kde přihlášení začalo
  5. Člověk kód opíše do aplikace, nebo otevře odkaz. Server si přihlášení vyzvedne s tím kódem a s vlastním důkazem požadavku

Přihlášení vyprší po 10 minutách. Pět chybných kódů ho ukončí. Odkaz, který tahle aplikace nezahájila, se odmítne hláškou Přihlášení nebylo zahájeno zde. Connect omezuje, kolik přihlášení může jedna síťová adresa zahájit, a jak často se tokeny GitHubu vydávají pro každého člověka a server, pro člověka napříč servery, pro adresu a pro celou aplikaci. Nová přihlášení mají vlastní rozpočet, takže nikdy nezdrží obnovy, které potřebují jiní lidé. Za limitem se volání odmítne s rate_limited a server to zkusí později, aniž by kohokoli odhlásil. Přihlášení nad limit člověka se na GitHubu vrátí zpět a odmítne se.

Výměna instalačního klíče

Sekce “Výměna instalačního klíče”

Výměnu klíče smí provést jen vlastník serveru, tlačítkem Vyměnit klíč na kartě Control Center Connect v Nastavení → Server → Jednotné přihlášení. Příkaz pro to není. Výměna:

  • Odhlásí všechny ze všech drah, které běží přes Connect. U každého serveru Connect, se kterým se starý klíč používal, server z něj odvolá přihlášení ke GitHubu a Slacku, která tam drží (přihlášení přes Google nemá co odvolat a vyprší)
  • Vyřadí staré ID instalace u každého z těchto serverů Connect, podepsané starým klíčem a doložené jednou pečetí, kterou server od toho Connectu drží. Od té chvíle Connect odmítne každý požadavek se starým klíčem, takže pečeť nebo kopie starého klíče odsud je k ničemu, a týmy Slacku vázané na staré ID se uvolní, aby se mohly znovu připojit. Tokeny, které už byly vydány, platí až do vypršení (hodinu u bot tokenu, osm hodin u tokenu člověka). Server, který od Connectu nemá žádnou pečeť, nemá co vyřazovat a přeskočí ho
  • Pak dá serveru nový instalační klíč a nové ID instalace
  • Pokud Connect nejde dosáhnout, nebo odmítne staré ID vyřadit, výměnu zastaví před přepnutím klíčů a ukáže Connect nemohl vyřadit starý klíč. Otočit i tak přepne klíče bez ohledu na to; staré ID instalace pak u daného Connectu zůstane použitelné, dokud nevyprší jeho tokeny, u GitHubu nejvýš 8 hodin
  • Přihlášení přes vlastní aplikace serveru nechá být
  • Vyžaduje přidání nového ID instalace na seznam povolených u vlastního Connect
Kód Význam
hosted_unprovisioned Tohle sestavení nemá klíč hostované konfigurace
signature Hostovaná konfigurace neprošla kontrolou podpisu
rollback Connect obsloužil starší konfiguraci, než jakou server už viděl
unreachable Server na Connect nedosáhne
install_blocked Connect toto ID instalace nepovoluje, nebo bylo vyřazeno
pins_changed Vlastní Connect ohlásil jiné identifikátory aplikací
protocol Connect odpověděl ve tvaru, kterému tento server nerozumí