モバイルアプリ用に Google Cloud Armor と統合する

このドキュメントでは、モバイルアプリで reCAPTCHA の機能を Cloud Armor と統合する方法について説明します。

統合を完了するには、reCAPTCHA の 1 つ以上の機能を実装し、Cloud Armor セキュリティ ポリシーを構成する必要があります。ただし、モバイルアプリで Cloud Armor と統合するには、reCAPTCHA アクション トークンのみを実装できます。

始める前に

1. reCAPTCHA Enterprise API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

   API の有効化

2. 保護するアクションを指定します。

reCAPTCHA アクション トークンを実装する

アクション トークンを生成するには、reCAPTCHA をモバイルアプリで実行する必要があります。 checkout などのユーザー アクションを保護する必要がある場合、reCAPTCHA がアクション トークンを生成したら、事前定義されたリクエスト ヘッダーにアクション トークンを添付します。デフォルトでは、アクション トークンは 30 分間有効ですが、トラフィックによって異なる場合があります。 Cloud Armor がトークン属性を評価できるように、トークンの有効期限が切れる前にアクション トークンを事前定義されたリクエスト ヘッダーに添付する必要があります。

reCAPTCHA アクション トークンを実装するには、次の手順を実行します。

1. モバイルアプリのアクション トークン キーを作成します。

   コンソール

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

      [reCAPTCHA] に移動

   2. ページの上部にあるプロジェクト セレクタにリソース名が表示されていることを確認します。

      プロジェクトの名前が表示されない場合は、リソース セレクタをクリックしてプロジェクトを選択します。

   3. [鍵を作成] をクリックします。
   4. [表示名] フィールドに、キーの表示名を入力します。
   5. WAF 用の reCAPTCHA キーを作成するアプリの種類に応じて、適切なアクションを実行します。
   注: モバイルアプリのアクション トークン キーのみを作成できます。

   iOS アプリ用の WAF 用 reCAPTCHA キーを作成する

   iOS アプリごとに reCAPTCHA キーを 1 つ作成することをおすすめします。

   1. [アプリケーションの種類] で [iOS] を選択します。
   1. [iOS bundle ID list] セクションで、[iOS バンドル ID を追加] をクリックします。

   2. [バンドル ID] フィールドに、iOS バンドル ID の名前を入力します。

   3. 省略可: 別のバンドル ID を追加するには、[iOS バンドル ID を追加] をクリックし、[バンドル ID] フィールドに iOS バンドル ID の名前を入力します。
   4. バンドル ID の reCAPTCHA キーを保護するには、 [バンドル ID の確認を無効にする] トグルがオフになっていることを確認します。

   5. 省略可: Apple Developer の設定 を指定します。

      reCAPTCHA がトラフィックに対してより正確なリスクスコアを提供できるため、このデータを提供することをおすすめします。

      次の情報を入力します。

      • 秘密鍵（.p8）: これは、Apple Developer Center の [Certificates, Identifiers & Profiles] で生成されます。
      • キー ID: Apple デベロッパー キー ID（10 文字の文字列）。
      • チーム ID: アプリの構築に使用されるプロビジョニング プロファイルを所有している Apple チーム ID（10 文字の文字列）。
   6. 省略可: [次のステップ（省略可）] をクリックします。
   1. WAF 用の reCAPTCHA キーを作成するには、次のようにします。
      1. [**追加設定**] で、
      2. [**追加設定**] で、 [**このキーをウェブ アプリケーション ファイアウォール（WAF）にデプロイしますか？**] 切り替えをオンにします。
      3. [サービス] オプションから [Cloud Armor] を選択します。
      4. [機能] オプションから [アクション] を選択します。

   2. 本番環境以外の環境で、評価の作成時にキーが返すスコアを指定する場合は、次の操作を行います。

      1. [**追加設定**] で、[**この鍵はテスト目的でのみ作成しますか？**] 切り替えをクリックします。
      2. [スコアを設定] スライダーを使用して、0 ～ 1.0 のスコアを指定します。
   7. [鍵を作成] をクリックします。

   新しく作成された鍵は、[reCAPTCHA のキー] ページにリストされています。

   Android アプリ用の WAF 用 reCAPTCHA キーを作成する

   1. [**アプリケーションの種類**] で [**Android**] を選択します。
      
   2. [Android パッケージ リスト] セクションで、[Android パッケージを追加] をクリックします。
   3. [Android パッケージ] フィールドに、Android パッケージの名前を入力します。
   4. 省略可: パッケージを追加するには、[Android パッケージを追加] をクリックして、[Android パッケージ] に別の Android パッケージの名前を入力します。
   5. reCAPTCHA キーがアプリでのみ使用されるようにするには、 [パッケージ名の確認を無効にする] をオフに切り替えます。
   6. Google Play ストアに加えて他のアプリストアで利用できるアプリケーションのキーを作成する場合は、[Google Play ストアの外部で配布されるアプリケーションをサポートする] をオンにします。
   7. 省略可: [次のステップ（省略可）] をクリックします。
   1. WAF 用の reCAPTCHA キーを作成するには、次のようにします。
      1. [**追加設定**] で、
      2. [**追加設定**] で、 [**このキーをウェブ アプリケーション ファイアウォール（WAF）にデプロイしますか？**] 切り替えをオンにします。
      3. [サービス] オプションから [Cloud Armor] を選択します。
      4. [機能] オプションから [アクション] を選択します。

   2. 本番環境以外の環境で、評価の作成時にキーが返すスコアを指定する場合は、次の操作を行います。

      1. [**追加設定**] で、[**この鍵はテスト目的でのみ作成しますか？**] 切り替えをクリックします。
      2. [スコアを設定] スライダーを使用して、0 ～ 1.0 のスコアを指定します。
   8. [鍵を作成] をクリックします。

   新しく作成された鍵は、[reCAPTCHA のキー] ページにリストされています。

   gcloud（iOS）

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

   注: モバイルアプリで WAF 用の reCAPTCHA キーを作成する操作は、Cloud Armor との統合でのみサポートされています。この統合では、モバイルアプリのアクション トークン キーのみを作成できます。

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

   • DISPLAY_NAME: キーの名前。通常はサイトの名前です。
   • BUNDLE_IDs: キーの使用を許可されているアプリの iOS バンドル ID。 複数のバンドル ID をカンマ区切りのリストとして指定します。
   • WAF_FEATURE: WAF 機能の名前。 action-token を実行します。
   • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。

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

   Linux、macOS、Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --ios --bundle-ids=BUNDLE_IDs \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE 

   Windows（PowerShell）

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --ios --bundle-ids=BUNDLE_IDs `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE 

   Windows（cmd.exe）

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --ios --bundle-ids=BUNDLE_IDs ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE 

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

   gcloud（Android）

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

   注: モバイルアプリで WAF 用の reCAPTCHA キーを作成する操作は、Cloud Armor との統合でのみサポートされています。この統合では、モバイルアプリのアクション トークン キーのみを作成できます。

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

   • DISPLAY_NAME: キーの名前。通常はサイトの名前です。
   • PACKAGE_NAMES: キーの使用が許可されているアプリの Android パッケージ名。複数のパッケージをカンマ区切りのリストとして指定します。
   • WAF_FEATURE: WAF 機能の名前。 action-token を実行します。
   • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。

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

   Linux、macOS、Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --android --package-names=PACKAGE_NAMES \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE 

   Windows（PowerShell）

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --android --package-names=PACKAGE_NAMES `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE 

   Windows（cmd.exe）

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --android --package-names=PACKAGE_NAMES ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE 

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

   REST（iOS）

   注: モバイルアプリで WAF 用の reCAPTCHA キーを作成する操作は、Cloud Armor との統合でのみサポートされています。この統合では、モバイルアプリのアクション トークン キーのみを作成できます。

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

   • DISPLAY_NAME: キーの名前。通常、アプリ名です。
   • BUNDLE_IDs: キーの使用を許可されているアプリの iOS バンドル ID。 複数のバンドル ID をカンマ区切りのリストとして指定します。
   • WAF_FEATURE: WAF 機能の名前。 action-token を実行します。
   • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。

   HTTP メソッドと URL:

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

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

   {
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
    "allowedBundleIds": "BUNDLE_IDS"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   curl

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を 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

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を 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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
       "allowAllBundleIds": false,
       "allowedBundleIds": [
           BUNDLE_IDS
       ]
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

   REST（Android）

   注: モバイルアプリで WAF 用の reCAPTCHA キーを作成する操作は、Cloud Armor との統合でのみサポートされています。この統合では、モバイルアプリのアクション トークン キーのみを作成できます。

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

   • DISPLAY_NAME: キーの名前。通常、アプリ名です。
   • PACKAGE_NAMES: キーの使用が許可されているアプリの Android パッケージ名。複数のパッケージをカンマ区切りのリストとして指定します。
   • WAF_FEATURE: WAF 機能の名前。 action-token を実行します。
   • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。

   HTTP メソッドと URL:

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

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

   {
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
     "allowedPackageNames":"PACKAGE_NAMES"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   curl

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を 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

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を 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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
         "allowAllPackageNames": false,
         "allowedPackageNames": [
             PACKAGE_NAMES
         ],
         "supportNonGoogleAppStoreDistribution": false
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

2. 作成したアクション トークンキーを使用して、モバイルアプリに reCAPTCHA モバイル SDK を統合します。手順については、モバイルアプリの種類に対応するドキュメントをご覧ください。

   • Android の場合は、WAF キーを Android アプリと統合するをご覧ください。
   • iOS の場合は、WAF キーを iOS アプリと統合するをご覧ください。

3. reCAPTCHA からトークンを受信したら、次の形式の事前定義されたリクエスト ヘッダーにトークンを添付します。

   X-Recaptcha-Token: value-of-your-action-token
   

   次のサンプルコードは、トークンを添付する方法を示しています。

   Android

   Java のサンプルコード

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   //
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of the
   // HTTP request.
   
   public static void sendRequestToServerWithRceToken(
       String serverUrl, String rceToken) throws JSONException, IOException {
    URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    connection.setRequestProperty("X-Recaptcha-Token", rceToken);
   
    try {
       String requestBody = "['']";
       sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
    } finally {
       connection.disconnect();
    }
   }
   
   private static void sendRequest(
       HttpURLConnection connection, String requestString, String requestName, String action)
       throws IOException {
    connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
    connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
    connection.setRequestProperty("Content-type", CONTENT_TYPE);
    connection.setRequestProperty(
       "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
    connection.setRequestMethod(action);
    connection.setDoOutput(true);
    connection.connect();
    try (OutputStream postStream = connection.getOutputStream()) {
       postStream.write(requestString.getBytes(UTF_8));
    }
   
    int responseCode = connection.getResponseCode();
    String response = connection.getResponseMessage();
    if (responseCode != HttpURLConnection.HTTP_OK) {
       throw new IOException(
          String.format(
             "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
             responseCode, response));
    }
   }

   iOS

   Swift のサンプルコード

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of
   // the HTTP request.
   
    public static func accessWafServer(rceToken: String, serverUrl: String)
       async throws -> String
    {
       let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
       var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
       request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")
   
       let data = try await HttpHelper.getDataFromServer(request)
   
       return String(decoding: data, as: UTF8.self)
    }

Cloud Armor セキュリティ ポリシーを構成する

WAF 用 reCAPTCHA の機能を実装したら、bot 管理用に reCAPTCHA トークンを評価する Cloud Armor セキュリティ ポリシーを構成する必要があります。

Cloud Armor セキュリティ ポリシーを構成し、セキュリティ ポリシーで アクション トークン キーを使用する方法については、 bot 管理のルールを構成するをご覧ください。

reCAPTCHA スコアを取得する

reCAPTCHA アクション トークンの場合、X-Recaptcha-Wafdata ヘッダーから reCAPTCHA スコアを取得できます。 これらのスコアに基づいて、ユーザー リクエストに対して実行する必要があるカスタム アクションを構成できます。

次の例は、X-Recaptcha-Wafdata ヘッダーのサンプルを示しています。

X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n

Google Cloud Armor ログで reCAPTCHA スコアを確認することもできます。

次のステップ

• bot 管理のルールを構成する。