アプリケーション サーバーで reCAPTCHA express を設定する

このドキュメントでは、API エンドポイントの保護など、reCAPTCHA JavaScript またはモバイル SDK の統合が不可能な環境で、アプリケーション サーバーに reCAPTCHA express を設定する方法について説明します。

reCAPTCHA express は、クライアントサイドの機能なしで評価を作成できる機能です。reCAPTCHA express は、バックエンド シグナルのみを使用して reCAPTCHA リスクスコアを生成します。このリスクスコアを使用して、リクエストを処理するか、チャレンジ ページにリダイレクトするか、後で分析するためにログに記録するかを決定できます。

始める前に

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    後で使用できるように、Google Cloud プロジェクト ID を記録します。

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

  4. 認証用の API キーを作成します。

    1. Google Cloud コンソールで、[認証情報] ページに移動します。

      [認証情報] に移動

    2. [認証情報を作成] をクリックし、[API キー] を選択します。

    3. 後で使用できるように、API キーを記録します。

reCAPTCHA express キーを作成する

reCAPTCHA express を実装するには、reCAPTCHA express キーを作成します。

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. gcloud

    reCAPTCHA キーを作成するには、gcloud recaptcha keys create コマンドを使用します。

    後述のコマンドデータを使用する前に、次のように置き換えます。

    • DISPLAY_NAME: キーの名前。通常はサイトの名前です。

    gcloud recaptcha keys create コマンドを実行します。

    Linux、macOS、Cloud Shell

    gcloud recaptcha keys create \
--express \
--display-name=DISPLAY_NAME

    Windows（PowerShell）

    gcloud recaptcha keys create `
--express `
--display-name=DISPLAY_NAME

    Windows（cmd.exe）

    gcloud recaptcha keys create ^
--express ^
--display-name=DISPLAY_NAME

    レスポンスには、新しく作成された reCAPTCHA キーが含まれます。

    REST

    キーの種類と統合タイプに関する API リファレンス情報については、鍵と統合タイプをご覧ください。

    リクエストのデータを使用する前に、次のように置き換えます。

    • DISPLAY_NAME: キーの名前。通常はサイトの名前です。

    HTTP メソッドと URL:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    リクエストの本文（JSON）: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    リクエストを送信するには、次のいずれかのオプションを選択します。

    curl

    リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    次のような JSON レスポンスが返されます。

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

後で使用するために、express キーを記録します。

評価の作成

アプリケーション サーバーから reCAPTCHA へのリクエストを行うには、projects.assessments.create メソッドを使用して評価を作成します。

リクエストのデータを使用する前に、次のように置き換えます。

  • API_KEY: 認証用に作成した API キー。
  • EXPRESS_KEY: アプリケーション用に作成した reCAPTCHA express キー。
  • USER_IP_ADDRESS: このイベントに関連するユーザーのデバイスからのリクエストに含まれる IP アドレス。
  • HEADER_INFO: 省略可。クライアントがアプリケーション サーバーに送信した HTTP ヘッダー。 これは、リクエスト ヘッダーが [key:value] 形式で格納された文字列配列です。たとえば、[key:value, key:value,...] のようになります。必要な順序でできるだけ多くのヘッダーを共有することをおすすめします。ヘッダーの順序が、同じセッション内のすべてのリクエストで一致していることを確認します。
  • JA3_FINGERPRINT: 省略可。JA3 は、TLS クライアント hello パケットの特定のフィールドの MD5 フィンガープリントです。詳細については、JA3 - SSL/TLS クライアントのプロファイリング方法をご覧ください。
  • URI_NAME: 省略可。ユーザーによってアクセスされている URI。
  • USER_AGENT: 省略可。このイベントに関連するユーザーのデバイスからのリクエストに含まれるユーザー エージェント。
  • ACCOUNT_ID: 省略可。ハッシュ化されたアカウント名など、ユーザーのアカウントの一意で永続的な識別子。

HTTP メソッドと URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

リクエストの本文（JSON）: 


{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "firewallPolicyEvaluation": false,
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

スコアを解釈する

reCAPTCHA express は、0.3 と 0.7 の 2 つのスコアのみを返します。 0.3 は、ユーザー インタラクションのリスクが高く、不正行為の可能性が高いことを示します。0.7 は、ユーザー インタラクションのリスクが低く、正当である可能性が高いことを示します。

シグナルが不足している場合、reCAPTCHA express はデフォルトで 0.7 を返します。

次のステップ