社内サイト向けの Cloudflare Access

Worker の手前に置く identity ベースの境界認可 -- アカウント単位のセットアップ、zone なしで workers.dev とプレビューまで覆う Worker スコープのアプリケーション、WebSocket の制約、そして Worker から呼び出し元の identity を読む方法

概要 -- Access は許可リストであって、サインアップの仕組みではない

Cloudflare Access は、リクエストがオリジンに届く前に、サイトの手前で identity のチェックを行う。訪問者が URL を開き、identity プロバイダーへリダイレクトされ、自分が誰であるかを証明し、署名済みのセッションを持って戻ってくる -- そのすべてが Cloudflare のエッジで強制され、そのどれもが自分で書くコードではない。

Access がどこに嵌まるかを決める言葉は許可リストだ。入ってよい相手を列挙し -- 特定のメールアドレス、メールドメイン、identity プロバイダーのグループ -- 新しい誰かを迎え入れるには管理者がポリシーを編集する。セルフサービスの登録は、設計上、存在しない。

3 つの道具、3 つの想定閲覧者

Access はパスワードゲートを置き換えるものではない。両者が答えているのは閲覧者が誰であり、その人を登録するのにどれだけのコストがかかるかという別々の問いであり、最も安く済む正しい道具は、たいていの場合いちばん強力な道具ではない。

最初の行がこの区別のすべてだ。Access には、その人が現れる前に登録して許可リストに載せられる identity が必要になる。ステージングビルドをレビューするクライアント、2 週間だけ関わる業務委託、社内のディレクトリに追加できない社外のレビュアー -- そうした相手には「URL とパスワードを送る」が正しい答えのままであり、道具もパスワードゲートのままだ。One-time PIN はこの差を縮めるが（後述）、埋めはしない: それでも相手のアドレスを事前に知っていなければならない。

この 3 つは組み合わせられる。成熟した構成では、エンドユーザーにはアプリケーションレベルの認証を、/admin とすべてのプレビューデプロイには Access を、クライアントに渡す唯一のステージング URL にはパスワードゲートを、それぞれ走らせる。

セットアップはアカウント単位であり、トークン単位ではない

API トークンのどこにも、Access が使えるかどうかを決める要素はない。Access は Zero Trust の中にあり、それは Cloudflare アカウントごとに有効化されるもので、ダッシュボードはその完全なインターフェイスになっている -- トークンが必要になるのは、Access をコードから管理するつもりがある場合だけだ。

ポリシーが 1 つでも存在する前に、一度だけ決めることが 3 つある。

1. Zero Trust の organization。Zero Trust ダッシュボードへの最初の訪問でチーム名を尋ねられ、それがチームドメイン <team>.cloudflareaccess.com になる。このホスト名はすべてのログインが着地する場所であり、結果として発行される JWT の iss クレームでもある。あとから改名するのは影響が大きい -- 慎重に選ぶこと。

2. プラン。現在の Free ティアの上限は、Cloudflare の Zero Trust プランページで確認する。記憶している数字を信用しないこと -- 広く言われている「50 ユーザー」という上限は 2022 年の文書に由来するもので、現在のプランページに書かれている内容とは異なる。また Cloudflare 自身のアカウント上限のページは、他のいくつかの機能をプランごとに段階分けしている一方で、ユーザー数の上限についてはまったく述べていない。

3. ログイン方法。本物の identity プロバイダー（Google Workspace、Microsoft Entra、Okta）か、IdP の設定をまったく必要としない One-time PIN のどちらかだ。One-time PIN では、訪問者がメールアドレスを入力し、Send login code を選び、メールで届いた PIN を貼り戻す。PIN はリクエストから 10 分で期限切れになる。

ホスト名ではなく Worker に Access を紐づける

従来の Access アプリケーションはホスト名に紐づくもので、これは *.workers.dev で配信される Worker にとって、歴史的に厄介な問いを生んでいた: それは自分が所有する zone ではない、という問いだ。Access アプリケーションは今では Worker 自体を対象にできるようになっており、この問いを丸ごと回避できる。

Cloudflare の Workers ドキュメントによれば、Worker スコープのアプリケーションはその Worker に紐づくすべてのドメイン -- ルート、Custom Domains、workers.dev のホスト名、そしてプレビュー -- を保護する。zone も、カスタムドメインも、DNS レコードも必要ない。

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "type": "self_hosted",
    "name": "Access for my-worker",
    "destinations": [{ "type": "worker", "worker_id": "c81a2d22c29840ed9d61681a3270dbff" }],
    "policies": [{
      "decision": "allow",
      "include": [{ "email_domain": { "domain": "example.com" } }]
    }]
  }'

API スキーマには書かれているが散文には書かれていない制約が 2 つある: all_workers と all_preview_workers の destination は、アカウントごとにそれぞれ最大1 つしか存在できない。そして destinations のリストは Worker 以外のバリアントも受け付ける（ホスト名や URI を指す public、CIDR/ポートを指す private、via_mcp_server_portal）。public は古いホスト名の形をした destination であり、Worker スコープのものではない。これを worker と同等のものだと取り違えるのは、期待した対象を何ひとつ覆わないアプリケーションを作ってしまう簡単な方法だ。

優先順位と、ポリシーを削除しても何も変わらないことがある理由

もっとも具体的なルールが勝つ。まずホスト名ベース（またはパスベース）の Access、次に Worker レベル、そして最後のフォールバックとしてアカウントレベルの all_workers だ。頭に入れておく価値のある帰結 -- そして Cloudflare 自身が、Worker レベルの Access を削除するとその下のアカウントレベルの Access が露出しうると明言している点 -- は、all_workers が動いているアカウントでは、ある Worker 自身のポリシーを削除してもその Worker が公開されるわけではないということだ。その下にあるアカウント全体のルールへ落ちるだけである。

特定の Worker を除外するには、削除ではなく明示的な bypass が要る:

{
  "decision": "bypass",
  "include": [{ "everyone": {} }]
}

これを、当該 Worker の worker デスティネーションに対して適用する。

訪問者に実際に見えるもの

identity プロバイダーがすでに設定されている場合 -- Zero Trust を他の用途でも使っている会社では普通のケースだ -- ほとんどの人は何も入力しない。

実務で効いてくる細部が 2 つある。

• 元のディープリンクが生き残る。 /items/123 へのリンクをクリックした訪問者は、サイトのルートではなく /items/123 に戻ってくる。共有されたリンクは機能し続ける。

• 拒否されたユーザーに見えるのは Cloudflare のブロックページであり、自分の 404 ではない。 ポリシーに載っていない同僚には、誰に聞けばいいのか分からない汎用的な拒否画面が見える。ブロックページはカスタマイズできる -- 名前かチャンネルを書いておくこと。さもなければ最初のサポート依頼は、リンクが壊れているのはなぜかという問い合わせになる。

IdP の代わりに One-time PIN を使う場合、訪問者は 2 回入力する: メールアドレスと、メールで届く 6 桁のコードだ。使えるコードが届くのは、ポリシーに一致するアドレスだけだ。

誰がどのくらいの頻度で再認証するかは設定でき、その設定は混同しやすい 3 つのレベルに分かれている。アプリケーションのセッション期間（Applications > Configure > Overview）は、即時タイムアウトから 1 か月までの範囲を取り、デフォルトは 24 時間だ。ポリシーは、そのポリシーに一致する人に対して同じ範囲でそれを上書きできる。グローバルのセッション期間はさらに別物で、アカウント全体での IdP への再ログインを支配し、15 分から 1 か月までの範囲を取り、こちらもデフォルトは 24 時間だ。Cloudflare One Client のセッションが存在する場合は、それがこれらすべてを上書きする。

Worker で identity を読む

リクエストが通過してしまえば、Worker はそれを送ったのが誰かを読める -- JWT のパースもライブラリも要らない。

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // ctx.access is undefined when Access did not authenticate the request
    // -- e.g. the Worker is reachable on a route the application does not
    // cover. Treat that as a failure, not as an anonymous visitor.
    if (!ctx.access) {
      return new Response("Access required", { status: 403 });
    }

    const identity = await ctx.access.getIdentity();
    return new Response(`Signed in as ${identity?.email ?? "unknown"}`);
  },
};

アプリケーションの audience タグは同じオブジェクト上にあり、ctx.access.aud として取れる。

これは共有パスワードには原理的に提供できない能力だ: 訪問者ごとの帰属付けである。どの項目を誰がトリアージしたかを記録することも、サインイン中のユーザーを表示することも、認証システムを書かずに可能になる。

ホスト名ベースのアプリケーションの場合、あるいは明示的な検証を行いたい場面では、代わりに Cf-Access-Jwt-Assertion ヘッダーをチームの JWKS エンドポイントに対して検証する。鍵は取得すること。決してハードコードしないこと。

import { createRemoteJWKSet, jwtVerify } from "jose";

// Module-level cache so one isolate reuses a single JWKS fetcher across
// requests. It cannot be built at module scope directly: `env` only exists
// inside the handler, so the URL is not known until the first request.
const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();

function getJwks(teamDomain: string) {
  let jwks = jwksCache.get(teamDomain);
  if (!jwks) {
    jwks = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`));
    jwksCache.set(teamDomain, jwks);
  }
  return jwks;
}

export async function verifyAccessJwt(request: Request, env: Env) {
  const token = request.headers.get("Cf-Access-Jwt-Assertion");
  if (!token) throw new Error("Missing Cf-Access-Jwt-Assertion header");

  return await jwtVerify(token, getJwks(env.TEAM_DOMAIN), {
    issuer: env.TEAM_DOMAIN,
    audience: env.POLICY_AUD, // the application's AUD tag
  });
}

ここでの TEAM_DOMAIN は完全なオリジン -- https://my-team.cloudflareaccess.com であり、スキームを含み、末尾のスラッシュは付けない。これが 2 回使われるのには別々の理由がある: new URL() は裸のホスト名をそもそも受け付けないこと、そして Access が署名する iss クレームがオリジンの形であるため、スキームを省いた値は URL の組み立てがたまたま通った場合でも issuer の検証に失敗することだ。

これと同じ RS256 + JWKS の形は Pages Functions での認証にも登場する -- Access もまた 1 つのサードパーティ発行者であり、同じやり方で検証される。

ローカル開発で identity を模擬する

wrangler dev の手前には Access がないため、ローカルのリクエストではすべて ctx.access が undefined になり、上のガードはすべてを拒否してしまう。代わりに access.dev ブロックが偽の identity を供給する。

{
  "access": {
    "dev": {
      "aud": "my-app", // required -- Wrangler will not start without it
      "identity": { "email": "admin@example.com" } // optional
    }
  }
}

このブロックを取り除けば ctx.access は undefined に戻る。未認証側の分岐をテストするにはこうする。

API トークンの権限は、デプロイ用トークンとは別物

Access の背後に置かれる Worker をデプロイするのに、デプロイ用トークンへの Access 権限は一切必要ない。Access アプリケーションは /accounts/{account_id}/access/apps を通じて作成されるが、これは Worker のアップロードが決して触らない API サーフェスであり、Cloudflare 自身のダッシュボードが生成するデプロイ用トークンには Access: の権限がそもそも 1 つも含まれていない。Access を有効にしても既存のデプロイパイプラインは壊れず、デプロイ用トークンは今のまま狭く保っておけばよい（Cloudflare セットアップを参照）。

権限が必要になるのは、Access をコードから管理する場合 -- Terraform や直接の API 呼び出し -- だ。そのためには別のトークンを作る。いずれもアカウントスコープだ。

関連

• プレビュー・ステージング環境向けパスワードゲート -- 共有シークレットによる代替手段。事前に許可リストへ登録できない社外の閲覧者には、いまでもこちらが正しい道具だ。

• CI 向けの Access サービストークン -- Playwright のスモークテストやヘルスチェックが、ログインのリダイレクトに阻まれずに Access で保護された URL を通過する方法。

• Pages Functions での認証 -- サードパーティ IdP のトークンを検証する方法と、アプリに一般公開のサインアップがある場合に取るべき道。

• HTTP-only Cookie セッション -- Access が意図的に提供しない、ユーザーごとのセッション層。

• Workers PR プレビュー -- worker の destination が覆うことになっている、プレビューエイリアスの URL。

• Cloudflare セットアップ -- このページに出てくる権限をどれ 1 つ必要としない、デプロイ用トークン。