與 Google Cloud Armor 整合，適用於行動應用程式

您可以將 Google Cloud Fraud Defense 的功能與 Cloud Armor 整合，用於行動應用程式。

如要完成整合，您必須導入一或多項 reCAPTCHA 功能，並設定 Cloud Armor 安全性政策。不過，您只能導入 reCAPTCHA 動作權杖，以便在行動應用程式中與 Cloud Armor 整合。

事前準備

1. 啟用 reCAPTCHA Enterprise API。

   啟用 API 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

2. 找出要保護的操作。

導入 reCAPTCHA 動作權杖

您必須在行動應用程式上執行 reCAPTCHA，才能產生動作權杖。 reCAPTCHA 產生動作權杖後，您可以在需要保護任何使用者動作 (例如 checkout) 的位置，將動作權杖附加至預先定義的要求標頭。根據預設，動作權杖的有效期限為 30 分鐘，但可能因流量而異。您必須在權杖到期前，將動作權杖附加至預先定義的要求標頭，Cloud Armor 才能評估權杖屬性。

如要導入 reCAPTCHA 動作權杖，請按照下列步驟操作：

1. 為行動應用程式建立動作權杖金鑰。

   控制台

   1. 前往 Google Cloud 控制台的「Google Cloud Fraud Defense」頁面。

      前往 Google Cloud Fraud Defense

   2. 確認專案名稱顯示在頁面頂端的資源選取器中。

      如果找不到專案名稱，請按一下資源選取器，然後選取專案。

   3. 選取「金鑰」分頁標籤。
   4. 按一下「建立金鑰」。
   5. 在「Display name」(顯示名稱) 欄位中，輸入金鑰的顯示名稱。
   6. 視您要為哪種應用程式建立 reCAPTCHA WAF 金鑰，執行適當的操作：
   注意：您只能為行動應用程式建立動作權杖金鑰。

   為 iOS 應用程式建立 WAF 適用的 reCAPTCHA 金鑰

   建議您為每個 iOS 應用程式建立一個 reCAPTCHA 金鑰。

   1. 在「應用程式類型」部分，選取「iOS」。
   1. 在「iOS bundle ID list」(iOS 軟體包 ID 清單) 部分，按一下「Add iOS bundle ID」(新增 iOS 軟體包 ID)。

   2. 在「Bundle ID」欄位中，輸入 iOS 軟體包 ID 的名稱。

   3. 選用：如要新增其他軟體包 ID，請按一下「Add iOS bundle ID」(新增 iOS 軟體包 ID)，然後在「Bundle ID」(軟體包 ID) 欄位中輸入 iOS 軟體包 ID 名稱。
   4. 為保護軟體包 ID 的 reCAPTCHA 金鑰，請確認「停用軟體包 ID 驗證」切換鈕已關閉。如果停用軟體包 ID 驗證，您必須驗證所建立評估作業中的 tokenProperties.iosBundleId 欄位。

   5. 選用：提供 Apple Developer 設定。

      建議您提供這項資料，讓 Fraud Defense 為流量提供更準確的風險評分。

      輸入下列資訊：

      • 私密金鑰 (.p8)：在 Apple Developer Center 的「Certificates, Identifiers & Profiles」下方產生。
      • 金鑰 ID：Apple 開發人員金鑰 ID (10 個字元的字串)。
      • 團隊 ID：Apple 團隊 ID (10 個字元的字串)，擁有用於建構應用程式的佈建設定檔。
   6. 選用：按一下「下一步 (選用)」。
   1. 如要建立 WAF 的 reCAPTCHA 金鑰，請按照下列步驟操作：
      1. 在「其他設定」中，開啟
      2. 在「其他設定」中，開啟「您是否要在網頁應用程式防火牆 (WAF) 中部署這組金鑰？」切換鈕。
      3. 在「Service」(服務) 選項中，選取「Cloud Armor」。
      4. 在「功能」選項中，選取「動作」。

   2. 在非正式環境中，如要指定金鑰在建立評估時應傳回的分數，請按照下列步驟操作：

      1. 在「其他設定」中，按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
      2. 使用「設定分數」滑桿，指定 0 到 1.0 之間的分數。
   7. 按一下 [Create key] (建立金鑰)。

   新建立的金鑰會列在「reCAPTCHA keys」(reCAPTCHA 金鑰) 頁面。

   為 Android 應用程式建立 WAF 適用的 reCAPTCHA 金鑰

   1. 在「應用程式類型」部分，選取「Android」。
      
   2. 在「Android package list」(Android 套件清單) 區段中，按一下「Add Android package」(新增 Android 套件)。
   3. 在「Android package」(Android 套件) 欄位中，輸入 Android 套件名稱。
   4. 選用：如要新增其他套件，請按一下「Add Android package」(新增 Android 套件)，然後在「Android package」(Android 套件) 欄位中輸入其他 Android 套件的名稱。
   5. 如要強制規定 reCAPTCHA 金鑰只能在應用程式中使用，請關閉「停用套件名稱驗證」切換鈕。如果停用套件名稱驗證，您必須驗證所建立評估中的 tokenProperties.androidPackageName 欄位。
   6. 如要為 Google Play 商店以外其他應用程式商店提供的應用程式建立金鑰，請開啟「支援在 Google Play 商店以外平台發布應用程式」。
   7. 選用：按一下「下一步 (選用)」。
   1. 如要建立 WAF 的 reCAPTCHA 金鑰，請按照下列步驟操作：
      1. 在「其他設定」中，開啟
      2. 在「其他設定」中，開啟「您是否要在網頁應用程式防火牆 (WAF) 中部署這組金鑰？」切換鈕。
      3. 在「Service」(服務) 選項中，選取「Cloud Armor」。
      4. 在「功能」選項中，選取「動作」。

   2. 在非正式環境中，如要指定金鑰在建立評估時應傳回的分數，請按照下列步驟操作：

      1. 在「其他設定」中，按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
      2. 使用「設定分數」滑桿，指定 0 到 1.0 之間的分數。
   8. 按一下 [Create key] (建立金鑰)。

   新建立的金鑰會列在「reCAPTCHA keys」(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 方法和網址：

   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 方法和網址：

   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：請參閱「將 Google Cloud Fraud Defense 整合至 Android 應用程式」。
   • 如果是 iOS，請參閱「將 Google Cloud Fraud Defense 與 iOS 應用程式整合」。

3. 收到權杖後，請按照下列格式將權杖附加至預先定義的要求標頭：

   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 安全性政策

導入 Fraud Defense for WAF 的功能後，您必須設定 Cloud Armor 安全性政策，評估 reCAPTCHA 權杖，以便管理機器人。

如要瞭解如何設定 Cloud Armor 安全性政策，以及如何搭配安全性政策使用動作權杖金鑰，請參閱「設定機器人管理規則」。

取得 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 分數。

後續步驟

• 設定機器人管理規則。