Gadget 03：Gatekeeper 連携

外部サービス（GitHub / Google 等）との連携設定と“やってはいけない設定”まとめ

Gatekeeper 連携

Gatekeeper は外部サービスとの接続を中継する「ドライバ」です。 正しく連携する手順と、ついついやってしまいがちな“やってはいけない設定”をまとめます。

目的

  • GitHub / Google などの OAuth 連携を安全に設定する
  • 「動かない」→「危険」の両方の落とし穴を事前に把握する

前提条件

  • Cloudflare OS 本体が起動している（00-quickstart）
  • 連携先サービスのアカウントと管理権限
  • 秘密情報の置き場所（.dev.vars）の理解

手順（GitHub 連携を例に）

  1. 連携先で OAuth アプリを作成し、Client ID / Secret を取得

  2. コールバック URL を登録（https 必須のサービスが多い）

    • ローカル: http://localhost:8787/oauth/callback
    • 公開時: https://<あなたのドメイン>/oauth/callback

  3. 秘密情報を .dev.vars に記載（gitignored）

GITHUB_CLIENT_ID=xxxx
GITHUB_CLIENT_SECRET=xxxx

  1. pnpm run-local を再起動して反映

  2. UI から連携をテストし、Gatekeeper が connected になることを確認

Tip同梱 Gatekeeper 例

GitHub / Google / Cloudflare / Supabase / Notion / Confluence / Email Workers / Home Assistant / Slack / Spotify / ZoomInfo。 各 packages/gatekeeper-* の README に従って設定します。

やってはいけない設定（重要）

やってしまいがち なぜダメか 正しい形
コールバック URL を http のまま登録 多くの OAuth は http を拒否 https（Dev 時もホスト・ポートを完全一致）
.dev.vars を git にコミット Secret 漏洩 .gitignore に必ず追記（ドット含む正確な行）
.dev.vars に引用符や余白を入れる パースミスで認証が動かない 余分な " / 空白を入れない
コールバック URL の完全一致を無視 OAuth は完全一致でしか動かない 末尾の /・ポートまで一致させる
Secret をコードに直書き 改変・漏洩リスク 常に process.env / .dev.vars 経由

よくある失敗

症状 原因 対処
「Callback URL エラー」 URL が http / 一致しない https 化し、ホスト・ポート・パスを完全一致に
認証が即失敗 Client ID / Secret の誤り env | grep -i github で注入を確認
連携が「読み込み中」のまま .dev.vars 未反映 run-local を再起動
ログイン後に 401 Gatekeeper の binding が旧状態 .wrangler と wrangler.dev.jsonc を消して再起動

確認

次に読む