Connect サーバーを実行
Control Center Connect は、独自のアプリを登録していないサーバーのために、プロバイダーのサインイン(GitHub、Google Calendar、Linear、Slack)を実行します。このガイドでは独自の Connect を実行する方法を説明します。そうすれば、プロバイダーアプリ、そのシークレット、それらを使ってよいサーバーの一覧がすべて手元にとどまります。
Connect に何が見え、何が見えないかは Connect リファレンスにあります。運用するかどうかを検討しているなら、先にそちらを読んでください。
前提条件
「前提条件」というセクション- TLS を終端するプロキシの背後にある、Connect 用の公開 HTTPS アドレス(例:
https://connect.example.com)。プレーンなhttpはループバックでのみ受け付けられます - Docker、または追加の環境変数を付けて再起動できる
cc_server - 提供したい各プロバイダーにアプリを登録する権限
- それを使うサーバーと、その所有者への連絡手段。各サーバーには、Connect の許可リストに追加するインストールID があります
ステップ 1: アドレスを決める
「ステップ 1: アドレスを決める」というセクションここで URL を決め、変えないでください。CONNECT_PUBLIC_URL は Connect が行うすべてに関わります。リクエストの署名、封印された資格情報、プロバイダーのリダイレクト URL、各サーバーのインストールID は、すべてこれに結び付けられます。後から変更すると、リダイレクトを登録し直し、全員がもう一度サインインすることになります。
ステップ 2: プロバイダーアプリを登録する
「ステップ 2: プロバイダーアプリを登録する」というセクション提供したいプロバイダーだけを登録します。変数がそろっていないプロバイダーは Connect の構成から除外され、サーバーからは利用不可として見えます。以下の <base> は、あなたの CONNECT_PUBLIC_URL です。
| プロバイダー | 登録するもの | 控えておくもの |
|---|---|---|
| GitHub App | Callback URL <base>/oauth/github/callback。Setup URL <base>/oauth/github/setup で Redirect on update をオンにします。Request user authorization (OAuth) during installation はオフのままにします。オンにすると GitHub は Setup URL を無視します。Expire user authorization tokens はオンのままにします |
App ID、スラッグ、クライアント ID、クライアントシークレット、秘密鍵 |
リダイレクト URI <base>/oauth/google/callback を持つ種類 Web application の OAuth クライアント。Google Calendar API を有効にします |
クライアント ID、クライアントシークレット | |
| Linear | コールバック URL <base>/oauth/linear/callback と <base>/oauth/linear_app/callback を持つ OAuth アプリケーション |
クライアント ID のみ |
| Slack | リダイレクト URL <base>/oauth/slack_oidc/callback と <base>/oauth/slack/callback。Event Subscriptions を <base>/v1/hooks/slack/events に(app_mention、message.*、assistant_thread_*、app_uninstalled、tokens_revoked)。スラッシュコマンドを <base>/v1/hooks/slack/commands に。トークンローテーションをオンにします |
App ID、クライアント ID、クライアントシークレット、署名シークレット |
GitHub App には次のリポジトリ権限を付与します: Metadata は読み取り、Contents は読み取りと書き込み、Pull requests は読み取りと書き込み、Issues は読み取りと書き込み、Checks、Actions、Commit statuses は読み取り。チームへのレビュー依頼のために、組織の Members の読み取りも追加します。Webhook はオフのままでかまいません。サーバーはポーリングします。
Connect には GitHub App の秘密鍵が必要です(アプリの設定の Generate a private key で作成します)。Connect は、リポジトリをカバーするインストールを見つけるリクエストに署名し(リポジトリにインストールがない場合は、オーナーのインストール)、1 リポジトリ限定のインストールトークンを発行します。いずれも、依頼した人自身のサインインがそのリポジトリへのアクセスを証明した後にのみ行われます。
Connect に接続するすべてのサーバーは、アプリのボットを共有します。ボットとして、そのいずれのリポジトリでも読み取り、コメント、ラベル付け、リアクションを行うことがあります。ボットとしてプルリクエストをレビューできるのは、CONNECT_GITHUB_REVIEW_BOT_INSTALLS(インストール ID をカンマ区切りで)に挙げたサーバーだけです。それ以外のサーバーは、レビュアー自身のトークンでレビューを公開します。プッシュがボットとして行われることは決してありません。自前のサーバーにボットとしてレビューさせるには、そのインストール ID を追加して再起動します。鍵ファイルはシール鍵と同じように、シークレットとして保管してください。Linear もシークレットを必要としません。Connect はコードをサーバーに返し、サーバーが自らやり取りを完了します。
ステップ 3: インストールID を集める
「ステップ 3: インストールID を集める」というセクションConnect は許可リストにあるサーバーにだけ応答します。各サーバーで、接続先をあなたの Connect にしてから、そのインストールID を読み取ります:
- 設定 → サーバー → シングルサインオン に移動し、Control Center Connect カードを開いて カスタムConnectサーバーを使う を選びます
- URL を入力して保存します。カードにサーバーの インストールID が表示されます
サーバーホストのターミナルからは、次のようにします:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus はインストールID を出力します。ステップ 5 が終わるまでは install_blocked と表示されますが、これは想定どおりです。
インストールID は Connect のアドレスごとに導出されるため、同じサーバーでも、通信する Connect ごとに異なる ID を持ちます。ID が変わるのは、所有者が鍵を更新したときだけです。
ステップ 4: シール鍵を作成する
「ステップ 4: シール鍵を作成する」というセクションConnect は、返すすべての資格情報をシール鍵で暗号化します。1 つ作成し、シークレットファイルとして保管します:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysシール鍵を失うと、全員がサインアウトされます。それなしではどのシールも開けません。
ステップ 5: コンテナーを起動する
「ステップ 5: コンテナーを起動する」というセクション各リリースでは、ビルドの来歴付きで ghcr.io/samuelalev/cc-connect が公開されます。本番環境ではバージョンタグを固定してください。
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リバースプロキシをポート 8790 に向け、CONNECT_TRUST_PROXY には Connect の前にあるプロキシの数を設定して、アドレスごとの制限が各クライアントのアドレスを見られるようにします。イメージは非特権ユーザーとして動作し、状態を /data ボリュームに保持し、組み込みのヘルスチェック(/healthz を確認する cc-connect --healthcheck。プロセスが応答しているかを確認します)を備えています。/readyz は、状態とバインディングのストアが応答すること、そして Redis を使う場合はそれが maxmemory-policy noeviction で動いていることも確認します。オーケストレーターの準備完了チェックはそこに向けてください。
サインインの同意ページは、Connect 自身のページからのみ受け付けられるフォーム投稿で応答します。Sec-Fetch-Site は送られてくる場合、same-origin でなければならず、Origin は送られてくる場合、CONNECT_PUBLIC_URL のオリジンでなければなりません。どちらもない投稿は拒否されます。そのため、プロキシはこの 2 つのヘッダーを変更せずに通す必要があり、CONNECT_PUBLIC_URL は人々のブラウザーが実際に使うアドレスでなければなりません。そのページで続行するたびに「このリンクは期限切れです」と表示され、ログに理由 origin または no_origin の oauth.done_refused が出ている場合は、この 2 つのどちらかが正しく設定されていません。
構成が開放的すぎる、安全でない、または未完成の場合、Connect は起動を拒否し(終了コード 78)、どの変数が誤っているかを出力します。許可リストがない、ループバック以外で http のアドレスを使っている、シール鍵の形式が不正、NAME と NAME_FILE の両方が設定されている、のいずれでも起動は止まります。
チェックポイント: 各サーバーで Connect カードに 動作中 と表示され、各サインインの実行場所 で、登録したすべてのプロバイダーに Connect と表示されます。cc_server connect status は Health: ok と同じレーンを出力します。
cc_server 内に Connect をマウントする
「cc_server 内に Connect をマウントする」というセクションサーバーは、別のコンテナーの代わりに、自分自身で Connect をホストできます。マウントされるサービスは、イメージが実行するものと同じです。
CONNECT_*変数をサーバーの.envファイルに置きます(ステップ 5 と同様)。CONNECT_SENTRY_DSNを含め、Connect のシークレットがサーバーの環境にエクスポートされている場合、サーバーは起動を拒否しますCC_SERVER_CONNECT_HOST=onを追加します- サーバーを再起動します。ログに
embedded Connect at <url>と出力されます
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_GITHUB_CLIENT_SECRET=<secret>CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pemConnect は <server>/connect で提供されます:
CONNECT_PUBLIC_URLの既定値は、サーバーの公開 URL のオリジンに/connectを付けたものです。プロキシの背後では明示的に設定してください。パスは正確に/connectでなければならず、ループバックでない限り HTTPS でなければなりません- マウントされたサービスに届くのは
CONNECT_*変数だけなので、サーバー自身のプロバイダーアプリを借りることはありません CONNECT_ALLOWED_INSTALLSは、ホストしているサーバー自身を含めて、引き続き必須です- 構成を誤ったマウントは、開放されたブローカーを提供するのではなく、サーバーの起動を止めます
- デモサーバーがこれをマウントすることはありません
プロバイダーのリダイレクトを https://<server>/connect に対して登録し、ステップ 3 と同様に、サーバー(ホストしているサーバーを含む)の接続先をその URL にします。
構成リファレンス
「構成リファレンス」というセクションすべての設定は環境変数です。どのシークレットも、代わりにマウントしたファイルから読み込めます。NAME の代わりに NAME_FILE を設定します。Connect はファイルを最大 30 秒ごとに読み直し、最後の正常な値を保持します。dual と記したシークレットは、ローテーション中に NAME_PREVIOUS(または NAME_PREVIOUS_FILE)も受け付けます。
アドレスとアクセス
「アドレスとアクセス」というセクション| 変数 | 既定値 | 意味 |
|---|---|---|
CONNECT_PUBLIC_URL |
必須 | 正規の公開 URL。HTTPS、またはループバックでのみ http。パスがあればマウントを意味します。クエリやフラグメントは不可 |
CONNECT_ALLOWED_INSTALLS |
必須 | カンマ区切りのインストールID。* は CONNECT_SIGNED_CONFIG_FILE と組み合わせた場合にのみ受け付けられます |
CONNECT_DENY_INSTALLS |
許可されていても拒否するインストールID | |
CONNECT_GITHUB_ALLOWED_OWNERS |
数値の GitHub オーナー ID。設定すると、それらが所有するリポジトリに対してだけリポジトリトークンが発行されます。サインインできる人を制限するものではありません。この Connect の利用を許可された人は、引き続き自身の GitHub App ユーザートークンを受け取ります。1 つの組織だけに提供するには、アプリをその組織専用にしてください | |
CONNECT_GITHUB_REVIEW_BOT_INSTALLS |
アプリのボットがプルリクエストをレビューしてよいインストール ID。既定では空です。* は拒否され、各 ID も許可されている必要があります |
|
CONNECT_HOST, CONNECT_PORT |
0.0.0.0, 8790 |
バインドアドレスとポート |
CONNECT_TRUST_PROXY |
0 |
X-Forwarded-For で信頼するプロキシのホップ数(0〜8)。アドレスごとの制限、サインインページのネットワークのヒント、ログに記録されるアドレスにのみ使われます。プロキシの背後では、0 はすべてのクライアントをプロキシとして数え、ログにその旨が一度出力されます |
プロバイダーのレーン
「プロバイダーのレーン」というセクション| 変数 | 既定値 | 意味 |
|---|---|---|
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID |
GitHub App | |
CONNECT_GITHUB_CLIENT_SECRET |
シークレット、dual | |
CONNECT_GITHUB_APP_PRIVATE_KEY |
シークレット。App の秘密鍵(PEM) | |
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET |
Google クライアント。シークレットは dual | |
CONNECT_LINEAR_CLIENT_ID |
Linear アプリケーション。シークレットなし | |
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID |
Slack アプリ | |
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET |
シークレット、dual | |
CONNECT_KLIPY_APP_KEY |
Klipy の GIF 検索キー。シークレット、dual | |
CONNECT_KLIPY_MODE |
proxy |
proxy はキーを Connect に保持し、key はキーをサーバーに渡します |
CONNECT_<LANE>_SECRET_GENERATION |
1 |
GitHub、Google、Slack: 新しいシールに記録される世代 |
CONNECT_<LANE>_MIN_SEAL_GENERATION |
1 |
GitHub、Google、Slack: これより古いシールは再度サインインが必要 |
CONNECT_<LANE>_ACCEPTS_NEW |
true |
すべてのレーン: false にすると新規サインインを止め、既存のものは更新を続けます |
シール、状態、ストレージ
「シール、状態、ストレージ」というセクション| 変数 | 既定値 | 意味 |
|---|---|---|
CONNECT_SEAL_BACKEND |
local |
local または gcp-kms |
CONNECT_SEAL_KEYS |
シークレット。local では必須。カンマ区切りの kid:key エントリーで、新しいものが先。古いエントリーも引き続き復号に使われます |
|
CONNECT_KMS_KEY |
projects/…/locations/…/keyRings/…/cryptoKeys/…。gcp-kms では必須 |
|
CONNECT_STATE |
memory |
1 インスタンスなら memory、複数なら redis。満杯のメモリストアは、生きているエントリーを忘れる代わりに、新しいサインインとリクエストを拒否します |
CONNECT_REDIS_URL |
シークレット。redis:// または rediss://。Redis 6.2 以降で maxmemory-policy noeviction が必要で、どちらも起動時に確認されます |
|
CONNECT_REDIS_CA_FILE |
rediss:// 用の CA バンドル |
|
CONNECT_BINDINGS |
file |
Slack チームのバインディングの保存先: file または firestore |
CONNECT_DATA_DIR |
data(イメージでは /data) |
bindings.json を保持します。1 つの Connect がロックするため、同じディレクトリを使う 2 つ目の Connect は起動しません |
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE |
(default) データベース |
CONNECT_BINDINGS=firestore 用。Firestore が応答しない場合、Connect は起動しません |
構成、ログ、制限
「構成、ログ、制限」というセクション| 変数 | 既定値 | 意味 |
|---|---|---|
CONNECT_SIGNED_CONFIG_FILE |
オフラインで署名された構成。そのまま提供されます。Control Center がホストする Connect が使います | |
CONNECT_CONFIG_PUBLIC_KEYS |
署名された構成の検証に使う鍵 | |
CONNECT_CONFIG_EPOCH |
1 |
セルフホストの Connect が生成する構成のエポック |
CONNECT_LOG_HMAC_KEY |
プロセスごとにランダム | シークレット。設定すると、インストールID の代わりとなるタグが再起動やインスタンスをまたいで安定します |
CONNECT_SENTRY_DSN |
シークレット。エラー行が報告される https の Sentry DSN。報告されるのはエラーの型、スタックフレーム、ルート、リクエスト ID で、メッセージ、本文、ヘッダーは決して含みません | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
Sentry の環境 |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
/v1/version が報告します |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
インストールごとのリクエスト数 |
CONNECT_RATE_IP_PER_MINUTE |
300 |
アドレスごとのリクエスト数(IPv6 アドレスは /64 ごとに数えます) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
インスタンス全体のリクエスト数 |
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE |
600 |
アドレスごとの Slack イベントとコマンドの配信数。他のリクエストとは別に数えます |
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND |
100 |
インスタンス全体の Slack イベントとコマンドの配信数 |
CONNECT_RATE_SLACK_TEAM_PER_MINUTE |
600 |
チームごとの Slack イベント数 |
CONNECT_RATE_KLIPY_PER_MINUTE |
120 |
インストールごとの GIF 検索数 |
CONNECT_RATE_KLIPY_IP_PER_MINUTE |
240 |
アドレスごとの GIF 検索数(サーバーをまたぐ) |
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES |
60 |
アドレスごとに開始されるサインイン数 |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR |
30 |
1 つのサーバーで、GitHub アカウントごとに発行される GitHub トークン数(サインイン、更新、リポジトリトークン) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
上記の 4 倍(120) |
同じ制限を、すべてのサーバーをまたいで GitHub アカウントごとに適用 |
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR |
600 |
アドレスごとに発行される GitHub トークン数 |
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR |
500 |
アプリ全体での新しい GitHub サインイン数 |
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR |
120 |
サーバーごとのボットトークン数 |
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR |
240 |
依頼した GitHub アカウントごとのボットトークン数(サーバーをまたぐ) |
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR |
3000 |
アプリ全体のボットトークン数 |
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR |
1500 |
アプリ全体の更新とリポジトリトークン。新しいサインインには、上記の別の制限があります |
CONNECT_GITHUB_TOKEN_CAP_WARN |
10 |
1 つの GitHub アカウントが保持してよい有効なリポジトリトークンの数。これを超えると Connect が警告をログに記録します |
CONNECT_RATE_RETIRE_IP_PER_HOUR |
10 |
アドレスごとに退役させるインストール ID 数(IPv6 は /48 ごと) |
制限を超えた呼び出しには rate_limited が返されます。サーバーは後で再試行し、そのためにサインアウトさせられることは決してありません。
複数のインスタンスを実行する
「複数のインスタンスを実行する」というセクションほとんどの組織では、CONNECT_STATE=memory の 1 インスタンスで十分です。1 つのアドレスの背後に複数のインスタンスを置く場合は、CONNECT_STATE=redis と CONNECT_BINDINGS=firestore が必要です。そうすれば、あるインスタンスで始まったサインインを別のインスタンスで完了でき、すべてのインスタンスが同じ Slack のバインディングと退役したインストール ID を参照します。共有の CONNECT_DATA_DIR は機能しません。最初の Connect がそれをロックしてしまうためです。インストールごと、アドレスごと、インスタンスごとのリクエスト制限はインスタンスごとです。サインイン、GitHub トークン、ボットトークン、アドレスごとの GIF 検索、退役、Slack チームの制限は、状態ストアを通じて共有されます。
プロバイダーのシークレットをローテーションする
「プロバイダーのシークレットをローテーションする」というセクション誰もサインアウトされません:
- プロバイダーで新しいシークレットを作成し、古いものは残しておきます
- 古い値を
NAME_PREVIOUSに移し、新しい値をNAMEに入れて、CONNECT_<LANE>_SECRET_GENERATIONを上げます。マウントしたファイルは 30 秒以内に反映されます - サインインが更新されるのを待ってから、プロバイダーで古いシークレットを削除し、
NAME_PREVIOUSを取り除きます
シール鍵をローテーションするには、新しい cc-connect-config seal-key のエントリーを CONNECT_SEAL_KEYS の先頭に置き、古いエントリーはそのシールが更新されるまで残しておきます。
アプリを変更する
「アプリを変更する」というセクションサーバーは、初めて使ったときにあなたの Connect が通知したアプリ ID とクライアント ID を記憶しています。アプリを置き換えると、すべてのサーバーの Connect カードに Connectのアプリが変更されました と表示され、所有者が 新しいアプリを信頼 を押すまで、Connect を通じたサインインは一時停止します。切り替える前にサーバー所有者に知らせておけば、その確認があなたによるものだとわかります。
サーバーをブロックする
「サーバーをブロックする」というセクションそのインストールID を CONNECT_DENY_INSTALLS に追加して再起動します。所有者には「ConnectがこのサーバーのインストールIDをブロックしました。Connectサーバーの運営者に連絡してください。」と表示され、そのサーバーでの Connect によるサインインはすべて停止します。
サーバーは、所有者が鍵を更新したとき、自身の古いインストール ID も退役させます。その ID が自分のものであることは、この Connect が同サーバーのために作成した資格情報シール 1 つで証明します。そのため、誰かをサインインさせたことのあるサーバーだけが ID を退役させられます。Connect は退役した ID を永久に保持するため、古い鍵とそれで作成されたすべてのシールは機能しなくなり、古い ID にバインドされていた Slack ワークスペースは解放されます。既に発行されたトークンは自然に期限切れになります。人のトークンは 8 時間以内、ボットのトークンは 1 時間以内です。Connect が保持できる退役した ID は最大 100,000 件です。それを超えると、ローテーションは拒否され、ログにエラーレベルでその旨が記録されます。
トラブルシューティング
「トラブルシューティング」というセクションサーバーに、Connect にブロックされたと表示される
「サーバーに、Connect にブロックされたと表示される」というセクションそのインストールID が CONNECT_ALLOWED_INSTALLS にないか、CONNECT_DENY_INSTALLS に含まれているか、鍵のローテーションで退役しています。ID は所有者が鍵を更新すると変わるので、新しい ID を尋ねてください。
1 つのプロバイダーのサインインがすべて失敗する
「1 つのプロバイダーのサインインがすべて失敗する」というセクションそのいずれかの変数が欠けている可能性があるため、Connect がレーンを除外しました。起動ログと上の表を確認してください。GitHub には App ID、スラッグ、クライアント ID、クライアントシークレット、秘密鍵の 5 つすべてが、Google にはクライアント ID とシークレットの両方が必要です。
サインインがリダイレクトの不一致で失敗する
「サインインがリダイレクトの不一致で失敗する」というセクションプロバイダーに登録したリダイレクトが CONNECT_PUBLIC_URL と完全には一致していません。スキーム、ホスト、ポート、そしてマウントした Connect なら /connect のパスを比べてください。
全員が再度サインインしなければならなかった
「全員が再度サインインしなければならなかった」というセクションシール鍵が変わったか失われた、サーバーが鍵を更新した、またはサーバーのデータが別のマシンに復元されました。封印された資格情報は、それを作成したインストールと Connect に対してだけ開きます。