Lewati ke konten

Jalankan server Connect

Control Center Connect menjalankan proses masuk penyedia (GitHub, Google Calendar, Linear, Slack) untuk server yang belum mendaftarkan app mereka sendiri. Panduan ini menunjukkan cara menjalankan Connect Anda sendiri, sehingga app penyedia, rahasianya, dan daftar server yang diizinkan memakainya tetap berada di tangan Anda.

Apa yang dilihat dan tidak dilihat Connect dijelaskan dalam referensi Connect. Bacalah itu terlebih dahulu jika Anda sedang mempertimbangkan untuk menjalankan satu.

  • Alamat HTTPS publik untuk Connect, misalnya https://connect.example.com, di belakang proxy yang mengakhiri TLS. HTTP biasa hanya diterima di loopback
  • Docker, atau cc_server yang dapat Anda mulai ulang dengan variabel lingkungan tambahan
  • Izin untuk mendaftarkan app pada setiap penyedia yang ingin Anda layani
  • Server yang akan memakainya, dengan pemiliknya di dekat Anda: setiap server memiliki id instalasi yang Anda tambahkan ke daftar izin Connect

Pilih URL sekarang dan simpan. CONNECT_PUBLIC_URL terlibat dalam setiap hal yang dilakukan Connect: tanda tangan permintaan, segel kredensial, URL pengalihan penyedia, dan id instalasi setiap server semuanya terikat padanya. Mengubahnya di kemudian hari berarti mendaftarkan ulang pengalihan dan setiap orang masuk ulang.

Daftarkan hanya penyedia yang ingin Anda layani. Penyedia yang variabelnya belum lengkap akan dikeluarkan dari konfigurasi Connect, dan server melihatnya sebagai tidak tersedia. <base> di bawah adalah CONNECT_PUBLIC_URL Anda.

Penyedia Daftarkan Simpan
Aplikasi GitHub Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup dengan Redirect on update aktif. Biarkan Request user authorization (OAuth) during installation nonaktif: jika aktif, GitHub mengabaikan setup URL. Biarkan Expire user authorization tokens aktif App id, slug, client id, client secret, kunci privat
Google Klien OAuth bertipe Web application dengan redirect URI <base>/oauth/google/callback, dan Google Calendar API diaktifkan Client id, client secret
Linear Aplikasi OAuth dengan callback URL <base>/oauth/linear/callback dan <base>/oauth/linear_app/callback Hanya client id
Slack Redirect URL <base>/oauth/slack_oidc/callback dan <base>/oauth/slack/callback. Event Subscriptions di <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash command di <base>/v1/hooks/slack/commands. Aktifkan token rotation App id, client id, client secret, signing secret

Berikan GitHub App izin repositori berikut: Metadata baca, Contents baca dan tulis, Pull requests baca dan tulis, Issues baca dan tulis, Checks, Actions, dan Commit statuses baca. Tambahkan izin organisasi Members baca untuk permintaan tinjauan tim. Webhook boleh dimatikan: server melakukan polling.

Connect memerlukan kunci privat GitHub App (Buat kunci privat di pengaturan App). Ia menandatangani permintaan App yang mencari instalasi yang mencakup sebuah repositori (atau, ketika repositori itu tidak punya, instalasi owner-nya) dan mencetak token instalasi satu-repositori, masing-masing hanya setelah proses masuk milik orang yang meminta membuktikan akses ke repositori tersebut.

Setiap server di Connect Anda berbagi bot App. Bot boleh membaca, berkomentar, memberi label, dan bereaksi sebagai bot untuk server mana pun. Meninjau pull request sebagai bot hanya diizinkan untuk server yang Anda daftarkan di CONNECT_GITHUB_REVIEW_BOT_INSTALLS (id instalasinya, dipisahkan koma); setiap server lain mempublikasikan tinjauan dengan token peninjau sendiri. Mendorong tidak pernah dilakukan sebagai bot. Untuk mengizinkan server milik Anda sendiri meninjau sebagai bot, tambahkan id instalasinya di sana lalu mulai ulang. Simpan berkas kunci sebagai rahasia, seperti kunci segel. Linear tidak memerlukan rahasia: Connect mengembalikan kode ke server, dan server menyelesaikan pertukarannya sendiri.

Connect hanya menjawab server dalam daftar izinnya. Pada setiap server, arahkan ke Connect Anda, lalu baca id instalasinya:

  1. Buka Pengaturan → Server → Single sign-on, buka kartu Control Center Connect dan pilih Gunakan server Connect kustom
  2. Masukkan URL Anda lalu simpan. Kartu menampilkan Id instalasi server

Dari terminal di host server, hal yang sama adalah:

Jendela terminal
cc_server connect enable --url https://connect.example.com
cc_server connect status

status mencetak id instalasi. Ia menampilkan install_blocked sampai Langkah 5 selesai, dan itu memang diharapkan.

Id instalasi diturunkan per alamat Connect, sehingga server yang sama memiliki id berbeda untuk setiap Connect yang diajaknya bicara. Id itu hanya berubah ketika pemiliknya memutar kunci.

Connect mengenkripsi setiap kredensial yang dikembalikannya dengan kunci segel. Buat satu dan simpan sebagai berkas rahasia:

Jendela terminal
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

Kehilangan kunci segel akan mengeluarkan semua orang: tidak ada segel yang dapat dibuka tanpanya.

Setiap rilis menerbitkan ghcr.io/samuelalev/cc-connect dengan build provenance. Dalam produksi, pin tag versi.

Jendela terminal
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

Arahkan reverse proxy Anda ke port 8790, dan atur CONNECT_TRUST_PROXY ke jumlah proxy di depan Connect agar batas laju per alamatnya melihat alamat setiap klien. Image berjalan sebagai pengguna tanpa hak istimewa, menyimpan state di volume /data, dan memiliki health check bawaan (cc-connect --healthcheck, yang memeriksa /healthz: prosesnya menjawab). /readyz juga memeriksa bahwa penyimpanan state dan binding-nya menjawab serta bahwa Redis, bila dipakai, masih menjalankan maxmemory-policy noeviction; arahkan readiness check orkestrator ke sana.

Halaman persetujuan masuk menjawab dengan form post yang hanya diterima Connect dari halamannya sendiri: Sec-Fetch-Site, bila dikirim, harus same-origin, dan Origin, bila dikirim, harus origin dari CONNECT_PUBLIC_URL; post tanpa keduanya ditolak. Jadi proxy harus meneruskan kedua header itu tanpa perubahan, dan CONNECT_PUBLIC_URL harus berupa alamat yang benar-benar digunakan browser orang. Jika melanjutkan dari halaman itu selalu menampilkan “Tautan ini sudah kedaluwarsa”, dan log menampilkan oauth.done_refused dengan alasan origin atau no_origin, salah satu dari dua hal itu tidak benar.

Connect menolak mulai (kode keluar 78) ketika konfigurasinya terbuka, tidak aman, atau setengah jadi, dan mencetak variabel mana yang salah. Daftar izin yang hilang, alamat http yang bukan loopback, kunci segel yang salah format, atau NAME dan NAME_FILE yang keduanya diatur akan menghentikannya.

Titik pemeriksaan: pada setiap server, kartu Connect menampilkan Berfungsi, dan Tempat setiap proses masuk berjalan menyebut Connect untuk setiap penyedia yang Anda daftarkan. cc_server connect status mencetak Health: ok beserta jalur yang sama.

Sebuah server dapat menjalankan Connect sendiri alih-alih kontainer terpisah. Layanan yang dipasang adalah layanan yang sama dengan yang dijalankan image.

  1. Letakkan variabel CONNECT_* di berkas .env server, seperti di Langkah 5. Server menolak mulai ketika sebuah rahasia Connect, termasuk CONNECT_SENTRY_DSN, diekspor di lingkungannya
  2. Tambahkan CC_SERVER_CONNECT_HOST=on
  3. Mulai ulang server. Log-nya mencetak embedded Connect at <url>
Jendela terminal
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 kemudian dilayani di <server>/connect:

  • CONNECT_PUBLIC_URL secara bawaan adalah origin URL publik server ditambah /connect. Atur secara eksplisit di balik proxy. Path-nya harus persis /connect, dan harus HTTPS kecuali loopback
  • Hanya variabel CONNECT_* yang sampai ke layanan yang dipasang, sehingga ia tidak pernah meminjam app penyedia milik server itu sendiri
  • CONNECT_ALLOWED_INSTALLS tetap wajib, termasuk untuk server penampung itu sendiri
  • Pemasangan yang salah konfigurasi menghentikan server agar tidak mulai, alih-alih melayani broker yang terbuka
  • Server demo tidak pernah memasangnya

Daftarkan pengalihan penyedia terhadap https://<server>/connect, lalu arahkan server (termasuk server penampung) ke URL itu seperti di Langkah 3.

Setiap pengaturan adalah variabel lingkungan. Rahasia apa pun dapat diambil dari berkas yang dipasang: atur NAME_FILE sebagai pengganti NAME. Connect membaca ulang berkas paling sering setiap 30 detik dan menyimpan nilai baik terakhir. Rahasia yang ditandai dual juga menerima NAME_PREVIOUS (atau NAME_PREVIOUS_FILE) selama rotasi.

Variabel Bawaan Arti
CONNECT_PUBLIC_URL wajib URL publik kanonis. HTTPS, atau http hanya di loopback. Path berarti dipasang. Tanpa query atau fragment
CONNECT_ALLOWED_INSTALLS wajib Id instalasi dipisahkan koma. * hanya diterima bersama CONNECT_SIGNED_CONFIG_FILE
CONNECT_DENY_INSTALLS Id instalasi yang ditolak meski diizinkan
CONNECT_GITHUB_ALLOWED_OWNERS Id pemilik GitHub numerik. Jika diatur, token repositori hanya dicetak untuk repositori yang mereka miliki. Ini tidak membatasi siapa yang dapat masuk: orang yang diizinkan memakai Connect ini tetap menerima token pengguna App miliknya sendiri. Untuk melayani satu organisasi saja, jadikan App privat bagi organisasi itu
CONNECT_GITHUB_REVIEW_BOT_INSTALLS Id instalasi yang boleh membuat bot App meninjau pull request. Kosong secara bawaan; * ditolak, dan setiap id juga harus diizinkan
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Alamat bind dan port
CONNECT_TRUST_PROXY 0 Lompatan proxy tepercaya dalam X-Forwarded-For (0 sampai 8). Hanya dipakai untuk batas per alamat, petunjuk jaringan pada halaman masuk, dan alamat yang dicatat. Di belakang proxy, 0 menghitung setiap klien sebagai proxy, dan log menyatakannya sekali
Variabel Bawaan Arti
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID GitHub App
CONNECT_GITHUB_CLIENT_SECRET Rahasia, dual
CONNECT_GITHUB_APP_PRIVATE_KEY Rahasia. Kunci privat App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Klien Google. Rahasianya dual
CONNECT_LINEAR_CLIENT_ID Aplikasi Linear. Tanpa rahasia
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID App Slack
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Rahasia, dual
CONNECT_KLIPY_APP_KEY Kunci pencarian GIF Klipy. Rahasia, dual
CONNECT_KLIPY_MODE proxy proxy menyimpan kunci di Connect; key menyerahkannya ke server
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google, dan Slack: generasi yang dicatat dalam segel baru
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google, dan Slack: segel yang lebih lama harus masuk ulang
CONNECT_<LANE>_ACCEPTS_NEW true Setiap jalur: false menghentikan proses masuk baru sementara yang ada tetap diperbarui
Variabel Bawaan Arti
CONNECT_SEAL_BACKEND local local atau gcp-kms
CONNECT_SEAL_KEYS Rahasia, wajib untuk local. Entri kid:key dipisahkan koma, yang terbaru di depan; entri lama tetap dapat mendekripsi
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, wajib untuk gcp-kms
CONNECT_STATE memory memory untuk satu instance, redis untuk beberapa. Penyimpanan memori yang penuh menolak proses masuk dan permintaan baru alih-alih melupakan entri yang masih aktif
CONNECT_REDIS_URL Rahasia. redis:// atau rediss://. Redis 6.2 atau lebih baru dengan maxmemory-policy noeviction, keduanya diperiksa saat mulai
CONNECT_REDIS_CA_FILE Bundel CA untuk rediss://
CONNECT_BINDINGS file Tempat pengikatan tim Slack disimpan: file atau firestore
CONNECT_DATA_DIR data (/data di image) Menyimpan bindings.json. Dikunci oleh satu Connect: Connect kedua pada direktori yang sama tidak mau mulai
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE database (default) Untuk CONNECT_BINDINGS=firestore. Connect tidak mau mulai ketika Firestore tidak menjawab
Variabel Bawaan Arti
CONNECT_SIGNED_CONFIG_FILE Konfigurasi yang ditandatangani secara offline, disajikan apa adanya. Dipakai oleh Connect hosted Control Center
CONNECT_CONFIG_PUBLIC_KEYS Kunci yang harus diverifikasi oleh konfigurasi yang ditandatangani
CONNECT_CONFIG_EPOCH 1 Epoch konfigurasi yang dibuat oleh Connect yang di-self-host
CONNECT_LOG_HMAC_KEY acak per proses Rahasia. Atur agar tag yang menggantikan id instalasi di log tetap stabil lintas restart dan instance
CONNECT_SENTRY_DSN Rahasia. DSN Sentry https tempat baris galat dilaporkan: jenis galat, bingkai stack, rute, dan id permintaan, tidak pernah pesan, body, atau header
CONNECT_SENTRY_ENVIRONMENT self-hosted Lingkungan Sentry
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Dilaporkan oleh /v1/version
CONNECT_RATE_INSTALL_PER_MINUTE 600 Permintaan per instalasi
CONNECT_RATE_IP_PER_MINUTE 300 Permintaan per alamat (alamat IPv6 dihitung per /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Permintaan untuk seluruh instance
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Pengiriman event dan perintah Slack per alamat, dihitung terpisah dari permintaan lain
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Pengiriman event dan perintah Slack untuk seluruh instance
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Peristiwa Slack per tim
CONNECT_RATE_KLIPY_PER_MINUTE 120 Pencarian GIF per instalasi
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 Pencarian GIF per alamat, di seluruh server
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Proses masuk yang dimulai per alamat
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 Token GitHub yang diterbitkan per akun GitHub di satu server (proses masuk, penyegaran, token repositori)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × di atas (120) Sama, per akun GitHub di seluruh server
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 Token GitHub yang diterbitkan per alamat
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Proses masuk GitHub baru untuk seluruh app
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Token bot per server
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Token bot per akun GitHub yang meminta, di seluruh server
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Token bot untuk seluruh app
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Penyegaran dan token repositori untuk seluruh app. Proses masuk baru memiliki batasnya sendiri di atas
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Token repositori aktif yang boleh dimiliki satu akun GitHub sebelum Connect mencatat peringatan
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Id instalasi yang dipensiunkan per alamat (per /48 untuk IPv6)

Panggilan yang melewati batas dijawab rate_limited. Server mencoba lagi nanti dan tidak pernah mengeluarkan siapa pun karenanya.

Satu instance dengan CONNECT_STATE=memory sudah cukup untuk sebagian besar organisasi. Beberapa instance di belakang satu alamat memerlukan CONNECT_STATE=redis dan CONNECT_BINDINGS=firestore, sehingga proses masuk yang dimulai di satu instance dapat diselesaikan di instance lain dan setiap instance melihat binding Slack dan id instalasi yang dipensiunkan yang sama. CONNECT_DATA_DIR bersama tidak berfungsi: Connect pertama mengunci direktori itu. Batas permintaan per instalasi, per alamat, dan per instance bersifat per instance; batas proses masuk, token GitHub, token bot, pencarian GIF per alamat, pensiun, dan tim Slack dibagikan melalui penyimpanan state.

Tidak ada yang dikeluarkan:

  1. Buat rahasia baru di penyedia dan simpan yang lama
  2. Pindahkan nilai lama ke NAME_PREVIOUS, letakkan yang baru di NAME, dan naikkan CONNECT_<LANE>_SECRET_GENERATION. Berkas yang dipasang diambil dalam 30 detik
  3. Tunggu proses masuk menyegarkan diri, lalu hapus rahasia lama di penyedia dan hapus NAME_PREVIOUS

Untuk merotasi kunci segel, letakkan entri cc-connect-config seal-key baru di awal CONNECT_SEAL_KEYS dan pertahankan entri lama sampai segelnya telah disegarkan.

Server mengingat id app dan id klien yang diumumkan Connect Anda saat pertama kali memakainya. Jika Anda mengganti sebuah app, kartu Connect setiap server akan menampilkan Aplikasi Connect berubah, dan proses masuk melalui Connect dijeda sampai pemiliknya menekan Percayai aplikasi baru. Beri tahu pemilik server sebelum Anda beralih, agar mereka tahu bahwa perintah itu berasal dari Anda.

Tambahkan id instalasinya ke CONNECT_DENY_INSTALLS lalu mulai ulang. Pemiliknya akan melihat “Connect memblokir ID pemasangan server ini. Hubungi operator server Connect Anda.” dan setiap proses masuk melalui Connect di sana akan berhenti.

Server juga memensiunkan id instalasi lamanya sendiri ketika pemiliknya memutar kunci. Ia membuktikan id itu miliknya dengan satu segel kredensial yang dibuat Connect ini untuknya, sehingga hanya server yang pernah memasukkan seseorang yang dapat memensiunkan id. Connect menyimpan id yang dipensiunkan selamanya, sehingga kunci lama dan setiap segel yang dibuat untuknya berhenti bekerja, dan melepaskan ruang kerja Slack yang terikat pada id lama. Token yang sudah dibagikan kedaluwarsa dengan sendirinya: dalam 8 jam untuk token seseorang, 1 jam untuk token bot. Connect menyimpan paling banyak 100.000 id yang dipensiunkan; melewati itu, rotasi ditolak dan log menyatakannya pada tingkat error.

Sebuah server menyatakan Connect telah memblokirnya

Bagian berjudul “Sebuah server menyatakan Connect telah memblokirnya”

Id instalasinya tidak ada di CONNECT_ALLOWED_INSTALLS, ada di CONNECT_DENY_INSTALLS, atau telah dipensiunkan oleh rotasi kunci. Id berubah ketika pemilik server memutar kunci; minta id yang baru.

Salah satu variabelnya mungkin hilang, sehingga Connect mengeluarkan jalur tersebut. Periksa log startup dan tabel di atas. GitHub memerlukan kelimanya: app id, slug, client id, client secret, dan kunci privat; Google memerlukan client id dan client secret.

Proses masuk gagal dengan ketidakcocokan redirect

Bagian berjudul “Proses masuk gagal dengan ketidakcocokan redirect”

Redirect yang didaftarkan di penyedia tidak sama persis dengan CONNECT_PUBLIC_URL. Bandingkan skema, host, port, dan path /connect untuk Connect yang dipasang.

Kunci segel berubah atau hilang, sebuah server memutar kuncinya, atau data server dipulihkan ke mesin lain. Sebuah kredensial tersegel hanya dapat dibuka untuk instalasi dan Connect yang membuatnya.