Справка по 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 видит и чего не видит никогда»| 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
Заголовок раздела «Установки GitHub»Установкой общего 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. Человек — это всегда
вошедший вызывающий.
Вход через Connect
Заголовок раздела «Вход через Connect»- Сервер просит Connect начать канал и получает URL авторизации провайдера, который проверяет, прежде чем показать. GitHub всегда показывает выбор аккаунта
- Человек подтверждает в браузере. Провайдер возвращается в Connect
- Connect показывает, что сервер, начавший вход, сможет делать от имени человека и на какой срок. Connect не может определить, кто управляет этим сервером, поэтому страница просит продолжить, только если вход начал сам человек, и закрыть её, если ссылку ему прислал кто-то другой. Когда браузер находится в другой сети, чем та, из которой начат вход, страница сообщает об этом: это нормально для размещённого сервера или другого устройства, но так же выглядит фишинг. Отмена завершает вход, код провайдера не используется. Каждая страница отвечает один раз: ответ, пришедший не со страницы, которую только что показал Connect, отклоняется
- После Продолжить Connect показывает 8-символьный код и ссылку
control-center://oauth-done. Любой, кто получит код, получит только что одобренный доступ, поэтому код передаётся только туда, где был начат вход - Человек вводит код в приложении или переходит по ссылке. Сервер забирает вход с этим кодом и собственным доказательством запроса
Вход истекает через 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 ответил в форме, которую этот сервер не понимает |