Перейти до вмісту

Запустити сервер Connect

Control Center Connect виконує входи в провайдерів (GitHub, Google Calendar, Linear, Slack) для серверів, які не зареєстрували власних застосунків. Цей посібник показує, як запустити власний Connect, щоб застосунки провайдерів, їхні секрети й список серверів, яким дозволено ними користуватися, залишалися у вас.

Що Connect може й чого не може бачити, описано в довідці про Connect. Прочитайте її спершу, якщо вирішуєте, чи запускати власний.

  • Публічна адреса HTTPS для Connect, наприклад https://connect.example.com, за проксі, що термінує TLS. Звичайний http приймається лише на loopback
  • Docker або cc_server, який можна перезапустити з додатковими змінними середовища
  • Право реєструвати застосунки в кожного провайдера, якого ви хочете обслуговувати
  • Сервери, які ним користуватимуться, і їхні власники під рукою: кожен сервер має ідентифікатор встановлення, який ви додаєте до списку дозволених Connect

Виберіть URL зараз і більше його не змінюйте. CONNECT_PUBLIC_URL входить в усе, що робить Connect: до нього прив’язані підписи запитів, запечатані облікові дані, URL переспрямування провайдерів та ідентифікатор встановлення кожного сервера. Змінити його пізніше — означає заново зареєструвати переспрямування й змусити кожну людину ввійти знову.

Крок 2: Зареєструйте застосунки провайдерів

Розділ із назвою «Крок 2: Зареєструйте застосунки провайдерів»

Реєструйте лише тих провайдерів, яких хочете обслуговувати. Провайдер із неповним набором змінних виключається з конфігурації Connect, і сервери бачать його недоступним. Нижче <base> — це ваш CONNECT_PUBLIC_URL.

Провайдер Що зареєструвати Що зберегти
Застосунок GitHub Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup з увімкненим Redirect on update. Залиште Request user authorization (OAuth) during installation вимкненим: якщо його ввімкнено, GitHub ігнорує setup URL. Залиште Expire user authorization tokens увімкненим Id застосунку, slug, id клієнта, секрет клієнта, приватний ключ
Google Клієнт OAuth типу Web application з URI переспрямування <base>/oauth/google/callback і ввімкнений Google Calendar API Id клієнта, секрет клієнта
Linear Застосунок OAuth з URL зворотного виклику <base>/oauth/linear/callback і <base>/oauth/linear_app/callback Лише id клієнта
Slack Redirect URLs <base>/oauth/slack_oidc/callback і <base>/oauth/slack/callback. Event Subscriptions за адресою <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash-команди за адресою <base>/v1/hooks/slack/commands. Ротацію токенів увімкнено Id застосунку, id клієнта, секрет клієнта, секрет підпису

Надайте GitHub App такі дозволи на репозиторій: Metadata — читання, Contents — читання й запис, Pull requests — читання й запис, Issues — читання й запис, Checks, Actions і Commit statuses — читання. Для запитів на рев’ю від команд додайте дозвіл організації Members на читання. Вебхуки можна залишити вимкненими: сервери опитують.

Connect потребує приватного ключа GitHub App (Generate a private key у налаштуваннях App). Він підписує запити App, які знаходять встановлення, що покриває репозиторій (або, коли такого немає, встановлення власника), і випускає токен встановлення для одного репозиторію, кожен лише після того, як власний вхід людини, яка питає, довів доступ до цього репозиторію.

Кожен сервер на вашому Connect має спільного бота застосунку. Він може читати, коментувати, ставити мітки й реагувати від імені бота в будь-якому з них. Рев’ю pull requests від імені бота дозволені лише для серверів, які ви перелічили в CONNECT_GITHUB_REVIEW_BOT_INSTALLS (їхні ідентифікатори встановлення через кому); кожен інший сервер публікує рев’ю токеном самого рев’юера. Push ніколи не виконується від імені бота. Щоб дозволити власному серверу рев’ю від імені бота, додайте туди його ідентифікатор встановлення й перезапустіть. Зберігайте файл ключа як секрет, як ключ печатки. Linear не потребує секрету: Connect повертає код серверу, який сам завершує обмін.

Крок 3: Зберіть ідентифікатори встановлення

Розділ із назвою «Крок 3: Зберіть ідентифікатори встановлення»

Connect відповідає лише серверам зі свого списку дозволених. На кожному сервері спрямуйте його на свій Connect, а потім прочитайте його ідентифікатор встановлення:

  1. Відкрийте Налаштування → Сервер → Єдиний вхід, відкрийте картку Control Center Connect і виберіть Використовувати власний сервер Connect
  2. Введіть свій URL і збережіть. Картка покаже Ідентифікатор встановлення сервера

З термінала на хості сервера те саме виглядає так:

Вікно термінала
cc_server connect enable --url https://connect.example.com
cc_server connect status

status друкує ідентифікатор встановлення. Доки не виконано крок 5, він показує install_blocked, і це очікувано.

Ідентифікатор встановлення виводиться для кожної адреси Connect окремо, тож той самий сервер має для кожного Connect, з яким спілкується, власний ідентифікатор. Він змінюється лише тоді, коли власник сервера змінює ключ.

Connect шифрує всі облікові дані, які повертає, ключем печатки. Створіть його й зберігайте як файл із секретом:

Вікно термінала
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

Втрата ключа печатки виводить усіх із системи: без нього жодну печатку не відкрити.

Кожен випуск публікує ghcr.io/samuelalev/cc-connect із підтвердженням походження збірки. У продакшені закріплюйте тег версії.

Вікно термінала
docker run -d --name cc-connect -p 8790:8790 \
-e CONNECT_PUBLIC_URL=https://connect.example.com \
-e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \
-e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \
-v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \
-e CONNECT_GITHUB_APP_ID=123456 \
-e CONNECT_GITHUB_APP_SLUG=acme-control-center \
-e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \
-e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \
-v "$PWD/github_secret:/run/secrets/github:ro" \
-e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \
-v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \
-v cc-connect-data:/data \
ghcr.io/samuelalev/cc-connect:latest

Спрямуйте зворотний проксі на порт 8790 і задайте CONNECT_TRUST_PROXY як кількість проксі перед Connect, щоб його ліміт на адресу бачив адресу кожного клієнта. Образ працює від непривілейованого користувача, зберігає свій стан у томі /data і має вбудовану перевірку працездатності (cc-connect --healthcheck, яка опитує /healthz: процес відповідає). /readyz також перевіряє, що його сховища стану й прив’язок відповідають, і що Redis, якщо його використовують, досі працює з maxmemory-policy noeviction; вкажіть на це перевірку готовності оркестратора.

Сторінка згоди на вхід відповідає формою POST, яку Connect приймає лише зі своєї сторінки: Sec-Fetch-Site, якщо його надіслано, має бути same-origin, а Origin, якщо його надіслано, має бути джерелом CONNECT_PUBLIC_URL; POST без жодного з них відхиляється. Тож проксі має передавати обидва заголовки без змін, а CONNECT_PUBLIC_URL має бути адресою, яку справді використовують браузери людей. Якщо продовження на цій сторінці завжди показує “This link has expired”, а журнал показує oauth.done_refused із причиною origin або no_origin, один із цих двох налаштувань вимкнено.

Connect відмовляється запускатися (код виходу 78), якщо його конфігурація відкрита, небезпечна або незавершена, і друкує, яка змінна неправильна. Його зупиняють відсутній список дозволених, адреса http не на loopback, некоректний ключ печатки або одночасно задані NAME і NAME_FILE.

Контрольна точка: на кожному сервері картка Connect показує Працює, а Де виконується кожен вхід називає Connect для кожного зареєстрованого вами провайдера. cc_server connect status друкує Health: ok і ті самі канали.

Сервер може сам розміщувати Connect замість окремого контейнера. Змонтований сервіс — той самий, що запускає образ.

  1. Помістіть змінні CONNECT_* у файл .env сервера, як на кроці 5. Сервер відмовляється запускатися, якщо будь-який секрет Connect, зокрема CONNECT_SENTRY_DSN, експортовано в його середовищі
  2. Додайте CC_SERVER_CONNECT_HOST=on
  3. Перезапустіть сервер. Його журнал надрукує embedded Connect at <url>
Вікно термінала
CC_SERVER_CONNECT_HOST=on
CONNECT_ALLOWED_INSTALLS=<install id>
CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>
CONNECT_GITHUB_APP_ID=123456
CONNECT_GITHUB_APP_SLUG=acme-control-center
CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd
CONNECT_GITHUB_CLIENT_SECRET=<secret>
CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pem

Після цього Connect обслуговується за адресою <server>/connect:

  • CONNECT_PUBLIC_URL типово — джерело публічного URL сервера плюс /connect. За проксі задайте його явно. Його шлях має бути рівно /connect, і він має бути HTTPS, якщо це не loopback
  • До змонтованого сервісу доходять лише змінні CONNECT_*, тож він ніколи не позичає власні застосунки провайдерів сервера
  • CONNECT_ALLOWED_INSTALLS і далі обов’язковий, зокрема для самого сервера, що розміщує Connect
  • Неправильно налаштоване монтування не дає серверу завантажитися, а не обслуговує відкритого брокера
  • Демонстраційний сервер його ніколи не монтує

Зареєструйте переспрямування провайдерів на https://<server>/connect, потім спрямуйте сервери (включно з тим, що розміщує) на цей URL, як на кроці 3.

Кожне налаштування — це змінна середовища. Будь-який секрет можна натомість брати зі змонтованого файлу: задайте NAME_FILE замість NAME. Connect перечитує файл не частіше ніж раз на 30 секунд і зберігає останнє коректне значення. Секрети з позначкою подвійний під час зміни також приймають NAME_PREVIOUS (або NAME_PREVIOUS_FILE).

Змінна Типово Значення
CONNECT_PUBLIC_URL обов’язкова Канонічний публічний URL. HTTPS або http лише на loopback. Шлях означає монтування. Без query і фрагмента
CONNECT_ALLOWED_INSTALLS обов’язкова Ідентифікатори встановлення через кому. * приймається лише разом із CONNECT_SIGNED_CONFIG_FILE
CONNECT_DENY_INSTALLS Ідентифікатори встановлення, яким відмовляють, навіть якщо їх дозволено
CONNECT_GITHUB_ALLOWED_OWNERS Числові id власників GitHub. Якщо задано, токени репозиторіїв випускаються лише для репозиторіїв, що їм належать. Це не обмежує, хто може ввійти: людина, якій дозволено користуватися цим Connect, усе одно отримує власний токен користувача App. Щоб обслуговувати лише одну організацію, тримайте App приватним для неї
CONNECT_GITHUB_REVIEW_BOT_INSTALLS Ідентифікатори встановлення, яким дозволено рев’ю pull requests від імені бота. Порожньо за замовчуванням; * відхиляється, і кожен id також має бути дозволений
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Адреса прив’язки й порт
CONNECT_TRUST_PROXY 0 Довірені переходи проксі в X-Forwarded-For (від 0 до 8). Використовується лише для лімітів на адресу, підказки мережі на сторінці входу та записаної адреси в журналі. За проксі 0 рахує кожного клієнта як проксі, і журнал повідомляє про це один раз
Змінна Типово Значення
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID GitHub App
CONNECT_GITHUB_CLIENT_SECRET Секрет, подвійний
CONNECT_GITHUB_APP_PRIVATE_KEY Секрет. Приватний ключ App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Клієнт Google. Секрет подвійний
CONNECT_LINEAR_CLIENT_ID Застосунок Linear. Без секрету
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID Застосунок Slack
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Секрети, подвійні
CONNECT_KLIPY_APP_KEY Ключ пошуку GIF Klipy. Секрет, подвійний
CONNECT_KLIPY_MODE proxy proxy залишає ключ у Connect; key передає його серверам
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google і Slack: покоління, що записується в нові печатки
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google і Slack: для старіших печаток потрібно ввійти знову
CONNECT_<LANE>_ACCEPTS_NEW true Будь-який канал: false зупиняє нові входи, а наявні й далі оновлюються
Змінна Типово Значення
CONNECT_SEAL_BACKEND local local або gcp-kms
CONNECT_SEAL_KEYS Секрет, обов’язковий для local. Записи kid:key через кому, найновіший першим; старі записи й далі розшифровують
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, обов’язковий для gcp-kms
CONNECT_STATE memory memory для одного екземпляра, redis для кількох. Повне сховище в пам’яті відмовляє в нових входах і запитах, а не забуває живий запис
CONNECT_REDIS_URL Секрет. redis:// або rediss://. Redis 6.2 або новіший із maxmemory-policy noeviction, обидва перевіряються під час запуску
CONNECT_REDIS_CA_FILE Пакет CA для rediss://
CONNECT_BINDINGS file Де зберігаються прив’язки команд Slack: file або firestore
CONNECT_DATA_DIR data (/data в образі) Містить bindings.json. Його блокує один Connect: другий на тому самому каталозі не запускається
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE база даних (default) Для CONNECT_BINDINGS=firestore. Connect не запускається, коли Firestore не відповідає
Змінна Типово Значення
CONNECT_SIGNED_CONFIG_FILE Конфігурація, підписана офлайн, віддається як є. Використовується розміщеним Connect від Control Center
CONNECT_CONFIG_PUBLIC_KEYS Ключі, за якими має перевірятися підписана конфігурація
CONNECT_CONFIG_EPOCH 1 Епоха конфігурації, яку генерує самостійно розміщений Connect
CONNECT_LOG_HMAC_KEY випадковий для кожного процесу Секрет. Задайте його, щоб мітки, які заміняють ідентифікатори встановлення, лишалися стабільними між перезапусками й екземплярами
CONNECT_SENTRY_DSN Секрет. https-DSN Sentry, куди надсилаються рядки помилок: тип помилки, кадри стеку, маршрут і ідентифікатор запиту, ніколи повідомлення, тіло чи заголовок
CONNECT_SENTRY_ENVIRONMENT self-hosted Середовище Sentry
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Повідомляються через /v1/version
CONNECT_RATE_INSTALL_PER_MINUTE 600 Запитів на встановлення
CONNECT_RATE_IP_PER_MINUTE 300 Запитів на адресу (адреса IPv6 рахується за /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Запитів на весь екземпляр
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Доставок подій і команд Slack на адресу, рахуються окремо від інших запитів
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Доставок подій і команд Slack для всього екземпляра
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Подій Slack на команду
CONNECT_RATE_KLIPY_PER_MINUTE 120 Пошуків GIF на встановлення
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 Пошуків GIF на адресу, на всіх серверах
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Розпочатих входів на адресу
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 Токенів GitHub, виданих на обліковий запис GitHub на одному сервері (входи, оновлення, токени репозиторіїв)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × вище (120) Те саме на обліковий запис GitHub на всіх серверах
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 Токенів GitHub, виданих на адресу
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Нові входи GitHub для всього застосунку
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Токенів бота на сервер
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Токенів бота на обліковий запис GitHub, що питає, на всіх серверах
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Токенів бота для всього застосунку
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Оновлення й токени репозиторіїв для всього застосунку. Нові входи мають власний ліміт вище
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Живих токенів репозиторіїв, які один обліковий запис GitHub може мати, перш ніж Connect запише попередження в журнал
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Виведених з обігу ідентифікаторів встановлення на адресу (на /48 для IPv6)

Виклик за межею ліміту отримує відповідь rate_limited. Сервери повторюють пізніше і ніколи через це не виводять когось із системи.

Більшості організацій достатньо одного екземпляра з CONNECT_STATE=memory. Кільком екземплярам за однією адресою потрібні CONNECT_STATE=redis і CONNECT_BINDINGS=firestore, щоб вхід, розпочатий на одному екземплярі, міг завершитися на іншому, а кожен екземпляр бачив ті самі прив’язки Slack і виведені з обігу ідентифікатори встановлення. Спільний CONNECT_DATA_DIR не працює: перший Connect його блокує. Ліміти запитів на встановлення, адресу й весь екземпляр діють окремо на кожному екземплярі; ліміти на входи, токени GitHub, токени бота, пошуки GIF на адресу, виведення з обігу та команди Slack спільні через сховище стану.

Ніхто не виходить із системи:

  1. Створіть новий секрет у провайдера й збережіть старий
  2. Перенесіть старе значення в NAME_PREVIOUS, помістіть нове в NAME і збільште CONNECT_<LANE>_SECRET_GENERATION. Змонтовані файли підхоплюються протягом 30 секунд
  3. Дочекайтеся оновлення входів, потім видаліть старий секрет у провайдера й приберіть NAME_PREVIOUS

Щоб змінити ключ печатки, поставте новий запис cc-connect-config seal-key першим у CONNECT_SEAL_KEYS і збережіть старий, доки його печатки не оновляться.

Сервери запам’ятовують id застосунку й клієнта, які ваш Connect оголосив, коли вони вперше ним скористалися. Якщо ви заміните застосунок, картка Connect на кожному сервері покаже Застосунки Connect змінилися, і входи через Connect призупиняться, доки власник сервера не натисне Довіряти новим застосункам. Попередьте власників серверів перед перемиканням, щоб вони знали, що це запит від вас.

Додайте його ідентифікатор встановлення в CONNECT_DENY_INSTALLS і перезапустіть. Його власник побачить «Connect заблокував ідентифікатор встановлення цього сервера. Зверніться до оператора вашого сервера Connect.», і всі входи через Connect на ньому зупиняться.

Сервер також виводить із обігу власний старий ідентифікатор встановлення, коли його власник змінює ключ. Він доводить, що ідентифікатор його власний, однією печаткою облікових даних, яку цей Connect створив для нього, тож виводити ідентифікатор може лише сервер, який уже впускав когось. Connect зберігає виведені з обігу ідентифікатори назавжди, тож старий ключ і кожна печатка, створена для нього, перестають працювати, а команди Slack, прив’язані до старого ідентифікатора, звільняються. Токени, які вже видано, спливають самі: протягом 8 годин для токена людини і 1 години для токена бота. Connect тримає не більше 100 000 виведених з обігу ідентифікаторів; після цього ротацію відхиляють, і журнал повідомляє про це на рівні error.

Сервер повідомляє, що Connect його заблокував

Розділ із назвою «Сервер повідомляє, що Connect його заблокував»

Його ідентифікатора встановлення немає в CONNECT_ALLOWED_INSTALLS, він є в CONNECT_DENY_INSTALLS, або його вивели з обігу через ротацію ключа. Ідентифікатор змінюється, коли власник сервера змінює ключ; попросіть новий.

Усі входи до одного провайдера завершуються помилкою

Розділ із назвою «Усі входи до одного провайдера завершуються помилкою»

Одна з його змінних може бути відсутня, тож Connect виключив канал. Перевірте журнал запуску й таблиці вище. GitHub потрібні всі п’ять значень: id застосунку, slug, id клієнта, секрет клієнта та приватний ключ; Google потрібні і id клієнта, і секрет.

Входи завершуються помилкою невідповідності переспрямування

Розділ із назвою «Входи завершуються помилкою невідповідності переспрямування»

Переспрямування, зареєстроване в провайдера, не збігається точно з CONNECT_PUBLIC_URL. Порівняйте схему, хост, порт і шлях /connect для змонтованого Connect.

Ключ печатки змінився або втрачений, сервер змінив свій ключ, або дані сервера відновили на іншій машині. Запечатані облікові дані відкриваються лише для того встановлення й того Connect, які їх створили.