Control Center Connect 參考
Control Center Connect 會為尚未登記自家應用程式的伺服器執行供應商登入。伺服器可以使用 Control Center 代管的 Connect、其組織自行運行的 Connect(執行 Connect 伺服器),或者都不使用。這個選擇位於 設定 → 伺服器 → 單一登入 → Control Center Connect、cc_server connect,或 CC_CONNECT_URL。工作區預設跟隨此選擇,除非管理員在 設定 → 工作區 → 整合 中為該工作區選擇了其他選項(每個工作區的選擇)。
在使用我自己的應用程式(或尚未有人選擇前),通道使用伺服器自己的應用程式(若已完整設定),否則無法使用。使用 Control Center Connect 或自訂 Connect 時,Connect 會服務其提供的每個通道:伺服器自己的應用程式保留但不使用,無論是登入、伺服器自動化或伺服器回報的狀態。已選定自身選擇的工作區則按該選擇執行每個通道。
| 通道 | 自家應用程式需要 | 透過 Connect |
|---|---|---|
github |
App 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 永遠看不到 |
|---|---|
| 伺服器的安裝 ID 與請求簽章 | 原始碼、程式庫內容、差異或 pull request 文字 |
| 登入期間,完成登入的那個供應商帳戶 | 工單、逐字稿或工作區資料庫中的任何內容 |
| 某份憑證屬於哪個工作區,以封存內的不透明 ID 形式呈現 | 伺服器自己的應用程式密鑰:它們絕不會離開伺服器 |
| 只適用於單一程式庫的 GitHub 權杖是為哪個程式庫簽發的 | 靜態儲存的重新整理權杖:它們只存在於伺服器保存的封存之內 |
| 綁定到該伺服器的 Slack 團隊 | Linear 密鑰:伺服器會自行交換 Linear 的代碼 |
| 代理 Klipy 時的 GIF 搜尋字詞 | 密碼、配對金鑰或模型供應商金鑰 |
| Slack 事件參照(團隊、頻道、訊息 id)與斜線指令文字 | Slack 訊息文字:Connect 在收到時就會丟棄,伺服器會自行從 Slack 讀取訊息 |
Connect 會把暫存中的登入、nonce 與快取保留最多 10 分鐘,並把每小時的用量計數器保留最多兩小時。以某人身分簽發的單一程式庫 GitHub 權杖會保持記錄,封存於請求它的那次登入之內,直到到期(最多 8 小時),因此 Connect 可以再次發出它,並在中斷連接時將其撤銷。它唯一長期保存的紀錄是 Slack 綁定(每個 Slack 團隊綁定到哪部伺服器)與已退役的安裝 ID。錯誤只帶有代碼,絕不包含供應商的回應。日誌只以帶金鑰的雜湊記錄安裝 ID,GitHub 權杖則只以 GitHub 組織稽核日誌為它顯示的 hashed_token 記錄,因此組織擁有者可以把兩者對應起來。
| 模式 | 設定 | 行為 |
|---|---|---|
| 未設定 | 全新的伺服器 | 沒有任何通道使用 Connect。入門引導會請伺服器擁有者選擇 |
hosted |
使用 Control Center 的應用程式 | https://connect.usectrl.dev,搭配一份離線簽署的設定。伺服器自己的應用程式不會被使用 |
custom |
使用自訂 Connect 伺服器 | 位於 HTTPS 網址(僅回送地址可用 http)的 Connect,首次使用時即予以信任。伺服器自己的應用程式不會被使用 |
off |
使用我自己的應用程式 | 沒有任何通道使用 Connect。只有自家應用程式能讓人們登入 |
伺服器環境或 .env 中的 CC_CONNECT_URL 會鎖定這個選擇:hosted、off 或一個 Connect 網址。之後設定會顯示這個鎖定,且無法更改它。
這個建置版本沒有內建任何代管設定金鑰,因此代管模式會回報 hosted_unprovisioned,且不提供任何通道。自家應用程式與自訂 Connect 都能運作。
代管的 Connect 在單一容器中執行。其封存金鑰與共用 GitHub App 的私鑰是那裡的環境變數,而不是只用於簽署或解密、如 GitHub 對 App 私鑰所建議的那種保險庫中的密鑰。這是目前設定的一個已知缺口。
伺服器最多每 10 分鐘讀取一次 Connect 的設定,每次呼叫最多等待 5 秒。當 Connect 無法連線時,會繼續使用最後一份有效的設定,並由設定將其標示為過時。
每個工作區的選擇
標題為「每個工作區的選擇」的章節設定 → 工作區 → 整合 → Control Center Connect 會為某個工作區覆寫伺服器的選擇。每位成員都能看到它以及每次登入在哪裡執行;只有工作區管理員可以更改。
| 選項 | 行為 |
|---|---|
| 與此伺服器相同 | 預設值。工作區執行伺服器擁有者選定的任何設定;選項會寫明該設定 |
| 使用 Control Center 的應用程式 | Control Center 代管的 Connect,無論伺服器使用什麼 |
| 使用我自己的應用程式 | 只使用工作區自己的應用程式:其 GitHub App、Google 用戶端、Linear 應用程式、Klipy 金鑰與 Slack 應用程式。沒有對應應用程式的供應商在此處關閉;只設定了一部分則是設定錯誤 |
| 使用自訂 Connect 伺服器 | 工作區指定的 HTTPS 位址上的 Connect。私人網絡或本機網絡上的位址會被拒絕 |
- 除與此伺服器相同外的任何選項,都會把每個人的 GitHub 與 Linear 登入保存在工作區自己的一個槽位中,因此它們絕不會與伺服器範圍的登入混在一起
- 切換時會先詢問:工作區中的每個人都需要透過新的應用程式重新登入 GitHub、Linear 和 Google Calendar
- 工作區自己的 Slack 應用程式連線在所有選項下都可用;將 Control Center 加入 Slack 跟隨所選選項
CC_CONNECT_URL也會阻止工作區擁有自己的 Connect:它們只能跟隨伺服器,或使用自己的應用程式- 工作區自己的自訂 Connect 只在該工作區內首次使用時受信任:那裡的信任新應用程式絕不會改變伺服器或其他工作區所信任的內容
安裝身分
標題為「安裝身分」的章節| 項目 | 說明 |
|---|---|
| 安裝金鑰 | 伺服器機密檔案中的一個 32 位元組種子(connect_install_key),與裝置配對金鑰分開 |
| 每個 Connect 的金鑰 | 由種子與該 Connect 的地址衍生出的 Ed25519 金鑰。每個送往 Connect 的請求都以它簽署(RFC 9421) |
| 安裝 ID | 由該公開金鑰衍生出的 26 個字元。顯示在設定中,以及 cc_server connect status 的輸出裡 |
同一部伺服器面對每個 Connect 地址都有不同的安裝 ID。只有在金鑰被輪替時,這個 ID 才會改變。
封存的憑證
標題為「封存的憑證」的章節透過 Connect 的登入會回傳一份憑證封存:一個只有建立它的 Connect 能開啟的加密資料塊。它綁定到供應商、Connect 地址、安裝 ID、工作區、供應商帳戶、應用程式與金鑰世代。
- 伺服器儲存這份封存以及它所對應的安裝 ID。存取權杖只留在記憶體中
- 要重新整理時,伺服器會把封存送回,並取得新的存取權杖與新的封存
- 安裝 ID 或 Connect 地址不再相符的封存,會在下次讀取時被刪除,而那個人需要重新登入。這會發生在金鑰輪替、切換到另一個 Connect,或資料目錄被還原到另一部伺服器之後
- Connect 無法開啟的封存會以
access_denied拒絕
GitHub 安裝
標題為「GitHub 安裝」的章節共用 GitHub App 的安裝可以從每部伺服器使用。Connect 不記錄哪部伺服器可以使用它。
- 設定 → 工作區 → 整合 中的安裝 GitHub 應用程式會開啟該應用程式在 GitHub 上的安裝頁面。伺服器會根據 Connect 設定中的應用程式名稱建立連結
- 單一程式庫的權杖需要應用程式已安裝在程式庫擁有者的帳戶上,並且登入的人可以存取該程式庫。這是該人自己的權杖,受其角色限制,絕不會更多
- 組織可以在 GitHub 上限制 Control Center:移除安裝、縮窄程式庫範圍,或移除該人
- 對只有該人能發出的呼叫,例如列出其安裝,Connect 會把該人自己的 App 用戶權杖交給伺服器,而非單一程式庫的權杖。在某伺服器上登入,即是信任該伺服器持有該權杖
- 強制執行 GitHub IP 允許清單的組織無法使用代管的 Connect,因為其位址並不固定。它改為在自己的伺服器上,或在其運行的 Connect 上註冊自己的 GitHub App
- 中斷連接只撤銷該次登入:Connect 會把它的重新整理權杖使用一次,並刪除該次使用所傳回的內容,同時刪除它的用戶權杖,以及 Connect 為其簽發的單一程式庫權杖。任何地方保留的該封存副本都會停止運作。此人在其他伺服器與工作區上的登入會繼續運作。若要把 Control Center 完全從一個 GitHub 帳戶移除,請在 GitHub 的 設定 → 應用程式 → 已授權的 GitHub Apps → 撤銷 中將其撤銷
共用的機器人
標題為「共用的機器人」的章節以 App 的機器人身分(as: app)簽發的權杖,對使用同一個 Connect 的每部伺服器,在 GitHub 上都顯示為同一個機器人:GitHub 無法分辨那些伺服器。
- 每部伺服器都可以讓機器人讀取與留言:
read、review與comment(issue 與 pull request 上的留言、標籤、指派對象與反應) - 以機器人身分審查 pull request(
bot,會寫入 pull request)只允許用於 Connect 營運者在CONNECT_GITHUB_REVIEW_BOT_INSTALLS中列出的伺服器。其他每部伺服器都會得到needs_requester回應,並以負責任的人自己的權杖發佈審查,而 GitHub 會把該權杖限定於該人:審查會以他們的名義顯示。這涵蓋 AI 審查的發佈、審查留言與審查者請求 - 推送、建立分支與開啟 pull request(
write)絕不會以共用機器人的身分簽發。它們一律使用請求者自己的登入 - 核准 pull request 在任何權杖上都絕不自動化
- 擁有自己 GitHub App 的伺服器或工作區,對以上所有工作(包括審查)都保留機器人身分
組織擁有者與成員應該知道的事
標題為「組織擁有者與成員應該知道的事」的章節- 在某部伺服器上登入,該伺服器便持有此人的 App 用戶權杖:每個權杖最長 8 小時,並會續期直到他們中斷連接。它能以此人的身分,在共用 App 已安裝、而此人可以觸及的每個儲存庫上行事。Connect 可以永久切斷某部伺服器(已退役或被拒絕的安裝),但已交出的權杖在到期前仍然有效
- 在組織上安裝共用的 GitHub App,等於同意任何成員登入的每部 Control Center 伺服器,而非某一部伺服器
- 如上所述,機器人是共用的:組織無法在 GitHub 上分辨是哪部伺服器以機器人身分行事
- 想要自己界線的組織,可註冊自己的 GitHub App 並運行自己的 Connect(執行 Connect 伺服器),或在自己的伺服器上配置該 App
設定信任
標題為「設定信任」的章節| Connect | 伺服器如何信任它的設定 |
|---|---|
| 代管 | 以內建於建置版本的金鑰驗證 Ed25519 簽章。拒絕低於它見過的最高世代號的設定(rollback) |
| 自訂 | 首次使用時釘選 GitHub 應用程式 id 與用戶端 id、Google 與 Linear 的用戶端 id,以及 Slack 應用程式與用戶端 id。任何變更都會暫停透過 Connect 的登入(pins_changed),直到伺服器擁有者按下信任新應用程式 |
伺服器的 Connect 設定都只限伺服器擁有者。
| 操作 | 作用 |
|---|---|
connect.status |
模式、網址、鎖定、安裝 ID、健康狀態、設定世代號,以及每條通道的來源 |
connect.configure |
設定 hosted、custom(搭配 url)或 off |
connect.test |
重新擷取設定並回報健康狀態 |
connect.confirmPins |
接受自訂 Connect 已更改的識別碼 |
connect.rotateKey |
產生新的安裝金鑰與新的安裝 ID(force 即使 Connect 無法撤銷舊的安裝 ID 也會將其取代);參見輪替安裝金鑰 |
工作區自己的選擇有獨立的操作,每個操作都會指明工作區:
| 操作 | 誰 | 作用 |
|---|---|---|
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 開始該通道,並取得供應商的授權網址,在顯示之前會先檢查它。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 伺服器上退役舊的安裝 ID,以舊金鑰簽署,並以伺服器從該 Connect 持有的一個憑證封存來證明。從那時起,Connect 會拒絕每個以舊金鑰提出的請求,因此從此伺服器取得的封存或舊金鑰副本都沒有用處;綁定到舊 ID 的 Slack 工作區亦會被釋放,以便它們重新連接。已交出的權杖在到期前仍然有效(機器人權杖為一小時,個人權杖為八小時)。此伺服器未持有任何封存的 Connect 伺服器沒有可退役的內容,會被略過
- 然後為伺服器取得新的安裝金鑰與新的安裝 ID
- 若某部 Connect 伺服器無法連線,或拒絕退役舊 ID,會在切換金鑰前停止,並顯示Connect 無法撤銷舊金鑰。仍要輪替無論如何都會切換金鑰;此時舊安裝 ID 在該 Connect 上仍可使用,直到其權杖到期,對 GitHub 而言最長為 8 小時
- 不影響透過伺服器自家應用程式的登入
- 需要把新的安裝 ID 加入自訂 Connect 的允許名單
狀態代碼
標題為「狀態代碼」的章節| 代碼 | 意義 |
|---|---|
hosted_unprovisioned |
這個建置版本沒有代管設定金鑰 |
signature |
代管設定未通過簽章檢查 |
rollback |
Connect 提供的設定比伺服器已見過的更舊 |
unreachable |
伺服器無法連到 Connect |
install_blocked |
Connect 不允許這個安裝 ID,或它已被退役 |
pins_changed |
自訂 Connect 公布了不同的應用程式識別碼 |
protocol |
Connect 的回應格式是這部伺服器無法理解的 |