Przejdź do głównej zawartości

Dokumentacja referencyjna Control Center Connect

Control Center Connect obsługuje logowanie do dostawców dla serwerów, które nie zarejestrowały własnych aplikacji. Serwer używa albo hostowanego Connect od Control Center, albo Connect prowadzonego przez jego organizację (Uruchom serwer Connect), albo żadnego. Wybór znajduje się w Ustawienia → Serwer → Logowanie jednokrotne → Control Center Connect, w cc_server connect albo w CC_CONNECT_URL. Obszar roboczy się do niego stosuje, chyba że administrator wybierze dla niego coś innego w Ustawienia → Obszar roboczy → Integracje (Wybór dla każdego obszaru roboczego).

Każdy dostawca to ścieżka logowania. Pod Użyj własnych aplikacji (albo zanim ktokolwiek dokona wyboru) ścieżka działa na własnej aplikacji serwera, gdy jest ona w pełni skonfigurowana, w przeciwnym razie jest niedostępna. Przy aplikacjach Control Center albo własnym serwerze Connect Connect obsługuje każdą ścieżkę, którą obsługuje: własne aplikacje serwera pozostają zapisane, ale nie są używane do logowania, do automatyzacji serwera ani do statusu, który serwer zgłasza. Obszar roboczy, który wybrał własny wybór, prowadzi każdą ścieżkę zgodnie z tym wyborem.

Ścieżka Własna aplikacja wymaga Przez Connect
github Identyfikatora aplikacji, klucza prywatnego, identyfikatora klienta i sekretu klienta Ludzie logują się do współdzielonej GitHub App
google Identyfikatora klienta i sekretu klienta Ludzie łączą Google Calendar
linear Identyfikatora klienta Ludzie logują się do Linear
linear_app Identyfikatora klienta Administrator obszaru roboczego łączy aktora aplikacji Linear
slack Połączenia własnej aplikacji Slack obszaru roboczego Administrator obszaru roboczego łączy Slacka ze współdzieloną aplikacją Slack
klipy KLIPY_APP_KEY Wyszukiwanie GIF-ów przez proxy Connect

Własna aplikacja skonfigurowana tylko częściowo zamienia swoją ścieżkę w błąd, nigdy w ciche przejście na Connect. Obszar roboczy na Użyj własnych aplikacji nigdy nie przechodzi przez aplikacje serwera ani przez żaden Connect, dla żadnego dostawcy. Zmiana wyboru Connect serwera nikogo nie wylogowuje z obszaru roboczego, który dokonał własnego wyboru.

Connect widzi Connect nigdy nie widzi
Identyfikator instalacji serwera i podpisy żądań Kodu źródłowego, zawartości repozytoriów, diffów ani tekstu pull requestów
Konto dostawcy, które się zalogowało, w trakcie logowania Zgłoszeń, transkryptów ani niczego z bazy danych obszaru roboczego
Do którego obszaru roboczego należy poświadczenie, jako nieprzejrzysty identyfikator w pieczęci Sekretów własnych aplikacji serwera: nie opuszczają serwera
Repozytorium, dla którego tworzony jest token GitHub dla jednego repozytorium Tokenów odświeżania w spoczynku: istnieją tylko w pieczęciach, które trzyma serwer
Zespół Slack powiązany z serwerem Sekretów Linear: kod od Linear serwer wymienia sam
Wyszukiwane frazy GIF-ów, gdy działa jako proxy dla Klipy Haseł, kluczy parowania ani kluczy dostawców modeli
Odnośniki do zdarzeń Slack (zespół, kanał, identyfikator wiadomości) i tekst poleceń z ukośnikiem Tekstu wiadomości Slack: Connect odrzuca go po odebraniu, a serwer sam odczytuje wiadomość ze Slacka

Connect trzyma rozpoczęte logowania, wartości nonce i pamięci podręczne najwyżej przez 10 minut, a godzinowe liczniki użycia najwyżej przez dwie godziny. Token GitHub dla jednego repozytorium, wydany jako osoba, pozostaje zapisany, zapieczętowany dla logowania, które o niego poprosiło, aż do wygaśnięcia (najwyżej 8 godzin), dzięki czemu Connect może wydać go ponownie i cofnąć przy rozłączeniu. Jego jedyne trwałe zapisy to powiązania Slack (z którym serwerem powiązany jest każdy zespół Slack) i wycofane identyfikatory instalacji. Błędy niosą kod, nigdy odpowiedź dostawcy. Dzienniki zapisują identyfikatory instalacji tylko jako skróty z kluczem, a token GitHub tylko jako hashed_token, który pokazuje dla niego dziennik audytu organizacji GitHub, dzięki czemu właściciel organizacji może oba dopasować.

Tryb Ustawienie Zachowanie
Nieustawiony Nowy serwer Żadna ścieżka nie używa Connect. Konfiguracja początkowa prosi właściciela serwera o wybór
hosted Użyj aplikacji Control Center https://connect.usectrl.dev, z konfiguracją podpisaną offline. Własne aplikacje serwera nie są używane
custom Użyj własnego serwera Connect Connect pod adresem HTTPS (http tylko na loopbacku), zaufany przy pierwszym użyciu. Własne aplikacje serwera nie są używane
off Użyj własnych aplikacji Żadna ścieżka nie używa Connect. Ludzi logują tylko własne aplikacje

CC_CONNECT_URL w środowisku serwera albo w .env blokuje wybór: hosted, off albo adres URL Connect. Ustawienia pokazują wtedy blokadę i nie mogą jej zmienić.

Ta kompilacja nie zawiera żadnego klucza konfiguracji hostowanej, więc tryb hostowany zgłasza hosted_unprovisioned i nie obsługuje żadnej ścieżki. Własne aplikacje i własny Connect działają.

Hostowany Connect działa w jednym kontenerze. Jego klucz pieczętowania i klucz prywatny współdzielonej GitHub App są tam zmiennymi środowiskowymi, a nie kluczami w sejfie, który tylko podpisuje lub odszyfrowuje, jak GitHub zaleca dla klucza prywatnego App. To znana luka obecnej konfiguracji.

Serwer odczytuje konfigurację Connect najwyżej co 10 minut i czeka na każde wywołanie najwyżej 5 sekund. Gdy Connect jest nieosiągalny, nadal obowiązuje ostatnia poprawna konfiguracja, a Ustawienia oznaczają ją jako nieaktualną.

Ustawienia → Obszar roboczy → Integracje → Control Center Connect zastępuje wybór serwera dla jednego obszaru roboczego. Każdy członek widzi wybór i miejsce, w którym działa każde logowanie; zmienia go tylko administrator obszaru roboczego.

Wybór Zachowanie
Tak samo jak ten serwer Domyślnie. Obszar roboczy działa na tym, co wybrał właściciel serwera; opcja podaje, co to jest
Użyj aplikacji Control Center Hostowany Connect Control Center, bez względu na to, czego używa serwer
Użyj własnych aplikacji Tylko aplikacje obszaru roboczego: aplikacja GitHub, klient Google, aplikacja Linear, klucz Klipy i aplikacja Slack. Dostawca bez niej jest tu wyłączony; częściowa aplikacja to błąd konfiguracji
Użyj własnego serwera Connect Connect pod adresem HTTPS podanym przez obszar roboczy. Adresy w sieci prywatnej lub lokalnej są odrzucane
  • Każdy wybór inny niż Tak samo jak ten serwer trzyma logowania do GitHuba i Linear każdej osoby w miejscu należącym do obszaru roboczego, więc nigdy nie mieszają się z ogólnoserwerowymi
  • Zmiana najpierw pyta o potwierdzenie: wszyscy w obszarze roboczym logują się ponownie do GitHuba, Linear i Kalendarza Google przez nowe aplikacje
  • Własne połączenie aplikacji Slack obszaru roboczego działa przy każdym wyborze; Dodaj Control Center do Slack podąża za wyborem
  • CC_CONNECT_URL blokuje też obszary robocze przed własnym Connect: mogą podążać za serwerem albo używać własnych aplikacji
  • Własny Connect obszaru roboczego jest zaufany przy pierwszym użyciu tylko dla tego obszaru roboczego: Zaufaj nowym aplikacjom tam nigdy nie zmienia tego, czemu ufa serwer albo inny obszar roboczy
Element Czym jest
Klucz instalacji 32-bajtowe ziarno w pliku sekretów serwera (connect_install_key), oddzielone od kluczy parowania urządzeń
Klucz dla danego Connect Klucz Ed25519 wyprowadzony z ziarna i adresu Connect. Każde żądanie do Connect jest nim podpisywane (RFC 9421)
Identyfikator instalacji 26 znaków wyprowadzonych z tego klucza publicznego. Pokazują go Ustawienia i cc_server connect status

Ten sam serwer ma inny identyfikator instalacji dla każdego adresu Connect. Identyfikator zmienia się tylko przy wymianie klucza.

Logowanie przez Connect zwraca pieczęć poświadczenia: zaszyfrowany blob, który może otworzyć tylko Connect, który go utworzył. Jest powiązana z dostawcą, adresem Connect, identyfikatorem instalacji, obszarem roboczym, kontem dostawcy, aplikacją i generacją sekretu.

  • Serwer zapisuje pieczęć i identyfikator instalacji, dla którego ją zapieczętowano. Tokeny dostępu pozostają w pamięci
  • Aby odświeżyć, serwer odsyła pieczęć i dostaje nowy token dostępu oraz nową pieczęć
  • Pieczęć, której identyfikator instalacji albo adres Connect już się nie zgadza, jest usuwana przy następnym odczycie, a ta osoba loguje się ponownie. Dzieje się tak po wymianie klucza, przejściu na inny Connect albo przywróceniu katalogu danych na innym serwerze
  • Pieczęć, której Connect nie potrafi otworzyć, jest odrzucana z access_denied

Instalacji współdzielonej GitHub App może używać każdy serwer. Connect nie prowadzi zapisu, który serwer może z niej korzystać.

  • Zainstaluj aplikację GitHub w Ustawienia → Obszar roboczy → Integracje otwiera stronę instalacji aplikacji na GitHubie. Serwer buduje link z nazwy aplikacji w konfiguracji Connect
  • Token dla jednego repozytorium wymaga, by aplikacja była zainstalowana u właściciela repozytorium, a zalogowana osoba miała dostęp do tego repozytorium. To własny token tej osoby, ograniczony do jej roli, nigdy szerszy
  • Organizacja ogranicza Control Center na GitHubie: usuwając instalację, zawężając repozytoria albo usuwając osobę
  • Do wywołań, które może wykonać tylko osoba, na przykład listowania jej instalacji, Connect przekazuje serwerowi osobisty token użytkownika App tej osoby, a nie token dla jednego repozytorium. Zalogowanie się na serwerze to powierzenie mu tego tokenu
  • Organizacja egzekwująca listę dozwolonych adresów IP GitHub nie może korzystać z hostowanego Connect, którego adresy nie są stałe. Zamiast tego rejestruje własną GitHub App, na swoich serwerach albo w Connect, który sama prowadzi
  • Rozłącz cofa tylko to logowanie: Connect zużywa token odświeżania raz i usuwa to, co on zwróci, usuwa swój token użytkownika oraz tokeny dla jednego repozytorium, które dla niego wydał. Kopia jego pieczęci, gdziekolwiek przechowywana, przestaje działać. Logowania tej osoby na innych serwerach i w innych obszarach roboczych dalej działają. Aby całkowicie usunąć Control Center z konta GitHub, cofnij dostęp w GitHubie w Settings → Applications → Authorized GitHub Apps → Revoke

Tokeny wydane jako bot App (as: app) pokazują ten sam bot na GitHubie dla każdego serwera, który korzysta z tego samego Connect: GitHub nie potrafi rozróżnić tych serwerów.

  • Każdy serwer może dać botowi odczyt i komentowanie: read, review i comment (komentarze, etykiety, osoby przypisane i reakcje w issues i pull requestach)
  • Recenzowanie pull requesta jako bot (bot, który zapisuje pull requesty) jest dozwolone tylko dla serwerów, które operator Connect umieszcza w CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Każdy inny serwer dostaje odpowiedź needs_requester i publikuje recenzję tokenem osobistym odpowiedzialnej osoby, który GitHub ogranicza do tej osoby: recenzja pojawia się pod jej nazwiskiem. Dotyczy to publikowania recenzji AI, komentarzy do recenzji i próśb o recenzentów
  • Push, tworzenie gałęzi i otwieranie pull requesta (write) nigdy nie są wydawane jako wspólny bot. Zawsze używają własnego logowania osoby zlecającej
  • Zatwierdzanie pull requesta nigdy nie jest zautomatyzowane, na żadnym tokenie
  • Serwer lub obszar roboczy z własną GitHub App zachowuje bota we wszystkim powyższym, łącznie z recenzjami

Co właściciele i członkowie organizacji powinni wiedzieć

Dział zatytułowany „Co właściciele i członkowie organizacji powinni wiedzieć”
  • Serwer, na którym ktoś się zalogował, przechowuje jego osobisty token użytkownika App: do 8 godzin na token, odnawiany, aż osoba się rozłączy. Może działać jako ona w każdym repozytorium, na którym zainstalowana jest wspólna App i do którego ta osoba ma dostęp. Connect może odciąć serwer na stałe (wycofana lub odrzucona instalacja), ale token już wydany pozostaje ważny do wygaśnięcia
  • Zainstalowanie wspólnej GitHub App w organizacji wyraża zgodę dla każdego serwera Control Center, na którym zaloguje się członek, a nie dla jednego serwera
  • Bot jest wspólny, jak wyżej: organizacja nie może sprawdzić na GitHubie, który serwer działał jako bot
  • Organizacja, która chce własnej granicy, rejestruje własną GitHub App i prowadzi własny Connect (Uruchom serwer Connect) albo konfiguruje App na własnych serwerach
Connect Jak serwer ufa jego konfiguracji
Hostowany Weryfikuje podpis Ed25519 względem kluczy wkompilowanych w kompilację. Odrzuca epokę niższą od najwyższej, jaką już widział (rollback)
Własny Przy pierwszym użyciu przypina identyfikator aplikacji i identyfikator klienta GitHub, identyfikatory klientów Google i Linear oraz identyfikatory aplikacji i klienta Slack. Zmiana wstrzymuje logowania przez Connect (pins_changed), dopóki właściciel serwera nie naciśnie Zaufaj nowym aplikacjom

Ustawienia Connect serwera może zmieniać tylko właściciel serwera.

Operacja Co robi
connect.status Tryb, adres URL, blokada, identyfikator instalacji, stan, epoka konfiguracji i źródło każdej ścieżki
connect.configure Ustawia hosted, custom (z url) albo off
connect.test Ponownie pobiera konfigurację i zgłasza stan
connect.confirmPins Akceptuje zmienione identyfikatory własnego Connect
connect.rotateKey Tworzy nowy klucz instalacji i nowy identyfikator instalacji (force zastępuje go nawet wtedy, gdy Connect nie mógł wycofać starego); zobacz Wymień klucz instalacji

Wybór obszaru roboczego ma własne operacje, a każda nazywa obszar roboczy:

Operacja Kto Co robi
workspaceConnect.status Każdy członek Wybór, na co się rozwiązuje, stan i źródło każdej ścieżki. Identyfikator instalacji i oczekujące przypięcia tylko dla administratorów
workspaceConnect.set Administrator obszaru roboczego Ustawia inherit, hosted, custom (z url) albo own
workspaceConnect.test Administrator obszaru roboczego Ponownie pobiera konfigurację Connect obszaru roboczego i zgłasza stan
workspaceConnect.confirmPins Administrator obszaru roboczego Akceptuje zmienione identyfikatory własnego Connect obszaru roboczego

Same logowania używają oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections i oauth.disconnect. Osobą jest zawsze zalogowany wywołujący.

  1. Serwer prosi Connect o rozpoczęcie ścieżki i dostaje adres URL autoryzacji dostawcy, który sprawdza, zanim go pokaże. GitHub zawsze pokazuje swój wybór konta
  2. Osoba zatwierdza w przeglądarce. Dostawca wraca do Connect
  3. Connect pokazuje, co serwer, który rozpoczął logowanie, będzie mógł robić jako ta osoba i jak długo. Connect nie potrafi stwierdzić, kto obsługuje ten serwer, więc strona prosi osobę o kontynuację tylko wtedy, gdy sama rozpoczęła logowanie, a o zamknięcie jej, gdy ktoś przysłał jej link. Gdy przeglądarka jest w innej sieci niż ta, z której rozpoczęto logowanie, strona o tym mówi: to normalne dla hostowanego serwera lub innego urządzenia, ale też tak wygląda phishing. Anuluj kończy logowanie: kod dostawcy nigdy nie jest używany. Każda strona odpowiada raz: odpowiedź, która nie pochodzi ze strony, którą Connect właśnie pokazał, jest odrzucana
  4. Po Kontynuuj Connect pokazuje 8-znakowy kod i link control-center://oauth-done. Każdy, kto dostanie kod, dostaje dostęp, który właśnie zatwierdzono, więc kod trafia tylko tam, gdzie rozpoczęto logowanie
  5. Osoba wpisuje kod w aplikacji albo otwiera link. Serwer odbiera logowanie z tym kodem i z własnym dowodem żądania

Logowanie wygasa po 10 minutach. Pięć błędnych kodów je kończy. Link, którego ta aplikacja nie rozpoczęła, jest odrzucany komunikatem Logowanie nie zostało rozpoczęte tutaj. Connect ogranicza, ile logowań jeden adres sieciowy może rozpocząć i jak często tokeny GitHub są wydawane: na osobę i serwer, na osobę we wszystkich serwerach, na adres oraz dla całej aplikacji. Nowe logowania mają własny budżet, więc nigdy nie wstrzymują odnowień, na których zależy innym osobom. Po przekroczeniu limitu wywołanie jest odrzucane kodem rate_limited, a serwer ponawia je później, nie wylogowując nikogo. Logowanie ponad limit osoby jest cofane w GitHubie i odrzucane.

Tylko właściciel serwera może wymienić klucz, przyciskiem Wymień klucz na karcie Control Center Connect w Ustawienia → Serwer → Logowanie jednokrotne. Nie ma do tego polecenia. Wymiana:

  • Wylogowuje wszystkich ze wszystkich ścieżek, które działają przez Connect. Dla każdego serwera Connect, z którym używano starego klucza, serwer cofa logowania GitHub i Slack, które od tego miejsca trzyma (logowanie Google nie ma czego cofać i po prostu wygasa)
  • Wycofuje stary identyfikator instalacji na każdym z tych serwerów Connect, podpisując go starym kluczem i dowodząc jedną pieczęcią poświadczenia, którą serwer trzyma z tego Connect. Od tej chwili Connect odrzuca każde żądanie złożone starym kluczem, więc pieczęć albo kopia starego klucza pobrana z tego serwera jest bezużyteczna, a obszary robocze Slack powiązane ze starym identyfikatorem zostają zwolnione, by mogły połączyć się ponownie. Tokeny już wydane pozostają ważne do wygaśnięcia (godzina dla tokenu bota, osiem godzin dla tokenu osoby). Serwer Connect, z którym ten serwer nie ma żadnej pieczęci, nie ma czego wycofać i jest pomijany
  • Następnie daje serwerowi nowy klucz instalacji i nowy identyfikator instalacji
  • Jeśli serwer Connect jest nieosiągalny albo odmawia wycofania starego identyfikatora, zatrzymuje się przed zmianą kluczy i pokazuje Connect nie mógł wycofać starego klucza. Zrotuj mimo to zmienia klucze mimo wszystko; stary identyfikator instalacji pozostaje wtedy użyteczny w tym Connect, dopóki jego tokeny nie wygasną, najwyżej 8 godzin dla GitHub
  • Nie zmienia logowań przez własne aplikacje serwera
  • Wymaga dodania nowego identyfikatora instalacji do listy dozwolonych własnego Connect
Kod Znaczenie
hosted_unprovisioned Ta kompilacja nie ma klucza konfiguracji hostowanej
signature Konfiguracja hostowana nie przeszła weryfikacji podpisu
rollback Connect udostępnił starszą konfigurację niż ta, którą serwer już widział
unreachable Serwer nie może połączyć się z Connect
install_blocked Connect nie zezwala na ten identyfikator instalacji albo został wycofany
pins_changed Własny Connect ogłosił inne identyfikatory aplikacji
protocol Connect odpowiedział w formie, której ten serwer nie rozumie