スコアベース・キーをウェブサイトにインストールする

このページでは、スコアベースのキーをチャレンジなしでウェブサイトにインストールする方法について説明します。スコアベースキーを使用すると、ユーザーに CAPTCHA チャレンジの解決を求めることなく、サイト全体に reCAPTCHA を含めることができます。

スコアベースキーをインストールしたら、評価を作成し、リクエストごとにスコアを取得する必要があります。このスコアに基づいて、ユーザーインタラクションのリスクレベルを把握し、適切なレスポンス（複数可）を構成できます。また、スコアベースキーは、新しい攻撃または対象にされていることを早期に警告するために bot アクティビティテレメトリーを収集できます。

reCAPTCHA のリスクモデルを向上させるには、サイトの各ページに reCAPTCHA を含めることをおすすめします。reCAPTCHA は、実際のユーザーや bot がさまざまなページやアクション間をどのように遷移するかを理解するのに役立ちます。

始める前に

reCAPTCHA 用に環境を準備します。
スコアベースキーを作成します。

あるいは、次のいずれかの手順で、既存のスコアベースのキーの ID をコピーできます。
- Google Cloud コンソールから既存のチェックボックスのキーの ID をコピーするには、次の操作を行います。
  1. [reCAPTCHA] ページに移動します。
    
    [reCAPTCHA] に移動
  2. reCAPTCHA キーのリストで、コピーするキーの上にポインタを置き、[] をクリックします。
- REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを使用します。
- gcloud CLI を使用して既存のキーの ID をコピーするには、gcloud recaptcha keys list コマンドを使用します。

キーをウェブサイトに配置する

reCAPTCHA は、サイト上でのインタラクションに関するコンテキストがある場合に最も効果的です。reCAPTCHA は、サイト上のインタラクションを調査するために、正当な動作と不正な動作の両方を監視します。

最適な結果を得るには、スコアベースキーをウェブサイトの次の場所にインストールします。

フォーム
アクション（ユーザーインタラクション）
すべてのウェブページのバックグラウンド

スコアベースキーはユーザーの作業を中断しないため、コンバージョンに影響を与えることなく、必要に応じてスコアベースキーを使用して reCAPTCHA を実行できます。

キーをフロントエンドへ統合する

reCAPTCHA による確認を追加する場所に応じて、適切なオプションを選択します。

ユーザーの操作に関する確認を追加する
HTML ボタンに reCAPTCHA を追加する

各オプションの例は、デモウェブサイトのソースコードをご覧ください。

ユーザーの操作に関する確認を追加する

ウェブページに reCAPTCHA を読み込むには、スコアベースキーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。
```
    <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>
  
```
reCAPTCHA は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script> で指定します。サポートされている言語については、reCAPTCHA の言語コードをご覧ください。

バッジのロケーションを指定する場合は、スクリプトタグでクエリパラメータとして badge=LOCATION を使用します。例: www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft。デフォルトの場所は bottomright に設定されています。その他の可能な値は inline と bottomleft です。

ユーザー操作に reCAPTCHA による確認を追加する手順は次のとおりです。

reCAPTCHA ライブラリの読み込み時に grecaptcha.enterprise.execute() が実行されるようにするため、grecaptcha.enterprise.ready() を使用します。

スコアベースのキーを使用して、保護対象のインタラクションごとに grecaptcha.enterprise.execute() を呼び出します。action パラメータで、ユーザーインタラクションに意味のある名前を指定します。詳しいガイダンスについては、アクションをご覧ください。

次の例では、ログインアクションで grecaptcha.enterprise.execute() を呼び出す方法を示します。

<script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/docs/create-assessment
  });
}
</script>

grecaptcha.enterprise.execute() によって、次の例のようにトークンが生成されます。

03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

WAF 統合でアクショントークンキーを統合する場合は、事前定義されたリクエストヘッダーにトークンを添付する必要があり、評価を作成する必要はありません。詳細については、reCAPTCHA アクショントークンを実装するをご覧ください。

重要: execute() で指定した action は評価の一部として返されます。評価の JSON レスポンスに含まれる action が、評価の作成時に指定した、想定されるアクションと一致していることを確認する必要があります。たとえば、ログインページで login アクションが返されます。不一致が存在する場合は、攻撃者が操作を偽装しようとしていることを示しています。

HTML ボタンに reCAPTCHA を追加する

ウェブページに reCAPTCHA を読み込むには、スコアベースキーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。
```
    <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>
  
```
reCAPTCHA は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script> で指定します。サポートされている言語については、reCAPTCHA の言語コードをご覧ください。
単純な HTML ボタンに reCAPTCHA を追加する手順は次のとおりです。
1. トークンを処理するコールバック関数を定義します。
```
<script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>
```
  詳細については、requestSubmit() メソッドをご覧ください。
2. html ボタンに属性を追加します。
```
<button class="g-recaptcha"
data-sitekey="KEY_ID"
data-callback='onSubmit'
data-action='submit'>Submit</button>
```
  バッジの位置を指定する場合は、class=g-recaptcha を含む要素に data-badge=LOCATION 属性を使用します。デフォルトの場所は bottomright に設定されています。その他の可能な値は inline と bottomleft です。
3. サイトでのフォームの送信にこのボタンを使用すると、g-recaptcha-response POST パラメータにレスポンストークンが含まれます。
  注: g-recaptcha ボタンを disabled として設定する場合、reCAPTCHA を読み込む際にボタンが有効になります。
トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

WAF 統合でアクショントークンキーを統合する場合は、事前定義されたリクエストヘッダーにトークンを添付する必要があり、評価を作成する必要はありません。詳細については、reCAPTCHA アクショントークンを実装するをご覧ください。

重要: execute() で指定した action は評価の一部として返されます。評価の JSON レスポンスに含まれる action が、評価の作成時に指定した、想定されるアクションと一致していることを確認する必要があります。たとえば、ログインページで login アクションが返されます。不一致が存在する場合は、攻撃者が操作を偽装しようとしていることを示しています。

次のステップ

reCAPTCHA の応答トークンを評価するため、評価を作成する。