cloudflare-zero-trust-access

Cloudflare Zero Trust Access スキル

実績のあるパターンとテンプレートを使用して、Cloudflare Workers アプリケーションに Cloudflare Zero Trust Access 認証を統合します。

---

概要

このスキルでは、Cloudflare Access の完全な統合パターンを提供し、独自の認証インフラストラクチャを管理することなく、Workers でアプリケーションレベルの認証を有効にします。

Cloudflare Access とは？ Cloudflare Access は、アプリケーションの前段に配置される Zero Trust 認証です。ユーザーが Worker に到達する前にユーザーを検証します。認証後、Access は Worker が検証する JWT トークンを発行します。

主なメリット：

• 管理が必要な認証インフラストラクチャが不要
• ID プロバイダー（Azure AD、Google、Okta、GitHub）と統合
• マシン間認証用のサービス トークン
• MFA とセッション管理を標準搭載
• 包括的な監査ログ

---

このスキルを使用するタイミング

次の内容を含むタスクで、このスキルを使用します。

• 認証：Worker ルートの保護、管理者ダッシュボードのセキュリティ保護、API 認証
• アクセス制御：ロールベースのアクセス制御（RBAC）、グループベースの権限、地域制限
• サービス認証：Worker API を呼び出すバックエンドサービス、CI/CD パイプライン、cron ジョブ
• マルチテナント：組織レベルの認証を備えた SaaS アプリ
• CORS + 認証：保護された API を呼び出すシングルページアプリケーション

トリガーとなるキーワード： cloudflare access、zero trust、access authentication、JWT validation、service tokens、cloudflare auth、hono access、workers authentication、protect worker routes、admin authentication

---

統合パターン

📖 Cloudflare Access を初めて使用しますか？ references/quick-start.md を読み込み、手順に沿ってセットアップしてください（15～20 分）。

パターン 1：Hono ミドルウェア（推奨）

@hono/cloudflare-access を使用して、Access を 1 行で統合します。

使用するタイミング：

• Hono フレームワークで構築する場合
• 迅速かつ本番環境ですぐに使えるセットアップが必要な場合
• JWT の自動検証とキーのキャッシュを利用したい場合

テンプレート：templates/hono-basic-setup.ts

セットアップ：

import { Hono } from 'hono'
import { cloudflareAccess } from '@hono/cloudflare-access'

const app = new Hono<{ Bindings: Env }>()

// Public routes
app.get('/', (c) => c.text('Public page'))

// Protected routes
app.use(
  '/admin/*',
  cloudflareAccess({
    domain: (c) => c.env.ACCESS_TEAM_DOMAIN,
  })
)

app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.text(`Welcome, ${email}!`)
})

設定（wrangler.jsonc）：

{
  "vars": {
    "ACCESS_TEAM_DOMAIN": "your-team.cloudflareaccess.com",
    "ACCESS_AUD": "your-app-aud-tag"
  }
}

メリット：

• ✅ JWT を自動検証
• ✅ 公開鍵をキャッシュ（TTL は 1 時間）
• ✅ TypeScript による型安全性
• ✅ 本番環境での使用実績があり、メンテナンスされています

---

パターン 2：手動での JWT 検証

使用するタイミング：Hono を使用せず、カスタム検証ロジックが必要な場合

テンプレート：templates/jwt-validation-manual.ts（約 100 行、Web Crypto API を使用）

---

パターン 3：サービストークン認証

使用するタイミング：CI/CD パイプライン、バックエンドサービス、cron ジョブ（対話型ログインなし）

クライアント：CF-Access-Client-Id と CF-Access-Client-Secret ヘッダーを送信します

サーバー：同じミドルウェアで両方に対応します。!payload.email && payload.common_name で判別します

📄 詳細ガイド：references/service-tokens-guide.md

---

パターン 4：CORS + Access

使用するタイミング：保護された API を呼び出す SPA（React/Vue/Angular）

⚠️ 重要：CORS ミドルウェアは Access ミドルウェアより前に配置する必要があります！

// ✅ CORRECT ORDER
app.use('*', cors({ origin: 'https://app.example.com', credentials: true }))
app.use('/api/*', cloudflareAccess({ domain: (c) => c.env.ACCESS_TEAM_DOMAIN }))

理由：OPTIONS プリフライトリクエストには認証ヘッダーがないため、Access によって 401 でブロックされます

📄 詳細なパターン：templates/cors-access.ts

---

パターン 5：マルチテナント

使用するタイミング：組織ごとの認証を備えた SaaS、ホワイトラベルアプリ

アーキテクチャ：D1/KV にテナント設定を保存 → リクエストごとにミドルウェアを動的に設定

📄 詳細なパターン：templates/multi-tenant.ts および references/use-cases.md

---

防止できる一般的なエラー

このスキルでは、記録されている 8 件のエラーを防止します。詳細は references/common-errors.md を参照してください。

エラー #1：CORS プリフライトのブロック（45 分の節約）

問題：OPTIONS リクエストが 401 を返し、CORS が機能しなくなります

解決策：CORS ミドルウェアを Access ミドルウェアより前に配置します

// ✅ Correct
app.use('*', cors())
app.use('/api/*', cloudflareAccess({ domain: '...' }))

---

エラー #2：JWT ヘッダーがない（30 分の節約）

問題：リクエストが Access を経由せず、JWT ヘッダーがありません

解決策：*.workers.dev に直接アクセスせず、Access URL 経由で Worker にアクセスします

✅ https://team.cloudflareaccess.com/...
❌ https://worker.workers.dev

---

エラー #3：チーム名が無効（15 分の節約）

問題：チーム名がハードコードされているか、誤っているため、「Invalid issuer」が発生します

解決策：環境変数を使用します

// ✅ Correct
cloudflareAccess({ domain: (c) => c.env.ACCESS_TEAM_DOMAIN })

// ❌ Wrong
cloudflareAccess({ domain: 'my-team.cloudflareaccess.com' })

---

エラー #4-8（クイックリファレンス）

#	エラー	解決策
4	キ​​ーキャッシュの競合状態	@hono/cloudflare-access を使用します（自動でキャッシュします）
5	サービストークンのヘッダーが誤っている	CF-Access-Client-Id/Secret を使用します（Authorization ではありません）
6	トークンの有効期限切れ（1 時間後に 401）	適切に処理し、ログインにリダイレクトします
7	ポリシーの重複	最も具体的なパスを使用します
8	開発環境と本番環境の不一致	環境ごとの設定を使用します

📄 エラーの詳細：references/common-errors.md（実装ごとに約 2.5 時間を節約）

---

テンプレート

テンプレート	目的
hono-basic-setup.ts	標準的な Hono と Access の統合
jwt-validation-manual.ts	Web Crypto を使用した手動 JWT 検証
service-token-auth.ts	サービストークンのパターン
cors-access.ts	CORS と Access（正しい順序）
multi-tenant.ts	マルチテナントアーキテクチャ
wrangler.jsonc	Wrangler の完全な設定
.env.example	環境変数のテンプレート
types.ts	TypeScript の型定義

スクリプト

スクリプト	使用方法
test-access-jwt.sh	./test-access-jwt.sh <jwt-token> - JWT のデコードと検証
create-service-token.sh	./create-service-token.sh [name] - サービストークンの設定ガイド

---

ユースケース

ユースケース	テンプレート	要点
管理者ダッシュボード	hono-basic-setup.ts	メールドメインポリシー
API 認証	hono-basic-setup.ts	ユーザーとサービスの混合ポリシー
SPA と API	cors-access.ts	Access の前に CORS を設定します！
CI/CD パイプライン	service-token-auth.ts	シークレットにサービストークンを設定
マルチテナント SaaS	multi-tenant.ts	D1 のテナント設定

📄 ユースケースの詳細：references/use-cases.md

---

リファレンスを読み込むタイミング

リファレンスファイル	読み込むタイミング
references/quick-start.md	新規ユーザー向けの手順に沿ったセットアップ、初回の統合時
references/common-errors.md	認証の問題のデバッグ、防止パターンの確認時（8 件すべてのエラーを含む）
references/jwt-payload-structure.md	JWT クレームへのアクセス時、ユーザートークンとサービストークンの確認時
references/service-tokens-guide.md	マシン間認証の設定時
references/access-policy-setup.md	ダッシュボードの設定、ポリシーの作成時
references/use-cases.md	特定のシナリオにおける実装の詳細を確認する時
references/value-proposition.md	トークン効率の指標、ワークフローのガイダンス、本番環境での検証を確認する時

---

パッケージのバージョン

パッケージ	バージョン
@hono/cloudflare-access	0.3.1
hono	4.12.12
@cloudflare/workers-types	4.20260408.0

検証済み：2025-12-14 | トークン節約率：約 58% | 本番環境でのテスト済み：✅

---

使用しない場合

このスキルは Cloudflare Access を使用する Cloudflare Workers 向けです。次の場合には使用しないでください。

• ❌ Cloudflare Pages（代わりに @cloudflare/pages-plugin-cloudflare-access を使用してください）
• ❌ Cloudflare 以外のプラットフォーム
• ❌ カスタム JWT 認証（Access ではないもの）
• ❌ Auth.js またはその他の認証ライブラリ
• ❌ セルフホスト型の認証

これらの場合は、適切なスキルまたはライブラリを使用してください。

---

追加リソース

Cloudflare のドキュメント：

• Access の概要
• JWT の検証
• サービストークン

パッケージ：

• @hono/cloudflare-access
• Hono フレームワーク

ダッシュボード：

• Zero Trust ダッシュボード

---

スキルのバージョン：1.0.0 最終更新日：2025-10-28 防止したエラー数：8 トークン節約率：58% 時間の節約：2.5 時間 本番環境でのテスト済み：✅