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).
Dráhy
Sekce “Dráhy”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žimy
Sekce “Režimy”| 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_URLtaké 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
Identita instalace
Sekce “Identita instalace”| 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
Instalace GitHubu
Sekce “Instalace GitHubu”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
Sdílený bot
Sekce “Sdílený bot”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,reviewacomment(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 vCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Každý jiný server dostane odpověďneeds_requestera 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
Důvěra v konfiguraci
Sekce “Důvěra v konfiguraci”| 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 |
Operace
Sekce “Operace”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”- 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
- Člověk to schválí v prohlížeči. Poskytovatel se vrátí na Connect
- 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
- 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 - Č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
Stavové kódy
Sekce “Stavové kódy”| 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í |