cloudflare-zero-trust-access

Cloudflare Zero Trust Access スキル

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

---

概要

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

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

主なメリット：

• 認証インフラストラクチャの保守が不要
• アイデンティティプロバイダー（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

---

統合パターン

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

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

使用するタイミング：

• 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 検証

Web Crypto API を使用して、カスタム検証ロジックを実装します。

使用するタイミング：

• Hono フレームワークを使用していない場合
• 標準的なチェックを超えるカスタム検証が必要な場合
• JWT 検証を完全に制御したい場合

テンプレート：templates/jwt-validation-manual.ts

主な関数：

// Validate JWT signature and claims
async function validateAccessJWT(
  token: string,
  env: Env
): Promise<AccessJWTPayload> {
  // 1. Decode header to get kid
  // 2. Fetch public keys (with caching)
  // 3. Verify signature using Web Crypto API
  // 4. Validate aud, exp, iss
  // 5. Return payload
}

複雑さ：約 100 行 依存関係：なし（Web Crypto API を使用）

---

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

マシン間認証にはサービス トークンを使用します。

使用するタイミング：

• Worker API を呼び出すバックエンドサービス
• CI/CD パイプライン
• 自動化スクリプトや cron ジョブ
• 対話型ログインが不要な場合

テンプレート：templates/service-token-auth.ts

クライアント側（リクエストの送信）：

const response = await fetch('https://api.example.com/data', {
  headers: {
    'CF-Access-Client-Id': env.SERVICE_TOKEN_ID,
    'CF-Access-Client-Secret': env.SERVICE_TOKEN_SECRET,
  },
})

サーバー側（Worker）：

// Same validation as user JWTs - middleware handles both
app.use('/api/*', cloudflareAccess({
  domain: (c) => c.env.ACCESS_TEAM_DOMAIN
}))

app.get('/api/data', (c) => {
  const payload = c.get('accessPayload')

  // Detect service token vs user
  const isService = !payload.email && payload.common_name

  return c.json({
    authenticated_by: isService ? 'service-token' : 'user',
    identifier: payload.email || payload.common_name,
  })
})

セットアップガイド：references/service-tokens-guide.md

---

パターン 4：CORS + Access

Access 認証を使用して、クロスオリジンリクエストを処理します。

使用するタイミング：

• 保護された API を呼び出す SPA（React/Vue/Angular）
• フロントエンドと API が異なるドメインにある場合
• クロスオリジンの認証済みリクエスト

テンプレート：templates/cors-access.ts

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

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

// ✅ CORRECT ORDER
app.use('*', cors({
  origin: 'https://app.example.com',
  credentials: true, // Allow cookies
}))

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

// ❌ WRONG ORDER - WILL FAIL!
// Access blocks OPTIONS preflight requests

理由：OPTIONS プリフライトリクエストには認証ヘッダーが含まれません。Access が先に実行されると、401 でブロックされます。

フロントエンド：

fetch('https://api.example.com/api/data', {
  credentials: 'include', // ← Critical!
  method: 'POST',
})

---

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

テナント／組織ごとに異なる Access 設定を適用します。

使用するタイミング：

• 組織レベルの認証を備えた SaaS
• 顧客ごとに個別の Access チームがある場合
• ホワイトラベルアプリケーション

テンプレート：templates/multi-tenant.ts

アーキテクチャ：

• テナント設定を D1 または KV に保存
• テナント ID に基づく動的ミドルウェア
• サブドメイン、パス、またはヘッダーからテナント ID を取得

例：

// Subdomain-based: tenant1.example.com, tenant2.example.com
app.use('/app/*', async (c, next) => {
  const tenantId = getTenantFromSubdomain(c.req.url)
  const tenant = await getTenantConfig(tenantId, c.env.DB)

  // Apply tenant-specific Access
  return cloudflareAccess({
    domain: tenant.access_team_domain
  })(c, next)
})

---

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

このスキルでは、文書化された 8 件のエラーを防止できます。詳細については、references/common-errors.md を参照してください。

エラー #1：CORS のプリフライトがブロックされる（45 分短縮）

問題：OPTIONS リクエストが 401 を返し、CORS が機能しません。

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

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

---

エラー #2：JWT ヘッダーがない（30 分短縮）

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

解決策：Access Worker には、直接 *.workers.dev にアクセスするのではなく、Access URL 経由でアクセスします。

✅ 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：キーキャッシュの競合（20 分短縮）

問題：最初のリクエストは失敗しますが、以降のリクエストは成功します。

解決策：@hono/cloudflare-access を使用します（キャッシュを自動的に処理します）。

---

エラー #5：サービストークンのヘッダー（10 分短縮）

問題：ヘッダー名が正しくないため、トークンが機能しません。

解決策：正確なヘッダー名を使用します。

// ✅ Correct
'CF-Access-Client-Id': '...'
'CF-Access-Client-Secret': '...'

// ❌ Wrong
'Authorization': 'Bearer ...'

---

エラー #6：トークンの有効期限切れ（10 分短縮）

問題：ユーザーが 1 時間後に突然 401 を受け取ります。

解決策：適切に処理し、ログインにリダイレクトします。

if (error.message.includes('expired')) {
  return c.json({ error: 'Session expired', code: 'TOKEN_EXPIRED' }, 401)
}

---

エラー #7：複数のポリシー（30 分短縮）

問題：Access アプリケーションのパスが重複していると、競合が発生します。

解決策：最も具体的なパスを使用し、重複を避けます。

---

エラー #8：開発環境と本番環境の不一致（15 分短縮）

問題：開発環境ではコードが動作しますが、本番環境では失敗します。

解決策：環境ごとの設定を使用します。

{
  "env": {
    "dev": {
      "vars": { "ACCESS_TEAM_DOMAIN": "dev-team.cloudflareaccess.com" }
    },
    "production": {
      "vars": { "ACCESS_TEAM_DOMAIN": "prod-team.cloudflareaccess.com" }
    }
  }
}

合計短縮時間：実装ごとに約 2.5 時間

---

テンプレート

コアテンプレート

1. hono-basic-setup.ts - Hono と Access の標準的な統合

   • パブリックルートと保護されたルート
   • ユーザー情報へのアクセス
   • エラー処理

2. jwt-validation-manual.ts - 手動での JWT 検証

   • Web Crypto API の使用
   • キーのキャッシュ
   • 完全な検証ロジック

3. service-token-auth.ts - サービストークンのパターン

   • クライアントとサーバーの例
   • サービスとユーザーの判別
   • ベストプラクティス

4. cors-access.ts - CORS と Access の統合

   • 正しいミドルウェアの順序
   • フロントエンドの例（fetch、axios）
   • トラブルシューティングガイド

5. multi-tenant.ts - マルチテナントアーキテクチャ

   • サブドメイン、パス、ヘッダーの各方式
   • D1 テナント設定
   • 動的ミドルウェア

設定テンプレート

6. wrangler.jsonc - Wrangler の完全な設定

   • 環境変数
   • バインディング（D1、KV、R2）
   • 開発／ステージング／本番環境

7. .env.example - 環境変数のテンプレート

   • 必須：ACCESS_TEAM_DOMAIN、ACCESS_AUD
   • 任意：サービストークン、CORS 設定
   • セットアップ手順

8. types.ts - TypeScript の型定義

   • AccessJWTPayload インターフェース
   • ServiceTokenJWTPayload インターフェース
   • 型ガードとヘルパー

---

リファレンスドキュメント

references/ にある包括的なガイド：

1. common-errors.md（約 800 語）

   • 8 つのエラーすべてと解決策
   • エラー → 症状 → 原因 → 解決策 → 予防
   • ソースリンクと短縮時間

2. jwt-payload-structure.md（約 1,200 語）

   • JWT フィールドの完全なリファレンス
   • ユーザートークンとサービストークンの違い
   • 型定義と例

3. service-tokens-guide.md（約 1,100 語）

   • サービストークンの作成
   • ポリシーへの追加
   • ユースケース（CI/CD、マイクロサービス、cron）
   • ローテーションのベストプラクティス

4. access-policy-setup.md（約 1,400 語）

   • ダッシュボードの設定手順
   • ポリシーの例
   • ID プロバイダーの設定
   • テストとトラブルシューティング

---

ヘルパースクリプト

scripts/ にあります：

1. test-access-jwt.sh - JWT テストツール

   • JWT のヘッダーとペイロードをデコード
   • 公開鍵を取得
   • 署名とクレームを検証
   • 使用方法：./test-access-jwt.sh <jwt-token>

2. create-service-token.sh - サービストークンのセットアップガイド

   • 対話形式のセットアップ手順
   • コード例（curl、Node.js、Python、GitHub Actions）
   • ベストプラクティスのチェックリスト
   • 使用方法：./create-service-token.sh [token-name]

---

クイックスタート

1. パッケージをインストールする

npm install hono @hono/cloudflare-access

2. アクセスを設定する

ダッシュボード:

1. Zero Trust > Access > Applications に移動します
2. Worker ドメイン用のアプリケーションを作成します
3. ポリシーを作成します（例：「@company.com で終わるメールアドレス」）
4. Application Audience（AUD）タグをコピーします

wrangler.jsonc:

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

3. Worker に追加する

templates/hono-basic-setup.ts を出発点として使用します。

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

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

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

app.get('/admin/dashboard', (c) => {
  const { email } = c.get('accessPayload')
  return c.json({ email })
})

export default app

4. デプロイしてテストする

npx wrangler deploy

アクセス先: https://your-worker.example.com/admin/dashboard

想定される動作: Access のログイン画面にリダイレクトされ、認証後にダッシュボードへ戻ります。

---

ユースケース

管理者ダッシュボードの保護

要件: メール認証で管理者向けルートを保護します

テンプレート: hono-basic-setup.ts

ポリシー: @company.com で終わるメールアドレス

---

API 認証

要件: API を保護し、公開ページへのアクセスを許可します

テンプレート: hono-basic-setup.ts + 個別のルート

ポリシー: サービストークン + 従業員のメールアドレス

---

SPA + 保護された API

要件: 認証済み API を呼び出す React アプリ

テンプレート: cors-access.ts

重要: Access より前に CORS ミドルウェアを配置します

---

CI/CD パイプライン

要件: GitHub Actions から Worker API を呼び出します

テンプレート: service-token-auth.ts

設定: GitHub Secrets にサービストークンを保存します

---

マルチテナント SaaS

要件: 組織ごとに異なる Access を設定します

テンプレート: multi-tenant.ts

アーキテクチャ: D1 にテナント設定を保存し、ミドルウェアを動的に適用します

---

パッケージ情報

パッケージ	バージョン	用途
@hono/cloudflare-access	0.3.1	Hono ミドルウェア（推奨）
hono	4.10.3	Web フレームワーク
@cloudflare/workers-types	4.20251014.0	TypeScript 型定義

検証日: 2025-10-28

Node.js の依存関係なし: すべてのパッケージが Web 標準 API を使用しており、Workers ランタイムと完全に互換性があります。

---

トークン効率

スキルなし: 約 5,550 トークン

• Cloudflare ドキュメント: 2,500 トークン
• ライブラリのドキュメント: 450 トークン
• GitHub の課題の調査: 1,000 トークン
• 手動での実装: 1,600 トークン

スキルあり: 約 2,300 トークン

• SKILL.md: 1,500 トークン
• テンプレート: 500 トークン
• クイック設定: 300 トークン

削減量: 3,250 トークン（約 58%）

---

本番環境でのテスト

ライブラリ: @hono/cloudflare-access は積極的にメンテナンスされています ダウンロード数: 約 3,000 件/週 GitHub: Hono ミドルウェアコレクションの一部（スター 10,000 件以上）

本番環境での使用: 商用プロジェクトで動作することを確認済みです。

---

ワークフロー

ユーザーから Access の統合を依頼された場合:

1. パターンを評価する: どの統合パターンが適していますか？（Hono ミドルウェア、手動、サービストークン、CORS、マルチテナント）

2. テンプレートを確認する: templates/ から該当するテンプレートをコピーします

3. 環境を設定する: wrangler.jsonc で ACCESS_TEAM_DOMAIN と ACCESS_AUD を設定します

4. ダッシュボードを設定する: Access ポリシーの作成手順をユーザーに案内します（references/access-policy-setup.md を使用）

5. エラーを防ぐ: references/common-errors.md の解決策を適用します

6. テストする: デプロイして認証フローを確認します

---

使用しない場合

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

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

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

---

Additional Resources

Cloudflare Documentation:

• Access Overview
• JWT Validation
• Service Tokens

Packages:

• @hono/cloudflare-access
• Hono Framework

Dashboard:

• Zero Trust Dashboard

---

Skill Version: 1.0.0 Last Updated: 2025-10-28 Errors Prevented: 8 Token Savings: 58% Time Savings: 2.5 hours Production Tested: ✅