コンテンツにスキップ

Control Center Connect リファレンス

Control Center Connect は、独自のアプリを登録していないサーバーのために、プロバイダーのサインインを実行します。サーバーは、Control Center がホストする Connect、組織が運用する Connect(Connect サーバーを実行)、またはなし、のいずれかを使います。この選択は 設定 → サーバー → シングルサインオン → Control Center Connect、cc_server connect、または CC_CONNECT_URL にあります。ワークスペースは、管理者が 設定 → ワークスペース → 連携 でそのワークスペースに別の選択をしない限り、この選択に従います(ワークスペースごとの選択)。

各プロバイダーが 1 つのレーンです。自分のアプリを使う(まだ選択されていない場合を含みます)の下では、レーンは、サーバー自身のアプリが完全に設定されていればそれで実行され、そうでなければ利用できません。Control Center のものまたはカスタムの 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 Connect がプロキシする GIF 検索

一部だけ設定された自前のアプリは、そのレーンをエラーにします。黙って Connect にフォールバックすることはありません。自分のアプリを使う を選んだワークスペースは、どのプロバイダーについてもサーバーのアプリや Connect を経由することはありません。サーバーの Connect の選択を変えても、自分の選択をしたワークスペースからサインアウトされる人はいません。

Connect に見えるもの Connect に決して見えないもの
サーバーのインストールID とリクエストの署名 ソースコード、リポジトリの内容、diff、プルリクエストのテキスト
サインイン中の、サインインしたプロバイダーアカウント チケット、トランスクリプト、ワークスペースのデータベース内のあらゆるもの
資格情報がどのワークスペースに属するか(シール内の不透明な ID として) サーバー自身のアプリのシークレット。それらがサーバーの外に出ることはありません
1 リポジトリ限定の GitHub トークンを発行する対象のリポジトリ 保存されたリフレッシュトークン。これはサーバーが保持するシールの中にしか存在しません
サーバーに結び付けられた Slack チーム Linear のシークレット。Linear のコードはサーバー自身が交換します
Klipy をプロキシする場合の GIF の検索語 パスワード、ペアリングキー、モデルプロバイダーのキー
Slack イベントの参照(チーム、チャンネル、メッセージ ID)とスラッシュコマンドのテキスト Slack のメッセージ本文。Connect は受信時に破棄し、サーバーが Slack からメッセージを自分で読み取ります

Connect は、進行中のサインイン、ノンス、キャッシュを最大 10 分間保持し、時間単位の利用カウンターを最大 2 時間保持します。人として発行された 1 リポジトリ限定の GitHub トークンは、それを要求したサインインに封印されたまま、期限切れ(最大 8 時間)まで記録されます。そのため Connect は、切断時にそれを再び渡したり取り消したりできます。永続的な記録は、Slack のバインディング(各 Slack チームがどのサーバーに結び付けられているか)と、引退したインストールID だけです。エラーにはコードが含まれますが、プロバイダーの応答が含まれることはありません。ログはインストールID を鍵付きハッシュとしてのみ記録し、GitHub トークンは、GitHub の組織の監査ログがそのトークンに示す hashed_token としてのみ記録します。そのため組織のオーナーは、両者を突き合わせられます。

モード 設定 動作
未設定 新しいサーバー どのレーンも Connect を使いません。オンボーディングでサーバー所有者に選択を求めます
hosted Control Centerのアプリを使う https://connect.usectrl.dev。オフラインで署名された構成を使います。サーバー自身のアプリは使われません
custom カスタムConnectサーバーを使う HTTPS URL(ループバックに限り http)の Connect。初回使用時に信頼されます。サーバー自身のアプリは使われません
off 自分のアプリを使う どのレーンも Connect を使いません。人々をサインインさせるのは自前のアプリだけです

サーバーの環境または .env の CC_CONNECT_URL は、選択を固定します: hosted、off、または Connect の URL です。設定画面はその固定を表示し、変更はできません。

このビルドにはホスト型の構成鍵が組み込まれていないため、ホスト型モードは hosted_unprovisioned を報告し、どのレーンも提供しません。自前のアプリとカスタム Connect は機能します。

ホスト型の Connect は単一のコンテナで動作します。そのシールキーと共有 GitHub App の秘密鍵は、そこでは環境変数であり、GitHub が App の秘密鍵について推奨するような、署名や復号しかできない保管庫の鍵ではありません。これは現在の構成の既知のギャップです。

サーバーは Connect の構成を最大 10 分ごとに読み取り、各呼び出しを最大 5 秒待ちます。Connect に到達できない場合は、最後の正常な構成が使われ続け、設定画面はそれを古いものとして示します。

設定 → ワークスペース → 連携 → Control Center Connect は、1 つのワークスペースについてサーバーの選択を上書きします。すべてのメンバーがそれを確認でき、各サインインがどこで実行されるかも見えます。変更できるのはワークスペース管理者だけです。

選択 動作
このサーバーと同じ 既定値です。ワークスペースは、サーバー所有者が選んだものに従って動きます。選択肢にその内容が表示されます
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 の構成にあるアプリ名からサーバーが組み立てます
  • 1 リポジトリ用のトークンには、アプリがリポジトリの所有者にインストールされていて、サインインした本人にそのリポジトリへのアクセス権があることが必要です。それは本人自身のトークンで、役割に応じて制限され、それ以上にはなりません
  • 組織は GitHub 上で Control Center を制限できます。インストールを削除するか、リポジトリを絞り込むか、本人を削除することで行います
  • インストールの一覧取得など、本人しか行えない呼び出しでは、Connect はサーバーに、1 リポジトリ限定のトークンではなく、本人自身の App ユーザートークンを渡します。サーバーにサインインすることは、そのトークンをそのサーバーに託すことを意味します
  • GitHub の IP 許可リストを強制している組織は、アドレスが固定されていないホスト型 Connect を使えません。代わりに、自社のサーバー上、または自社が運用する Connect 上で、独自の GitHub App を登録します
  • 切断 は、そのサインインだけを取り消します。Connect は更新トークンを一度使い、そこから返ってくるものを削除します。さらに、その人のユーザートークンと、Connect がその人のために発行した 1 リポジトリ限定のトークンを削除します。どこかに保存されたそのシールのコピーも機能しなくなります。その人の他のサーバーやワークスペースでのサインインは、引き続き機能します。Control Center を GitHub アカウントから完全に削除するには、GitHub の 設定 → アプリケーション → Authorized GitHub Apps → 取り消し で取り消してください

ボットとして発行されたトークン(as: app)は、同じ Connect を使うサーバーすべてで、GitHub 上では同じボットとして表示されます。GitHub は、それらのサーバーを区別できません。

  • どのサーバーでも、ボットは read、review、comment を使えます(Issue とプルリクエストのコメント、ラベル、担当者、リアクション)
  • ボットとしてプルリクエストをレビューすること(bot。プルリクエストへの書き込みを伴います)は、Connect の運営者が CONNECT_GITHUB_REVIEW_BOT_INSTALLS に一覧で挙げたサーバーにのみ許可されます。それ以外のすべてのサーバーには needs_requester が返され、レビューは責任を負う人自身のトークンで公開されます。GitHub はそれをその人に制限するため、レビューはその人の名前で表示されます。これには AI レビューの公開、レビューコメント、レビュアーの依頼が含まれます
  • プッシュ、ブランチの作成、プルリクエストの作成(write)は、共有ボットとして発行されることは決してありません。常に依頼者自身のサインインを使います
  • プルリクエストの承認は、どのトークンでも自動化されることは決してありません
  • 独自の GitHub App を持つサーバーやワークスペースは、レビューを含め、これらすべてにボットを保持します

組織のオーナーとメンバーが知っておくべきこと

「組織のオーナーとメンバーが知っておくべきこと」というセクション
  • サインインしたサーバーは、その人の App ユーザートークンを保持します。トークンごとに最大 8 時間で、切断されるまで更新されます。そのトークンは、本人が到達できる共有 App がインストールされたすべてのリポジトリで、その人として動作できます。Connect は、サーバーを完全に切り離せます(引退済みまたは拒否されたインストール)。ただし、すでに渡されたトークンは期限切れまで有効なままです
  • 共有 GitHub App を組織にインストールすることは、本人がサインインするすべての Control Center サーバーに同意することになり、1 つのサーバーだけへの同意ではありません
  • ボットは共有されます(上記のとおり)。組織は、どのサーバーがボットとして動作したかを GitHub 上で区別できません
  • 独自の境界を望む組織は、独自の GitHub App を登録し、独自の Connect を実行します(Connect サーバーを実行)。または、自社のサーバー上で App を設定します
Connect サーバーが構成を信頼する方法
ホスト型 ビルドに組み込まれた鍵で Ed25519 署名を検証します。これまでに見た最大のエポックより小さいエポックは拒否します(rollback)
カスタム GitHub のアプリ ID とクライアント ID、Google と Linear のクライアント ID、Slack のアプリ ID とクライアント ID を初回使用時に固定します。変更があると、サーバー所有者が 新しいアプリを信頼 を押すまで、Connect を通じたサインインは一時停止します(pins_changed)

サーバーの Connect 設定はサーバー所有者専用です。

操作 内容
connect.status モード、URL、固定、インストールID、ヘルス、構成のエポック、各レーンのソース
connect.configure hosted、custom(url 付き)、または off を設定します
connect.test 構成を再取得し、ヘルスを報告します
connect.confirmPins カスタム Connect の変更された識別子を受け入れます
connect.rotateKey 新しいインストールキーとインストールID を発行します(force は、Connect が古いものを無効化できなかった場合でも置き換えます)。インストールキーを更新するを参照してください

ワークスペースの選択には独自の操作があり、それぞれワークスペースを指定します:

操作 対象 内容
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 にレーンの開始を依頼し、プロバイダーの認可 URL を受け取ります。サーバーはそれを表示する前に検査します。GitHub は常にアカウント選択画面を表示します
  2. 本人がブラウザーで承認します。プロバイダーは Connect に戻ります
  3. Connect は、サインインを開始したサーバーが本人としてどこまで何をできるか、そしてそれがどれだけの期間有効かを表示します。Connect はそのサーバーを運用している人を判別できないため、ページは、本人が自分でサインインを開始した場合にのみ続行するよう求め、誰かからリンクが送られてきた場合は閉じるよう求めます。ブラウザーがサインインを開始したネットワークとは別のネットワークにある場合、ページはそのことを表示します。これはホスト型サーバーや別のデバイスでは普通のことですが、フィッシングの典型的な形でもあります。キャンセル はサインインを終了し、プロバイダーのコードは決して使われません。各ページは一度だけ応答します。Connect が表示したばかりのページからではない応答は拒否されます
  4. 続行 のあと、Connect は 8 文字のコードと control-center://oauth-done リンクを表示します。コードを受け取った人は、たった今承認されたアクセス権を得るため、コードはサインインを開始した場所にだけ渡してください
  5. 本人がコードをアプリに入力するか、リンクをたどります。サーバーはそのコードと、リクエストに対する自身の証明を使ってサインインを受け取ります

サインインは 10 分後に失効します。誤ったコードを 5 回入力すると終了します。このアプリが開始していないリンクは ここで開始されたサインインではありません で拒否されます。Connect は、1 つのネットワークアドレスが開始できるサインインの数と、GitHub トークンが発行される頻度を、人とサーバーごと、サーバーをまたいだ人ごと、アドレスごと、そしてアプリ全体ごとに制限します。新しいサインインには独自の予算があるため、他の人が必要とする更新を妨げることはありません。上限を超えた呼び出しは rate_limited で拒否され、サーバーは誰もサインアウトさせずに後で再試行します。本人の上限を超えたサインインは GitHub 上で取り消され、拒否されます。

鍵を更新できるのはサーバーオーナーだけで、設定 → サーバー → シングルサインオン の Control Center Connect カードにある 鍵を更新 で行います。これに対応するコマンドはありません。更新すると:

  • Connect を通じて実行されるすべてのレーンから、全員をサインアウトさせます。古い鍵が使われていた Connect サーバーごとに、サーバーはそこから保持している GitHub と Slack のサインインを取り消します(Google のサインインには取り消すものがなく、失効します)
  • それらの Connect サーバーごとに、古いインストールID を引退させます。これは古い鍵で署名し、その Connect から保持している資格情報シール 1 つで証明します。それ以降、Connect は古い鍵を使ったすべてのリクエストを拒否します。そのため、このサーバーから取得したシールや古い鍵のコピーは役に立たなくなります。古い ID に結び付けられていた Slack ワークスペースは解放され、再び接続できるようになります。すでに渡されたトークンは期限切れまで有効なままです(ボットトークンは 1 時間、人のトークンは 8 時間)。このサーバーがシールを保持していない Connect サーバーには、引退させるものがないためスキップされます
  • その後、サーバーに新しいインストールキーと新しいインストールID を与えます
  • Connect サーバーに到達できない場合、または古い ID の引退を拒否する場合は、鍵を切り替える前に停止し、Connect は古い鍵を無効化できませんでした と表示します。それでもローテーション は、いずれの場合も鍵を切り替えます。その場合、古いインストールID は、そのトークンが期限切れになるまで(GitHub では最大 8 時間)、その Connect で使用可能なままになります
  • サーバー自身のアプリを通じたサインインには影響しません
  • カスタム Connect の許可リストに、新しいインストールID を追加する必要があります
コード 意味
hosted_unprovisioned このビルドにはホスト型の構成鍵がありません
signature ホスト型の構成が署名の検証に失敗しました
rollback Connect が、サーバーがすでに見たものより古い構成を提供しました
unreachable サーバーが Connect に到達できません
install_blocked Connect がこのインストールID を許可していないか、引退済みです
pins_changed カスタム Connect が異なるアプリ識別子を通知しました
protocol Connect が、このサーバーの理解できない形式で応答しました