Довідка з 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 там — це змінні середовища, а не ключі в сховищі, яке лише підписує чи розшифровує, як GitHub рекомендує для приватного ключа застосунку. Це відома прогалина поточного налаштування.
Сервер читає конфігурацію 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 у Налаштування → Застосунки → Авторизовані застосунки GitHub → Відкликати
Спільний бот
Розділ із назвою «Спільний бот»Токени, випущені як бот App (as: app), показують на GitHub того самого бота для
кожного сервера, який використовує той самий Connect: GitHub не може відрізнити ці
сервери один від одного.
- Кожен сервер може дозволити боту читати й коментувати:
read,reviewіcomment(коментарі, мітки, виконавці та реакції на issues і pull requests) - Рев’ю pull request від імені бота (
bot, який записує pull requests) дозволено лише для серверів, які оператор Connect перелічив уCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Кожному іншому серверу відповідаютьneeds_requester, і рев’ю публікується за власним токеном відповідальної людини, який GitHub обмежує цією людиною: рев’ю з’являється під її іменем. Це охоплює публікацію рев’ю ШІ, коментарі до рев’ю та запити рев’юерів - Push, створення гілки та відкриття pull request (
write) ніколи не випускаються як спільний бот. Вони завжди використовують власний вхід запитувача - Схвалення pull request ніколи не автоматизується, з жодним токеном
- Сервер або робочий простір із власним GitHub App зберігає бота для всього цього, зокрема рев’ю
Що мають знати власники та учасники організацій
Розділ із назвою «Що мають знати власники та учасники організацій»- Сервер, на якому хтось увійшов, тримає токен користувача його App: до 8 годин на токен, оновлюваний, доки людина не відключиться. Він може діяти від її імені в кожному репозиторії, де встановлено спільний App і до якого вона має доступ. Connect може відрізати сервер назавжди (вибракуваний або заборонений встановлення), але токен, який уже видано, лишається чинним, доки не спливе
- Встановлення спільного GitHub App в організації дає згоду для кожного сервера Control Center, на якому будь-який учасник входить, а не для одного сервера
- Бот спільний, як описано вище: організація не може визначити на GitHub, який сервер діяв як бот
- Організація, яка хоче власну межу, реєструє власний GitHub App і запускає власний Connect (Запустити сервер Connect) або налаштовує застосунок на власних серверах
Довіра до конфігурації
Розділ із назвою «Довіра до конфігурації»| 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, доки не спливуть його токени, — не більше 8 годин для GitHub
- Не зачіпає входи через власні застосунки сервера
- Вимагає додати новий ідентифікатор встановлення до списку дозволених власного Connect
Коди стану
Розділ із назвою «Коди стану»| Код | Значення |
|---|---|
hosted_unprovisioned |
У цій збірці немає ключа розміщеної конфігурації |
signature |
Розміщена конфігурація не пройшла перевірку підпису |
rollback |
Connect віддав конфігурацію, старішу за ту, яку сервер уже бачив |
unreachable |
Сервер не може зв’язатися з Connect |
install_blocked |
Connect не дозволяє цей ідентифікатор встановлення, або його виведено з обігу |
pins_changed |
Власний Connect оголосив інші ідентифікатори застосунків |
protocol |
Connect відповів у формі, якої цей сервер не розуміє |