跳到內容

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 永遠看不到
伺服器的安裝 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 App 的安裝可以從每台伺服器使用。Connect 不記錄哪台伺服器可以使用它。

  • 設定 → 工作區 → 整合 中的安裝 GitHub 應用程式會開啟該應用程式在 GitHub 上的安裝頁面。伺服器會根據 Connect 設定中的應用程式名稱建立連結
  • 單一儲存庫的權杖需要應用程式已安裝在儲存庫擁有者的帳號上,並且登入的人可以存取該儲存庫。這是該人自己的權杖,受其角色限制,絕不會更多
  • 組織可以在 GitHub 上限制 Control Center:移除安裝、縮小儲存庫範圍,或移除該人
  • 對於只有該人能發出的呼叫,例如列出其安裝,Connect 會把該人自己的 App 使用者權杖交給伺服器,而不是單一儲存庫權杖。在某台伺服器上登入,就等於信任那台伺服器持有該權杖
  • 組織若強制 GitHub IP 允許清單,便無法使用代管的 Connect,因為它的位址並不固定。該組織應改為註冊自己的 GitHub App,並在自己的伺服器上或它所執行的 Connect 上使用
  • 中斷連線只撤銷該次登入:Connect 會把其重新整理權杖用掉一次,並刪除回傳的內容,同時刪除它的使用者權杖,以及為其簽發的單一儲存庫權杖。任何地方保存的該封存副本都會停止運作。該人在其他伺服器與工作區上的登入則維持運作。若要完全從 GitHub 帳戶移除 Control Center,請在 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。登入者一律是已登入的呼叫者本人。

  1. 伺服器要求 Connect 開始該通道,並取得供應商的授權網址,在顯示之前會先檢查它。GitHub 一律會顯示其帳戶選擇器
  2. 使用者在瀏覽器中核准。供應商返回 Connect
  3. Connect 會顯示發起登入的伺服器將能以該使用者身分做什麼,以及期限多長。Connect 無法分辨是誰在執行該伺服器,因此頁面只會在使用者是自己發起登入時請他繼續,若是有人傳給他連結,則請他關閉。當瀏覽器所在的網路與發起登入時不同,頁面會明確說明:對代管的伺服器或其他裝置而言,這是正常的,但這也正是釣魚攻擊的樣貌。取消會結束登入,供應商的代碼絕不會被使用。每個頁面只回答一次:不是來自 Connect 剛顯示之頁面的回答會被拒絕
  4. 按下繼續後,Connect 會顯示一組 8 個字元的代碼與一個 control-center://oauth-done 連結。任何拿到代碼的人都會得到剛核准的存取權,因此它只能送到發起登入的地方
  5. 使用者把代碼輸入應用程式,或點開連結。伺服器以該代碼及它自己對這次請求的證明認領這次登入

登入會在 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 的回應格式是這台伺服器無法理解的