Turnstile

解決する課題

• 会員登録・ログイン・問い合わせフォームへの自動化されたスパム送信やクレデンシャルスタッフィングを防ぎたい
• 従来型CAPTCHAの画像選択やゆがんだ文字入力がユーザー体験を損ない、離脱率を上げてしまっている
• 特定ベンダーの検証サービスに縛られず、サイトを問わず埋め込めるボット対策を導入したい
• ボット判定のために個人情報や広告目的のトラッキングを増やしたくない
• モバイル・低速回線でも軽量に動作する検証手段が欲しい

主要概念と用語

• ウィジェット（Widget）: 保護対象のページに埋め込む検証部品。多くの場合、目に見えるチャレンジを出さずに裏側で完了する
• サイトキー（Site Key）: フロントエンドに埋め込む公開用の識別子。ドメインごとに発行する
• シークレットキー（Secret Key）: サーバー側だけが保持する秘密の鍵。siteverifyの呼び出しに使う
• トークン（Response Token）: ウィジェットの検証完了後にクライアントへ発行される一時的な文字列。フォーム送信時にサーバーへ渡す
• siteverify: サーバーからトークンの正当性を検証するためのAPIエンドポイント。真偽と付随情報を返す
• マネージドチャレンジ（Managed Challenge）: リスクに応じてCloudflareが自動的に検証の強度を調整するモード。多くの場合ユーザーに追加操作を求めない
• 非対話モード（Non-Interactive）／見えないモード（Invisible）: 画面上のチェックボックス操作すら不要にする動作モード
• Widget Mode: 埋め込み時の表示形式（マネージド／非対話型／見えない型）を指定する設定
• プレクリアランス（Pre-Clearance）: 一度検証をパスしたクライアントに対し、一定時間チャレンジを再提示しない仕組み

仕様・制限・クォータ

• ドメインごとにサイトキーとシークレットキーのペアを発行し、キーはサイト単位で管理する
• トークンには有効期限があり、発行から一定時間内にサーバー側で検証を完了させる必要がある
• 同一トークンをsiteverifyで検証できるのは一度きりで、再利用（リプレイ）はできない
• 開発・テスト用に、常に成功または常に失敗を返すテスト用の共有キーが公式に用意されている
• ウィジェットはJavaScriptの読み込みを伴うため、厳格なコンテンツセキュリティポリシー（CSP）を敷いている場合は許可設定が必要になる
• 提供中の主要な機能は無料枠の範囲で利用でき、料金体系は変動するため契約時の最新情報を確認する

内部の仕組み

Turnstileは、ページに埋め込まれたウィジェットがブラウザ環境やネットワークの特徴、過去の挙動シグナルなどを裏側で複数の非対話的なチェックにかけ、多くの場合ユーザーに画像選択などの操作を要求せずに人間らしさを判定します。判定が難しい場合にのみ、軽量なチャレンジを追加で提示します。

検証が完了すると、ウィジェットは短命なレスポンストークンを発行し、フォームの隠しフィールドなどを通じてクライアントからサーバーへ送信されます。サーバーはこのトークンをシークレットキーとともにsiteverify APIへ送り、Cloudflare側でトークンの正当性・有効期限・重複利用の有無を検証します。

siteverifyは真偽値の判定結果に加えて、必要に応じてエラーコードやチャレンジのタイムスタンプなどの付随情報を返します。アプリケーションはこの結果を見て、フォーム送信やアカウント作成などの後続処理を許可するかどうかを決定します。判定はクライアント側の見た目の操作だけでなく、必ずサーバー側での検証を経て初めて信頼できる状態になります。

設計パターン / ベストプラクティス

• フォーム送信前に必ずサーバー側検証を挟む: トークンの検証が成功するまで、実際の登録処理やメール送信などの副作用を実行しない
• マネージドチャレンジを既定にする: 個別のモードを細かく作り込むより、リスクに応じて自動調整されるマネージドチャレンジを基本にすると運用の手間が減る
• 重要フォームごとにウィジェットを分離: ログイン・登録・パスワードリセットなど攻撃対象になりやすい画面ごとにサイトキーやウィジェット設置を検討する
• 失敗時のフォールバック導線を用意: ウィジェットの読み込みに失敗した場合でも、ユーザーが完全にブロックされないよう代替手段やエラーメッセージを設計する
• レート制限や既存のWAFルールと併用: Turnstile単体に頼らず、異常な送信頻度の検知や既存のセキュリティ機構と組み合わせて多層防御にする
• CSPやSRIなど既存のセキュリティヘッダーとの整合を確認: ウィジェットのスクリプト読み込み元を許可リストに追加し、他のセキュリティ設定を壊さないようにする

運用・監視

• ダッシュボードでウィジェットごとのチャレンジの発行数や成功率などの傾向を確認できる
• siteverify呼び出しのエラーコードをアプリケーションログに記録し、キーの設定ミスやトークン期限切れなどの原因を切り分けられるようにする
• 正規ユーザーからの問い合わせで「フォームが送信できない」といった声が増えた場合、ウィジェットの表示モードやCSP設定を見直す
• キー（サイトキー／シークレットキー）のローテーションや無効化はダッシュボードまたはAPIから行い、漏えい時に速やかに再発行できる体制を整えておく
• 本番導入前後でスパム送信数やアカウント作成の異常値を比較し、効果測定を行う

コスト

具体的な無料枠の範囲や上限は変わりやすいため、導入前に公式の料金・プランページで最新の内容を確認してください。一般的な用途では追加コストをかけずに導入できる位置づけのサービスです。

セキュリティ

• サーバー側検証の徹底: クライアント側の見た目の成功表示だけで判断せず、必ずsiteverifyでトークンを検証してから重要な処理を実行する
• シークレットキーの厳重な管理: シークレットキーはサーバー環境変数やシークレットストアで管理し、フロントエンドのコードや公開リポジトリに含めない
• トークンの使い回し防止: レスポンストークンは一度きりの利用を前提に設計されているため、アプリケーション側でも再送や使い回しを許容しない実装にする
• プライバシーへの配慮: 画像選択のような個人の識別性が高い操作を避け、必要最小限のシグナルで判定する設計思想を理解して運用する
• 多層防御の一部として位置づける: Turnstileは入口の選別を担うものであり、認可・レート制限・WAFなど他の防御層と組み合わせて初めて十分な保護になる

関連サービス・比較

同じくフォームやアプリケーションへの不正トラフィックを制御する仕組みとして、WAFのレート制限やBot Managementが関連サービスに当たります。Turnstileは主に「人間かどうかを入力操作の摩擦なく判定する」役割を担い、WAFやBot Managementはリクエスト全体のパターンやルールベースの制御を担う点で位置づけが異なります。

ハンズオン / CLI例

Turnstileのウィジェット作成や設定変更は主にダッシュボードまたはCloudflare APIから行います。wranglerで認証情報を確認したうえで、APIを直接呼び出す例を示します。

# wranglerでCloudflareアカウントへの認証状態を確認
wrangler whoami

# ウィジェット（サイトキー/シークレットキーのペア）を作成
curl -X POST "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/challenges/widgets" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "contact-form-widget",
    "domains": ["example.com"],
    "mode": "managed"
  }'

# 作成済みウィジェットの一覧を確認
curl -X GET "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/challenges/widgets" \
  -H "Authorization: Bearer ${CF_API_TOKEN}"

# サーバー側でクライアントから受け取ったトークンをsiteverifyへ送信して検証
curl -X POST "https://challenges.cloudflare.com/turnstile/v0/siteverify" \
  -H "Content-Type: application/json" \
  --data '{
    "secret": "'"${TURNSTILE_SECRET_KEY}"'",
    "response": "'"${CLIENT_RESPONSE_TOKEN}"'"
  }'