Перейти к содержимому

Справка по Control Center Connect

Control Center Connect выполняет входы в провайдеры для серверов, которые не зарегистрировали собственных приложений. Сервер использует либо размещённый Connect от Control Center, либо Connect, который запускает его организация (Запустить сервер Connect), либо никакой. Выбор задаётся в разделе Настройки → Сервер → Единый вход → Control Center Connect, командой cc_server connect или переменной CC_CONNECT_URL. Рабочее пространство следует этому выбору, если только администратор не выбрал для него что-то другое в разделе Настройки → Рабочее пространство → Интеграции (Выбор для рабочего пространства).

В режиме Использовать свои приложения (или до того, как кто-либо выберет) канал работает на собственном приложении сервера, если оно полностью настроено, иначе недоступен. С Control Center Connect или собственным Connect Connect обслуживает каждый канал, который он предоставляет: собственные приложения сервера остаются сохранёнными, но не используются — ни для входов, ни для автоматизации сервера, ни для статуса, который сообщает сервер. Рабочее пространство, которое сделало собственный выбор, запускает каждый канал по этому выбору.

Канал Что нужно собственному приложению Через Connect
github Id приложения, закрытый ключ, id клиента и секрет клиента Люди входят в общий GitHub App
google Id клиента и секрет клиента Люди подключают Google Calendar
linear Id клиента Люди входят в Linear
linear_app Id клиента Администратор рабочего пространства подключает актора приложения Linear
slack Подключение собственного приложения Slack рабочего пространства Администратор рабочего пространства подключает Slack к общему приложению Slack
klipy KLIPY_APP_KEY Поиск GIF через прокси Connect

Собственное приложение, настроенное лишь частично, переводит свой канал в ошибку и никогда не переходит молча на Connect. Рабочее пространство на Использовать свои приложения никогда не ходит через приложения сервера или какой-либо Connect, для любого провайдера. Смена выбора Connect у сервера никого не выводит из рабочего пространства, которое сделало собственный выбор.

Connect видит Connect никогда не видит
Идентификатор установки сервера и подписи запросов Исходный код, содержимое репозиториев, diff или текст pull request
Аккаунт провайдера, который выполнил вход, — во время входа Тикеты, транскрипты или что-либо в базе данных рабочего пространства
К какому рабочему пространству относятся учётные данные — как непрозрачный id внутри печати Собственные секреты приложений сервера: они никогда не покидают сервер
Репозиторий, для которого выпускается токен GitHub для одного репозитория Токены обновления в состоянии покоя: они существуют только внутри печатей, которые хранит сервер
Команда Slack, привязанная к серверу Секреты Linear: сервер сам обменивает код Linear
Поисковые запросы GIF, когда он проксирует Klipy Пароли, ключи сопряжения или ключи провайдеров моделей
Ссылки на события Slack (команда, канал, id сообщения) и текст slash-команд Текст сообщений Slack: Connect отбрасывает его при получении, а сервер сам читает сообщение из Slack

Connect хранит начатые входы, nonce и кэши не дольше 10 минут, а почасовые счётчики использования — не дольше двух часов. Токен GitHub для одного репозитория, выпущенный как человек, остаётся записанным, запечатанным для входа, который его запросил, до истечения срока (не более 8 часов), поэтому Connect может выдать его снова и отозвать при отключении. Его единственные долговременные записи — привязки Slack (к какому серверу привязана каждая команда Slack) и выведенные из обращения идентификаторы установки. Ошибки несут код, а не ответ провайдера. Журналы записывают идентификаторы установки только как ключевые хеши, а токен GitHub — только как hashed_token, который показывает журнал аудита организации GitHub, чтобы владелец организации мог сопоставить эти два.

Режим Настройка Поведение
Не задан Новый сервер Ни один канал не использует Connect. Онбординг просит владельца сервера сделать выбор
hosted Использовать приложения Control Center https://connect.usectrl.dev с конфигурацией, подписанной офлайн. Собственные приложения сервера не используются
custom Использовать свой сервер Connect Connect по URL HTTPS (http только на loopback), которому доверяют при первом использовании. Собственные приложения сервера не используются
off Использовать свои приложения Ни один канал не использует Connect. Вход людей выполняют только собственные приложения

CC_CONNECT_URL в окружении сервера или в .env фиксирует выбор: hosted, off или URL Connect. «Настройки» тогда показывают блокировку и не могут её изменить.

В эту сборку не вкомпилирован ключ размещённой конфигурации, поэтому режим hosted сообщает hosted_unprovisioned и не обслуживает ни одного канала. Собственные приложения и свой Connect работают.

Размещённый Connect работает в одном контейнере. Его ключ печатей и закрытый ключ общего GitHub App — это переменные окружения там, а не ключи в хранилище, которое только подписывает или расшифровывает, как рекомендует GitHub для закрытого ключа App. Это известный пробел текущей настройки.

Сервер читает конфигурацию Connect не чаще чем раз в 10 минут и ждёт каждого вызова не дольше 5 секунд. Когда Connect недоступен, используется последняя корректная конфигурация, а «Настройки» помечают её устаревшей.

Настройки → Рабочее пространство → Интеграции → Control Center Connect переопределяет выбор сервера для одного рабочего пространства. Каждый участник видит выбор и то, где выполняется каждый вход; менять его может только администратор рабочего пространства.

Выбор Поведение
Как на этом сервере По умолчанию. Рабочее пространство работает по тому, что выбрал владелец сервера; опция показывает, что именно
Использовать приложения Control Center Размещённый Connect Control Center, независимо от того, что использует сервер
Использовать свои приложения Только собственные приложения рабочего пространства: GitHub App, клиент Google, приложение Linear, ключ Klipy и приложение Slack. Провайдер без них здесь выключен; частично настроенный — ошибка настройки
Использовать свой сервер Connect Connect по HTTPS-адресу, который указало рабочее пространство. Адреса в частной или локальной сети отклоняются
  • Любой выбор, кроме Как на этом сервере, держит входы в GitHub и Linear каждого человека в собственном слоте рабочего пространства, поэтому они никогда не смешиваются с общесерверными
  • Смена сначала запрашивает подтверждение: все в рабочем пространстве заново входят в GitHub, Linear и Google Calendar через новые приложения
  • Собственное подключение рабочего пространства к Slack работает при любом выборе; Добавить Control Center в Slack следует выбору
  • CC_CONNECT_URL также запрещает рабочим пространствам собственный Connect: они могут следовать за сервером или использовать собственные приложения
  • Собственный Connect рабочего пространства доверяется при первом использовании, только для этого рабочего пространства: Доверять новым приложениям там никогда не меняет то, чему доверяют сервер или другое рабочее пространство
Элемент Что это
Ключ установки 32-байтовое начальное значение в файле секретов сервера (connect_install_key), отдельно от ключей сопряжения устройств
Ключ для каждого Connect Ключ Ed25519, выведенный из начального значения и адреса Connect. Им подписывается каждый запрос к Connect (RFC 9421)
Идентификатор установки 26 символов, выведенных из этого открытого ключа. Показывается в «Настройках» и командой cc_server connect status

У одного и того же сервера для каждого адреса Connect свой идентификатор установки. Идентификатор меняется, только когда меняется ключ.

Вход через Connect возвращает печать учётных данных: зашифрованный блок, открыть который может только создавший его Connect. Она привязана к провайдеру, адресу Connect, идентификатору установки, рабочему пространству, аккаунту провайдера, приложению и поколению секрета.

  • Сервер хранит печать и идентификатор установки, для которого она запечатана. Токены доступа остаются в памяти
  • Чтобы обновить доступ, сервер отправляет печать обратно и получает новый токен доступа и новую печать
  • Печать, у которой идентификатор установки или адрес Connect больше не совпадает, удаляется при следующем чтении, и этот человек входит снова. Так бывает после смены ключа, переключения на другой Connect или восстановления каталога данных на другом сервере
  • Печать, которую Connect не может открыть, отклоняется с access_denied

Установкой общего GitHub App можно пользоваться с любого сервера. Connect не ведёт учёта того, какой сервер может ею пользоваться.

  • Установить приложение GitHub в разделе Настройки → Рабочее пространство → Интеграции открывает страницу установки приложения на GitHub. Сервер строит ссылку по имени приложения из конфигурации Connect
  • Токену для одного репозитория нужна установка приложения у владельца репозитория и доступ вошедшего человека к этому репозиторию. Это собственный токен этого человека, ограниченный его ролью, и никогда не шире
  • Организация ограничивает Control Center на GitHub: удалением установки, сужением репозиториев или удалением человека
  • Для вызовов, которые может сделать только человек, например для списка его установок, Connect передаёт серверу пользовательский токен App самого человека, а не токен для одного репозитория. Вход на сервере означает доверие этому серверу с этим токеном
  • Организация, которая требует разрешённые IP-адреса GitHub, не может использовать размещённый Connect, потому что его адреса не фиксированы. Она регистрирует собственный GitHub App — на своих серверах или на Connect, который запускает сама
  • Отключить отзывает только этот вход: Connect тратит свой токен обновления один раз и удаляет то, что тот вернул, а также пользовательский токен человека и токены для одного репозитория, которые Connect выпустил для него. Копия печати этого входа, где бы она ни хранилась, перестаёт работать. Входы человека на других серверах и в других рабочих пространствах продолжают работать. Чтобы полностью убрать Control Center из аккаунта GitHub, отзовите его в GitHub: Settings → Applications → Authorized GitHub Apps → Revoke

Токены, выпущенные как бот App (as: app), показывают на GitHub одного и того же бота для каждого сервера, который использует один и тот же Connect: GitHub не может различить эти серверы.

  • Каждый сервер может дать боту право читать и комментировать: read, review и comment (комментарии, метки, исполнители и реакции в issues и pull request)
  • Ревью pull request от имени бота (bot, который пишет pull request) разрешено только для серверов, которые оператор Connect перечислил в CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Каждому другому серверу отвечают needs_requester, и ревью публикуется по токену ответственного человека, который GitHub ограничивает этим человеком: ревью появляется от его имени. Это относится к публикации AI-ревью, комментариям ревью и запросам ревьюеров
  • Push, создание ветки и открытие pull request (write) никогда не выпускаются от имени общего бота. Они всегда используют собственный вход запрашивающего
  • Одобрение pull request никогда не автоматизируется, с любым токеном
  • Сервер или рабочее пространство с собственным GitHub App сохраняет за ботом все эти действия, включая ревью

Что должны знать владельцы и участники организации

Заголовок раздела «Что должны знать владельцы и участники организации»
  • Сервер, на котором кто-то вошёл, хранит его пользовательский токен App: до 8 часов на токен, продлеваемый до отключения. Он может действовать от его имени в каждом репозитории, где установлено общее приложение и который этот человек может читать. Connect может навсегда отключить сервер (выведенная или запрещённая установка), но уже выданный токен остаётся действительным до истечения срока
  • Установка общего GitHub App в организации даёт согласие на каждый сервер Control Center, на котором входит любой участник, а не на один сервер
  • Общий бот, как описано выше: организация не может определить на GitHub, какой сервер действовал как бот
  • Организация, которой нужна собственная граница, регистрирует собственный GitHub App и запускает собственный Connect (Запустить сервер Connect) или настраивает App на собственных серверах
Connect Как сервер доверяет его конфигурации
Размещённый Проверяет подпись Ed25519 по ключам, вкомпилированным в сборку. Отклоняет эпоху ниже самой высокой из уже виденных (rollback)
Свой При первом использовании закрепляет id приложения GitHub и id клиента, id клиентов Google и Linear, а также id приложения и клиента Slack. Изменение приостанавливает входы через Connect (pins_changed), пока владелец сервера не нажмёт Доверять новым приложениям

Настройки Connect самого сервера доступны только владельцу сервера.

Операция Что делает
connect.status Режим, URL, блокировка, идентификатор установки, состояние, эпоха конфигурации и источник каждого канала
connect.configure Задаёт hosted, custom (с url) или off
connect.test Заново получает конфигурацию и сообщает состояние
connect.confirmPins Принимает изменившиеся идентификаторы своего Connect
connect.rotateKey Создаёт новый ключ установки и новый идентификатор установки (force заменяет его, даже если Connect не смог вывести старый из обращения); см. Сменить ключ установки

Собственный выбор рабочего пространства имеет собственные операции, каждая из которых называет рабочее пространство:

Операция Кто Что делает
workspaceConnect.status Любой участник Выбор, во что он превращается, состояние и источник каждого провайдера. ID установки и ожидающие пины — только для администраторов
workspaceConnect.set Администратор рабочего пространства Задаёт inherit, hosted, custom (с url) или own
workspaceConnect.test Администратор рабочего пространства Заново получает конфигурацию Connect рабочего пространства и сообщает состояние
workspaceConnect.confirmPins Администратор рабочего пространства Принимает изменившиеся идентификаторы собственного Connect рабочего пространства

Сами входы используют oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections и oauth.disconnect. Человек — это всегда вошедший вызывающий.

  1. Сервер просит Connect начать канал и получает URL авторизации провайдера, который проверяет, прежде чем показать. GitHub всегда показывает выбор аккаунта
  2. Человек подтверждает в браузере. Провайдер возвращается в Connect
  3. Connect показывает, что сервер, начавший вход, сможет делать от имени человека и на какой срок. Connect не может определить, кто управляет этим сервером, поэтому страница просит продолжить, только если вход начал сам человек, и закрыть её, если ссылку ему прислал кто-то другой. Когда браузер находится в другой сети, чем та, из которой начат вход, страница сообщает об этом: это нормально для размещённого сервера или другого устройства, но так же выглядит фишинг. Отмена завершает вход, код провайдера не используется. Каждая страница отвечает один раз: ответ, пришедший не со страницы, которую только что показал Connect, отклоняется
  4. После Продолжить Connect показывает 8-символьный код и ссылку control-center://oauth-done. Любой, кто получит код, получит только что одобренный доступ, поэтому код передаётся только туда, где был начат вход
  5. Человек вводит код в приложении или переходит по ссылке. Сервер забирает вход с этим кодом и собственным доказательством запроса

Вход истекает через 10 минут. Пять неверных кодов завершают его. Ссылка, которую это приложение не запускало, отклоняется с сообщением Вход начат не здесь. Connect ограничивает, сколько входов может начать один сетевой адрес и как часто выпускаются токены GitHub: на человека и сервер, на человека во всех серверах, на адрес и на всё приложение в целом. У новых входов собственный бюджет, поэтому они никогда не задерживают продления, которые нужны другим людям. За пределом лимита вызов отклоняется с rate_limited, и сервер пробует позже, никого не выводя из системы. Вход сверх лимита человека отменяется на GitHub и отклоняется.

Сменить ключ может только владелец сервера, кнопкой Сменить ключ на карточке Control Center Connect в Настройки → Сервер → Единый вход. Команды для этого нет. Смена:

  • Выводит всех из каждого канала, работающего через Connect. Для каждого сервера Connect, с которым использовался старый ключ, сервер отзывает входы в GitHub и Slack, которые хранит оттуда (вход в Google отзывать нечего, и он просто истекает)
  • Выводит из обращения старый идентификатор установки на каждом из этих серверов Connect: запрос подписан старым ключом и подтверждён одной печатью учётных данных, которую сервер хранит от этого Connect. С этого момента Connect отклоняет каждый запрос со старым ключом, поэтому печать или копия старого ключа, взятые с этого сервера, бесполезны, а рабочие пространства Slack, привязанные к старому идентификатору, освобождаются и могут подключиться снова. Токены, которые уже выданы, остаются действительными до истечения срока (час для токена бота, восемь часов для токена человека). Сервер Connect, от которого у этого сервера нет печати, нечего выводить из обращения, и он пропускается
  • Затем выдаёт серверу новый ключ установки и новый идентификатор установки
  • Если сервер Connect недоступен или отказывается выводить старый идентификатор из обращения, смена останавливается до переключения ключей и показывает Connect не смог вывести старый ключ из обращения. Всё равно перевыпустить переключает ключи в любом случае; старый идентификатор установки тогда остаётся пригодным на этом Connect до истечения его токенов, для GitHub не более 8 часов
  • Не затрагивает входы через собственные приложения сервера
  • Требует добавить новый идентификатор установки в список разрешённых своего Connect
Код Значение
hosted_unprovisioned В этой сборке нет ключа размещённой конфигурации
signature Размещённая конфигурация не прошла проверку подписи
rollback Connect отдал конфигурацию старше той, что сервер уже видел
unreachable Сервер не может связаться с Connect
install_blocked Connect не разрешает этот идентификатор установки или он выведен из обращения
pins_changed Свой Connect объявил другие идентификаторы приложений
protocol Connect ответил в форме, которую этот сервер не понимает