Referensi Control Center Connect
Control Center Connect menjalankan proses masuk penyedia untuk server yang belum mendaftarkan app
mereka sendiri. Sebuah server memakai Connect yang dihosting Control Center, atau Connect yang dijalankan
sebuah organisasi (Jalankan server Connect),
atau tidak keduanya. Pilihannya ada di Pengaturan → Server → Single sign-on → Control Center Connect,
perintah cc_server connect, atau CC_CONNECT_URL. Ruang kerja mengikutinya kecuali admin memilih hal lain
untuk ruang kerja itu di Pengaturan → Ruang kerja → Integrasi (Pilihan per ruang kerja).
Setiap penyedia adalah satu jalur. Di bawah Gunakan aplikasi saya sendiri (atau sebelum ada yang memilih), jalur berjalan di app server sendiri ketika app itu sudah dikonfigurasi lengkap, jika tidak jalur itu tidak tersedia. Dengan Connect milik Control Center atau Connect kustom, Connect menjalankan setiap jalur yang dilayaninya: app server tetap tersimpan tetapi tidak dipakai untuk login, otomatisasi server, atau status yang dilaporkan server. Ruang kerja yang memilih pilihannya sendiri menjalankan setiap jalur sesuai pilihan itu sebagai gantinya.
| Jalur | App milik sendiri memerlukan | Melalui Connect |
|---|---|---|
github |
Id app, kunci privat, id klien, dan rahasia klien | Orang masuk ke GitHub App bersama |
google |
Id klien dan rahasia klien | Orang menghubungkan Google Calendar |
linear |
Id klien | Orang masuk ke Linear |
linear_app |
Id klien | Admin ruang kerja menghubungkan aktor app Linear |
slack |
Koneksi app Slack milik ruang kerja | Admin ruang kerja menghubungkan Slack ke app Slack bersama |
klipy |
KLIPY_APP_KEY |
Pencarian GIF, diproksikan oleh Connect |
App milik sendiri yang hanya dikonfigurasi sebagian menjadikan jalurnya galat, tidak pernah diam-diam jatuh kembali ke Connect. Ruang kerja yang memakai Gunakan aplikasi saya sendiri tidak pernah melalui app server maupun Connect mana pun, untuk penyedia mana pun. Mengubah pilihan Connect server tidak mengeluarkan siapa pun dari ruang kerja yang membuat pilihannya sendiri.
Apa yang dilihat Connect dan apa yang tidak pernah dilihatnya
Bagian berjudul “Apa yang dilihat Connect dan apa yang tidak pernah dilihatnya”| Connect melihat | Connect tidak pernah melihat |
|---|---|
| Id instalasi server dan tanda tangan permintaan | Kode sumber, isi repositori, diff, atau teks pull request |
| Akun penyedia yang masuk, selama proses masuk | Tiket, transkrip, atau apa pun di basis data ruang kerja |
| Ruang kerja mana yang dimiliki sebuah kredensial, sebagai id buram di dalam segel | Rahasia app server sendiri: rahasia itu tidak pernah meninggalkan server |
| Repositori yang diberi token GitHub satu-repositori | Refresh token dalam keadaan tersimpan: hanya ada di dalam segel yang disimpan server |
| Tim Slack yang terikat ke server | Rahasia Linear: server menukar kode Linear sendiri |
| Istilah pencarian GIF, saat Connect memproksikan Klipy | Kata sandi, kunci pairing, atau kunci penyedia model |
| Referensi peristiwa Slack (team, kanal, id pesan) dan teks perintah slash | Teks pesan Slack: Connect membuangnya saat diterima, dan server membaca pesan dari Slack sendiri |
Connect menyimpan proses masuk yang tertunda, nonce, dan cache paling lama 10 menit, dan penghitung pemakaian per jam paling lama dua jam. Token GitHub satu-repositori yang dicetak sebagai seseorang tetap tercatat, tersegel untuk proses masuk yang memintanya, sampai kedaluwarsa (paling lama 8 jam), sehingga Connect dapat mengeluarkannya lagi dan mencabutnya saat diputuskan. Satu-satunya catatan jangka panjangnya adalah pengikatan Slack (server mana yang terikat ke setiap tim Slack) dan id instalasi yang sudah dipensiunkan. Galat membawa kode, tidak pernah respons penyedia. Log hanya mencatat id instalasi sebagai hash berkunci, dan token GitHub hanya sebagai hashed_token yang ditampilkan log audit organisasi GitHub untuknya, sehingga pemilik organisasi dapat mencocokkan keduanya.
| Mode | Pengaturan | Perilaku |
|---|---|---|
| Tidak diatur | Server baru | Tidak ada jalur yang memakai Connect. Onboarding meminta pemilik server untuk memilih |
hosted |
Gunakan aplikasi Control Center | https://connect.usectrl.dev, dengan konfigurasi yang ditandatangani secara offline. App server tidak dipakai |
custom |
Gunakan server Connect kustom | Connect di URL HTTPS (http hanya di loopback), dipercaya saat pertama kali digunakan. App server tidak dipakai |
off |
Gunakan aplikasi saya sendiri | Tidak ada jalur yang memakai Connect. Hanya app milik sendiri yang dapat memasukkan orang |
CC_CONNECT_URL di lingkungan atau .env server mengunci pilihan: hosted, off, atau URL Connect.
Pengaturan kemudian menampilkan kuncinya dan tidak dapat mengubahnya.
Build ini tidak menyertakan kunci konfigurasi hosted, sehingga mode hosted melaporkan hosted_unprovisioned
dan tidak melayani jalur apa pun. App milik sendiri dan Connect kustom tetap berfungsi.
Connect yang dihosting berjalan dalam satu kontainer. Kunci segel dan kunci privat GitHub App bersama berupa variabel lingkungan di sana, bukan kunci di vault yang hanya menandatangani atau mendekripsi, seperti yang direkomendasikan GitHub untuk kunci privat App. Itu adalah celah yang diketahui pada penyiapan saat ini.
Sebuah server membaca konfigurasi Connect paling sering setiap 10 menit dan menunggu paling lama 5 detik untuk setiap panggilan. Saat Connect tidak terjangkau, konfigurasi baik terakhir tetap dipakai dan Pengaturan menandainya sebagai usang.
Pilihan per ruang kerja
Bagian berjudul “Pilihan per ruang kerja”Pengaturan → Ruang kerja → Integrasi → Control Center Connect menggantikan pilihan server untuk satu ruang kerja. Setiap anggota melihatnya dan melihat tempat setiap proses masuk berjalan; hanya admin ruang kerja yang dapat mengubahnya.
| Pilihan | Perilaku |
|---|---|
| Sama seperti server ini | Bawaan. Ruang kerja berjalan di apa pun yang dipilih pemilik server; opsi itu menyebutkannya |
| Gunakan aplikasi Control Center | Connect hosted milik Control Center, apa pun yang digunakan server |
| Gunakan aplikasi saya sendiri | Hanya app milik ruang kerja: GitHub App-nya, klien Google, aplikasi Linear, kunci Klipy, dan app Slack. Penyedia tanpa app di sini nonaktif; app yang hanya sebagian dikonfigurasi adalah galat penyiapan |
| Gunakan server Connect kustom | Connect di alamat HTTPS yang diberikan ruang kerja. Alamat di jaringan privat atau lokal ditolak |
- Pilihan apa pun selain Sama seperti server ini menyimpan proses masuk GitHub dan Linear setiap anggota di slot milik ruang kerja, sehingga tidak pernah bercampur dengan slot milik server
- Beralih meminta konfirmasi dulu: setiap orang di ruang kerja harus masuk lagi ke GitHub, Linear, dan Google Calendar lewat aplikasi baru
- Koneksi app Slack milik ruang kerja berfungsi di setiap pilihan; Tambahkan Control Center ke Slack mengikuti pilihan
CC_CONNECT_URLjuga mengunci ruang kerja agar tidak memiliki Connect sendiri: mereka hanya bisa mengikuti server atau memakai app mereka sendiri- Connect kustom sebuah ruang kerja dipercaya saat pertama kali digunakan untuk ruang kerja itu saja: Percayai aplikasi baru di sana tidak pernah mengubah apa yang dipercaya server atau ruang kerja lain
Identitas instalasi
Bagian berjudul “Identitas instalasi”| Item | Apa itu |
|---|---|
| Kunci instalasi | Seed 32 byte di berkas secret server (connect_install_key), terpisah dari kunci pairing perangkat |
| Kunci per-Connect | Kunci Ed25519 yang diturunkan dari seed dan alamat Connect. Setiap permintaan ke Connect ditandatangani dengannya (RFC 9421) |
| Id instalasi | 26 karakter yang diturunkan dari kunci publik itu. Ditampilkan di Pengaturan dan oleh cc_server connect status |
Server yang sama memiliki id instalasi yang berbeda untuk setiap alamat Connect. Id itu hanya berubah ketika kuncinya dirotasi.
Segel kredensial
Bagian berjudul “Segel kredensial”Proses masuk melalui Connect mengembalikan segel kredensial: sebuah blob terenkripsi yang hanya dapat dibuka oleh Connect yang membuatnya. Segel itu terikat pada penyedia, alamat Connect, id instalasi, ruang kerja, akun penyedia, app, dan generasi secret.
- Server menyimpan segel dan id instalasi tempat segel itu dibuat. Access token tetap di memori
- Untuk menyegarkan, server mengirim segel kembali dan menerima access token baru serta segel baru
- Segel yang id instalasi atau alamat Connect-nya tidak lagi cocok akan dihapus saat berikutnya dibaca, dan pemiliknya masuk ulang. Ini terjadi setelah rotasi kunci, saat pindah ke Connect lain, atau ketika direktori data dipulihkan ke server yang berbeda
- Segel yang tidak dapat dibuka Connect ditolak dengan
access_denied
Instalasi GitHub
Bagian berjudul “Instalasi GitHub”Instalasi GitHub App bersama dapat digunakan dari setiap server. Connect tidak menyimpan catatan tentang server mana yang boleh menggunakannya.
- Pasang aplikasi GitHub di Pengaturan → Ruang kerja → Integrasi membuka halaman pemasangan aplikasi di GitHub. Server membangun tautan dari nama aplikasi dalam konfigurasi Connect
- Token satu-repositori memerlukan app terpasang pada pemilik repositori dan akses orang yang masuk ke repositori tersebut. Itu adalah token pribadi orang tersebut, dibatasi sesuai perannya, tidak pernah lebih
- Sebuah organisasi membatasi Control Center di GitHub: dengan menghapus instalasi, mempersempit repositorinya, atau mengeluarkan orangnya
- Untuk panggilan yang hanya dapat dilakukan orang itu sendiri, seperti mendaftar instalasi mereka, Connect memberikan kepada server token pengguna App milik orang tersebut, bukan token satu-repositori. Masuk di sebuah server berarti mempercayai server itu dengan token tersebut
- Organisasi yang menerapkan daftar izin IP GitHub tidak dapat memakai Connect yang dihosting, yang alamatnya tidak tetap. Organisasi itu mendaftarkan GitHub App sendiri, di servernya sendiri atau di Connect yang dijalankannya
- Putuskan hanya mencabut proses masuk itu: Connect menggunakan refresh token-nya sekali dan menghapus apa yang dikembalikannya, menghapus token pengguna serta token satu-repositori yang dicetak Connect untuknya. Salinan segelnya yang disimpan di mana pun berhenti berfungsi. Proses masuk orang tersebut di server dan ruang kerja lain tetap berfungsi. Untuk menghapus Control Center dari akun GitHub sepenuhnya, cabut di GitHub pada Pengaturan → Aplikasi → Aplikasi GitHub yang diotorisasi → Cabut
Bot bersama
Bagian berjudul “Bot bersama”Token yang dicetak sebagai bot App (as: app) menampilkan bot yang sama di GitHub untuk setiap server yang memakai Connect yang sama: GitHub tidak dapat membedakan server-server itu.
- Setiap server boleh membuat bot membaca dan berkomentar:
read,review, dancomment(komentar, label, penerima tugas, dan reaksi pada issue dan pull request) - Meninjau pull request sebagai bot (
bot, yang menulis pull request) hanya diizinkan untuk server yang dicantumkan operator Connect diCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Setiap server lain dijawabneeds_requesterdan memublikasikan tinjauan melalui token pribadi orang yang bertanggung jawab, yang dibatasi GitHub hanya untuk orang itu: tinjauan tampil di bawah nama mereka. Ini mencakup penerbitan tinjauan AI, komentar tinjauan, dan permintaan peninjau - Push, membuat cabang, dan membuka pull request (
write) tidak pernah dicetak sebagai bot bersama. Selalu memakai proses masuk pemintanya sendiri - Menyetujui pull request tidak pernah otomatis, dengan token apa pun
- Server atau ruang kerja dengan GitHub App sendiri tetap memakai bot untuk semua ini, termasuk tinjauan
Yang perlu diketahui pemilik dan anggota organisasi
Bagian berjudul “Yang perlu diketahui pemilik dan anggota organisasi”- Server tempat seseorang masuk menyimpan token pengguna App mereka: hingga 8 jam per token, diperbarui sampai mereka memutuskan. Token itu dapat bertindak atas nama mereka di setiap repositori tempat App bersama terpasang yang dapat mereka jangkau. Connect dapat memutus server dari akses untuk selamanya (instalasi yang dipensiunkan atau ditolak), tetapi token yang sudah diberikan tetap berlaku sampai kedaluwarsa
- Memasang GitHub App bersama di sebuah organisasi memberi persetujuan untuk setiap server Control Center tempat anggota mana pun masuk, bukan untuk satu server
- Bot bersama, seperti di atas: organisasi tidak dapat mengetahui di GitHub server mana yang bertindak sebagai bot
- Organisasi yang ingin memiliki batasnya sendiri mendaftarkan GitHub App sendiri dan menjalankan Connect sendiri (Jalankan server Connect), atau mengonfigurasi App di servernya sendiri
Kepercayaan konfigurasi
Bagian berjudul “Kepercayaan konfigurasi”| Connect | Cara server mempercayai konfigurasinya |
|---|---|
| Hosted | Memverifikasi tanda tangan Ed25519 terhadap kunci yang dikompilasi ke dalam build. Menolak epoch yang lebih rendah dari epoch tertinggi yang pernah dilihatnya (rollback) |
| Custom | Mengunci id GitHub app dan id klien, id klien Google dan Linear, serta id app dan klien Slack saat pertama kali digunakan. Perubahan menjeda proses masuk Connect (pins_changed) sampai pemilik server menekan Percayai aplikasi baru |
Operasi
Bagian berjudul “Operasi”Pengaturan Connect milik server hanya untuk pemilik server.
| Operasi | Fungsi |
|---|---|
connect.status |
Mode, URL, kunci, id instalasi, kesehatan, epoch konfigurasi, dan sumber setiap jalur |
connect.configure |
Menetapkan hosted, custom (dengan url), atau off |
connect.test |
Mengambil ulang konfigurasi dan melaporkan kesehatan |
connect.confirmPins |
Menerima id yang berubah dari Connect kustom |
connect.rotateKey |
Membuat kunci instalasi dan id instalasi baru (force menggantinya meskipun Connect tidak dapat mempensiunkan yang lama); lihat Rotasi kunci instalasi |
Pilihan milik ruang kerja memiliki operasinya sendiri, masing-masing menyebut ruang kerjanya:
| Operasi | Siapa | Fungsi |
|---|---|---|
workspaceConnect.status |
Anggota mana pun | Pilihan, hasilnya, kesehatan, dan sumber setiap penyedia. Id instalasi dan pin tertunda hanya untuk admin |
workspaceConnect.set |
Admin ruang kerja | Menetapkan inherit, hosted, custom (dengan url), atau own |
workspaceConnect.test |
Admin ruang kerja | Mengambil ulang konfigurasi Connect ruang kerja dan melaporkan kesehatan |
workspaceConnect.confirmPins |
Admin ruang kerja | Menerima id yang berubah dari Connect kustom ruang kerja |
Proses masuk sendiri memakai oauth.lanes, oauth.begin, oauth.status, oauth.complete,
oauth.connections, dan oauth.disconnect. Orang tersebut selalu adalah pemanggil yang sudah masuk.
Proses masuk melalui Connect
Bagian berjudul “Proses masuk melalui Connect”- Server meminta Connect memulai jalur dan menerima URL otorisasi penyedia, yang diperiksanya sebelum ditampilkan. GitHub selalu menampilkan pemilih akunnya
- Orang tersebut menyetujui di peramban. Penyedia mengembalikan peramban ke Connect
- Connect menampilkan apa yang dapat dilakukan server yang memulai proses masuk sebagai orang tersebut, dan untuk berapa lama. Connect tidak dapat mengetahui siapa yang menjalankan server itu, sehingga halaman meminta orang tersebut melanjutkan hanya bila mereka sendiri yang memulai proses masuk, dan menutupnya bila seseorang mengirimkan tautan itu kepada mereka. Bila peramban berada di jaringan lain dibandingkan jaringan tempat proses masuk dimulai, halaman mengatakannya: itu wajar untuk server yang dihosting atau perangkat lain, dan itu juga yang terlihat seperti phishing. Batal mengakhiri proses masuk: kode penyedia tidak pernah dipakai. Setiap halaman menjawab sekali: jawaban yang tidak berasal dari halaman yang baru ditampilkan Connect ditolak
- Setelah Lanjutkan, Connect menampilkan kode 8 karakter dan tautan
control-center://oauth-done. Siapa pun yang mendapatkan kode itu mendapatkan akses yang baru disetujui, sehingga kode hanya boleh dikirim ke tempat proses masuk dimulai - Orang tersebut mengetik kode ke aplikasi, atau mengikuti tautan. Server mengklaim proses masuk dengan kode itu beserta bukti miliknya sendiri atas permintaan tersebut
Proses masuk kedaluwarsa setelah 10 menit. Lima kode salah akan mengakhirinya. Tautan yang tidak dimulai oleh
aplikasi ini akan ditolak dengan Proses masuk tidak dimulai di sini. Connect membatasi berapa banyak proses masuk yang dapat dimulai dari satu alamat jaringan, dan seberapa sering token GitHub diterbitkan per orang dan server, per orang lintas server, per alamat, dan untuk seluruh app. Proses masuk baru memiliki anggarannya sendiri, sehingga tidak pernah menahan pembaruan yang dibutuhkan orang lain. Melewati batas, sebuah panggilan ditolak dengan rate_limited, dan server mencoba lagi nanti tanpa mengeluarkan siapa pun. Proses masuk yang melewati batas orang tersebut dibatalkan di GitHub dan ditolak.
Rotasi kunci instalasi
Bagian berjudul “Rotasi kunci instalasi”Hanya pemilik server yang dapat memutar kunci, dengan Rotasi kunci pada kartu Control Center Connect di Pengaturan → Server → Single sign-on. Tidak ada perintah untuk itu. Rotasi:
- Mengeluarkan semua orang dari setiap jalur yang berjalan melalui Connect. Untuk setiap server Connect tempat kunci lama dipakai, server mencabut proses masuk GitHub dan Slack yang dipegangnya dari sana (proses masuk Google tidak memiliki apa pun untuk dicabut dan berakhir sendiri)
- Mempensiunkan id instalasi lama di setiap server Connect tersebut, ditandatangani dengan kunci lama dan dibuktikan dengan satu segel kredensial yang dipegang server dari Connect itu. Sejak saat itu Connect menolak setiap permintaan yang dibuat dengan kunci lama, sehingga segel atau salinan kunci lama yang diambil dari server ini tidak berguna, dan tim Slack yang terikat ke id lama dilepaskan agar dapat terhubung lagi. Token yang sudah diberikan tetap berlaku sampai kedaluwarsa (satu jam untuk token bot, delapan jam untuk token seseorang). Server Connect yang tidak memiliki segel dari server ini tidak memiliki apa pun untuk dipensiunkan dan dilewati
- Kemudian memberi server kunci instalasi baru dan id instalasi baru
- Jika sebuah server Connect tidak dapat dijangkau, atau menolak mempensiunkan id lama, berhenti sebelum mengganti kunci dan menampilkan Connect tidak dapat menonaktifkan kunci lama. Tetap ganti mengganti kunci apa pun yang terjadi; id instalasi lama kemudian tetap dapat dipakai di Connect itu sampai tokennya kedaluwarsa, paling lama 8 jam untuk GitHub
- Membiarkan proses masuk melalui app milik server sendiri tidak berubah
- Memerlukan id instalasi baru ditambahkan ke daftar izin Connect kustom
Kode status
Bagian berjudul “Kode status”| Kode | Arti |
|---|---|
hosted_unprovisioned |
Build ini tidak memiliki kunci konfigurasi hosted |
signature |
Konfigurasi hosted gagal dalam pemeriksaan tanda tangannya |
rollback |
Connect menyajikan konfigurasi yang lebih lama daripada yang sudah dilihat server |
unreachable |
Server tidak dapat menjangkau Connect |
install_blocked |
Connect tidak mengizinkan id instalasi ini, atau id tersebut sudah dipensiunkan |
pins_changed |
Connect kustom mengumumkan id app yang berbeda |
protocol |
Connect menjawab dalam bentuk yang tidak dipahami server ini |