BLOG

Cloudflare Turnstileを使う

Written by ogoe

INDEX

Cloudflare Turnstile（クラウドフレア ターンスタイル）は、ユーザーがボットではないことを確認するためのセキュリティ機能です。
Google Cloud Fraud Defense（reCAPTCHA）の代わりとして使用することができます。

Turnstileはブラウザ環境やユーザーの振る舞いをもとに検証を行い、ボットではないことを確認します。
ユーザーに謎の文字列を入力させたり、パズルを解かせたりすることはありません。
2026年現在、無料プランがありアカウント登録をするだけで簡単に利用することができます。

ウィジェット表示までの流れ

  1. Cloudflareアカウントの作成
  2. ダッシュボードからのウィジェット設定
  3. フロントにウィジェットを表示

Cloudflareアカウントの作成

Turnstileを利用するにはCloudflareアカウントが必要です。
Cloudflare公式サイトからアカウントを作成します。

ウィジェットを追加する

フロントにウィジェットを追加するための設定を行います。
Cloudflareアカウント作成後、ダッシュボードからTurnstile ウィジェット画面に移動します。
サイドバー > 保護と接続 > アプリケーション セキュリティ > Turnstile
Turnstile ウィジェット画面に移動したら「ウィジェットを手動で追加」をクリックします。

ウィジェットを追加するためのフォームに移動するため必要な情報を入力します。

ウィジェット名

プロジェクト名などわかりやすい名前を入力

ホスト名管理

ウィジェットを使用するドメインを入力

ウィジェット モード

ウィジェットの表示・動作方法を選択

検証済み訪問者の今後のセキュリティルールチャレンジをスキップする

Turnstileがボットではないことを判定した後、同じユーザーが再度訪問した際にセキュリティルールのチャレンジをスキップするかどうかを選択

入力完了後、「作成」をクリックすることでサイトキー、シークレットキーが発行されます。
フロントにウィジェットを表示する際に使用するので控えておきます。
ウィジェットの追加はこれにて完了です。

ウィジェットの追加後、各キーはいつでも確認できるので安心です。

ウィジェットの仕様について

ウィジェットには埋め込み方法や外観、コールバックなどのオプションがあります。
公式ドキュメントから個人的に使用度が高そうな項目を抜粋して解説します。

ウィジェットの種類

ウィジェットには以下の3種類があります。
基本的には公式が推奨する管理を使うのががよさそうです。
リスクレベルが水準を超えた際、管理は、ユーザーにチェックボックスの入力を要求することで、ボットではないことを確認し通過させることができます。
非インタラクティブと非表示は、ユーザーの操作を要求しないため回復手段がなくブロックされてしまいます。

ウィジェットの種類はダッシュボードからいつでも変更することができます。

管理

（Managed）

ユーザーの行動や環境に基づいて判定

（チェックボックスの入力を要求することがある） [推奨]

非インタラクティブ

（Non-interactive）

ウェジェットを表示するがユーザーの操作を要求せずに判定

非表示

（Invisible）

ウィジェットはユーザーに表示されずバックグラウンドで判定

レンダリング方法

フロントに表示する際の記述方法です。
暗黙的レンダリングまたは明示的レンダリングを使用することができます。

暗黙的レンダリング

.cf-turnstileクラスを持つ要素を記述するだけで、ページ読み込み時に自動でウィジェットをレンダリングします。
オプションはdata属性から指定することができます。
静的サイトでの使用や、ページ読み込み時にウィジェットを即時表示したい場合に適しています。

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" defer></script>

明示的レンダリング

JavaScriptの関数を使用して、手動でウィジェットをレンダリングします。
オプションは関数の引数から指定することができます。
動的サイトやSPA、または特定条件下でウィジェットを表示したい場合に適しています。

<div id="my-widget"></div>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    turnstile.render('#my-widget', {
      sitekey: '<YOUR-SITE-KEY>',
    });
  });
</script>

ウィジェットのサイズ

オプション名：size
Managed（管理）またはNon-interactive（非インタラクティブ）を使用する場合、ウィジェットのサイズを変更することができます。

normal

標準サイズのウィジェット（300 * 65）[デフォルト]

flexible

幅を親要素の幅に合わせて自動調整するウィジェット（100%/min300 * 65）

compact

コンパクトサイズのウィジェット（150 * 140）

記述例

<!-- 暗黙的レンダリング -->
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="normal"></div>

<!-- 明示的レンダリング -->
<script>
  turnstile.render('#my-widget', {
    sitekey: '<YOUR-SITE-KEY>',
    size: 'normal',
  });
</script>

テーマオプション

オプション名：theme
ウィジェットの外観を変更することができます。主に色です。

auto

ユーザーのOSやブラウザのテーマ設定に基づいて自動的に`light`または`dark`を決定 [デフォルト, 推奨]

light

明るい色使いのウィジェット

dark

暗い色使いのウィジェット

記述例

<!-- 暗黙的レンダリング -->
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="auto"></div>

<!-- 明示的レンダリング -->
<script>
  turnstile.render('#my-widget', {
    sitekey: '<YOUR-SITE-KEY>',
    theme: 'auto',
  });
</script>

コールバック

ウィジェットにコールバック関数を登録することができます。
チャレンジ成功時にトークンを受け取ったり、エラー発生時の処理を定義するなど。

callback

チャレンジが正常に完了した際にトリガーされる

error-callback

チャレンジ中にエラーが発生した場合にトリガーされる

expired-callback

トークンの有効期限が切れたとき（タイムアウト前）にトリガーされる

timeout-callback

インタラクティブなチャレンジのタイムアウト時にトリガーされる

記述例

<!-- 暗黙的レンダリング -->
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-callback="onSuccess"></div>
<script>
  function onSuccess(token) {
    console.log(`Challenge Success: ${token}`);
  }
</script>

<!-- 明示的レンダリング -->
<script>
  turnstile.render('#widget-container', {
    sitekey: '<YOUR-SITE-KEY>',
    callback: (token) => {
      console.log(`Challenge Success: ${token}`);
    },
  });
</script>

リファレンス

その他のオプションやAPIについてのリファレンスは公式ドキュメントを参照ください。
ウィジェットの設定 · Cloudflare Turnstile ドキュメント

ダミーキー

サイトキーとシークレットキーそれぞれのダミーキーが提供されており、実装をテストすることができます。

テストサイトキー

サイトキー

結果

ウィジェットの種類

1x00000000000000000000AA

必ず合格する

管理, 非インタラクティブ

2x00000000000000000000AB

常に失敗する

管理, 非インタラクティブ

1x00000000000000000000BB

必ず合格する

非表示

2x00000000000000000000BB

常に失敗する

非表示

3x00000000000000000000FF

フォースインタラクティブチャレンジ

管理, 非インタラクティブ

テストシークレットキー

シークレットキー

結果

1x0000000000000000000000000000000AA

常に検証に合格する

2x0000000000000000000000000000000AA

常に検証に失敗する

3x0000000000000000000000000000000AA

「トークンは既に消費されている」という旨のエラーを返す

WordPressのContact Form 7にTurnstileを組み込む

Contact Form 7 6.1からTurnstileのインテグレーションが実装されました。
WordPressのフォームプラグインであるContact Form 7にTurnstileを組み込むことができます。
なおContact Form 7の作者はTurnstileの使用を推奨しています。

以下公式ドキュメントから引用

Turnstile は Cloudflare によるスマートな CAPTCHA 代替サービスです。Contact Form 7 は Turnstile とのインテグレーションモジュールを提供し、あなたのフォームをスパムボットから守ります。Google reCAPTCHA とは異なり Turnstile は無料で利用できます。reCAPTCHA を使うべき理由が特にないのであれば Turnstile を選択してください。

バージョン

  • WordPress 7.0
  • Contact Form 7 6.1.6

インテグレーションの追加

WordPressにContact Form 7をインストールして有効化した後、Contact Form 7のインテグレーション画面に移動します。
Turnstileのパネルから「インテグレーションのセットアップ」をクリックします。
サイドバー > お問い合わせ > インテグレーション

ウィジェットを追加した際に発行されたサイトキー、シークレットキーを入力して「変更を保存」をクリックします。

ウィジェットの組み込み

インテグレーションを追加するだけでウィジェットがフォームの先頭に自動で配置されます。
ウィジェットの位置を移動させたい場合は、[turnstile]タグを使用して任意の位置に配置することができます。

なお、[turnstile]タグには一部のオプションを指定することができます。

  • action : data-action属性値
  • appearance : data-appearance属性値
  • language : data-language属性値
  • size : data-size属性値
  • tabindex : data-tabindex属性値
  • theme : data-theme属性値

[turnstile size:compact theme:dark]を記述した場合の表示

参考

概要 · Cloudflare Turnstile ドキュメント
Cloudflare Turnstile インテグレーション | Contact Form 7 [日本語]

PICK UP