Turnstile は、ウェブサイトのフォームをボットから保護します。処理は 2 段階です。JavaScript ウィジェットが訪問者のブラウザーでチャレンジを実行してトークンを発行し、サーバーがそのトークンを Cloudflare へ送って正当性を確認します。このガイドでは、両方の手順を設定します。
開始する前に、次が必要です。
- Cloudflare アカウント
- 保護するウェブサイトまたはウェブアプリケーション
- HTML と、利用するサーバー側言語の基本知識
Turnstile ウィジェットは、ウェブページに埋め込んだ Turnstile のインスタンスです。各ウィジェットには、サイトキー（HTML に置く公開識別子）と、シークレットキー（サーバーがトークン検証に使う非公開の認証情報）があります。
各ウィジェットには、一意の sitekey とシークレットキーのペア、および設定オプションがあります。
| コンポーネント | 説明 |
|---|---|
| sitekey | サイト上で Turnstile ウィジェットを呼び出す公開鍵です。 |
| シークレットキー | サーバー側のトークン検証に使う秘密鍵です。 |
| 設定 | モード、ホスト名、外観設定、その他のオプションです。 |
Turnstile の導入には、連携する 2 つの必須コンポーネントがあります。
-
クライアント側: ウィジェットを埋め込む
ウェブページに Turnstile ウィジェットを追加し、訪問者にチャレンジを出してトークンを生成します。トークンは、訪問者がチャレンジを完了したときに生成される文字列です（最大 2,048 文字）。
-
サーバー側: トークンを検証する
トークンを Cloudflare の Siteverify API（Turnstile トークンを検証するエンドポイント）へ送り、改ざんされていない本物であることを確認します。
Turnstile は独立したサービスとして設計されています。Cloudflare ネットワークでプロキシしているかどうかに関係なく、任意のウェブサイトで使えます。マルチクラウド、オンプレミス、他の CDN を使うサイトでも柔軟に導入できます。クライアント側ウィジェットとサーバー側検証は、それぞれ自己完結しています。
ウェブサイトへの導入手順は、下記の 実装 を参照してください。
次の手順で Turnstile を導入します。
まず Turnstile ウィジェットを作成し、サイトキーとシークレットキーを取得します。
導入方法を選びます。
Cloudflare ダッシュボード
API
Terraform
ウェブページのフォームやアプリケーションに Turnstile ウィジェットを追加します。
暗黙的レンダリングと明示的レンダリングの詳細は、ウィジェットを埋め込む を参照してください。
ウィジェットが生成したトークンを確認するため、サーバー側検証を実装します。
適切なトークン検証で実装を保護するには、トークンを検証する を参照してください。
モバイルアプリケーションと WebView の実装では、特別な考慮が必要です。
モバイルアプリケーション連携の詳細は、モバイル実装 を参照してください。
現在 reCAPTCHA、hCaptcha、または他の CAPTCHA サービスを使っている場合、Turnstile は差し替え可能な代替です。既存スクリプトを置いている場所に、Turnstile のスクリプトをコピー＆ペーストできます。
他の CAPTCHA サービスからの移行手順は、移行 を参照してください。
-
サーバー側での検証は必須です。Turnstile トークンは Siteverify API で必ず検証してください。Turnstile トークンは無効、期限切れ、またはすでに使用済みの場合があります。トークンを検証しないと、実装に重大な脆弱性が残ります。Turnstile の設定を完了するには、Siteverify を呼び出す必要があります。呼び出さないと設定は不完全なままとなり、Turnstile Analytics でメトリクスを確認したときにトークン検証がゼロになります。
-
トークンは 300 秒（5 分）で期限切れになります。各トークンは 1 回だけ検証できます。期限切れまたは使用済みのトークンは、新しいチャレンジに置き換える必要があります。
- シークレットキーを保護します。クライアント側コードにシークレットキーを置かないでください。
- キーを定期的にローテーションします。API またはダッシュボードで、シークレットキーを定期的にローテーションします。
- ホスト名を制限します。管理下のドメインでのみウィジェットを許可します。
- 利用状況を監視します。分析で異常なパターンを検出します。
- わかりやすい名前を使います。用途に応じて「ログインフォーム」や「お問い合わせページ」などと名付けます。
- 環境を分けます。開発、ステージング、本番で別のウィジェットを使います。
- どのウィジェットをどの場所で使っているかを記録します。
- Terraform を使う場合は、ウィジェット設定をバージョン管理に保存します。