本頁面由 Cloud Translation API 翻譯而成。

將 Identity Platform 與 reCAPTCHA Enterprise API 整合

本文說明如何透過 Identity Platform 與 reCAPTCHA Enterprise API 的整合功能，提升使用者安全性。這項功能可讓應用程式更有效地防範垃圾內容、濫用行為和其他詐欺活動。

整合作業會代表您建立 reCAPTCHA Enterprise 評估，以驗證使用者要求。如要瞭解定價資訊，請參閱 reCAPTCHA 定價。

總覽

設定 Identity Platform 與 reCAPTCHA Enterprise API 的整合時，您會啟用 reCAPTCHA 的預設防護功能，也就是 reCAPTCHA 機器人防護。啟用機器人防護後，Identity Platform 會在您的專案中，為您佈建以分數為準的 reCAPTCHA 金鑰。當使用者透過下列任一作業存取您的應用程式或網站時，如果已啟用對應的供應商，用戶端 SDK 就會載入 reCAPTCHA。

供應商	作業	方法
`passwordProvider`	使用電子郵件地址和密碼登入	`signInWithPassword`
	透過電子郵件地址和密碼註冊	`signUpPassword`
	透過電子郵件連結登入	`getOobCode`
	重設密碼	`getOobCode`
`phoneProvider`	使用電話號碼註冊或登入	`sendVerificationCode`
	註冊 MFA 電話號碼	`mfaSmsEnrollment`
	使用 MFA 電話號碼登入	`mfaSmsSignIn`

接著，reCAPTCHA 會根據您的設定和風險容許度，提供評估要求風險的分數給 Identity Platform。

詳情請參閱 reCAPTCHA 總覽。

事前準備

根據您要使用 reCAPTCHA 保護的驗證流程類型，請確保已設定下列項目：

如果是電子郵件地址/密碼驗證流程，請確認您已為使用者設定電子郵件登入功能。
如果是以簡訊為基礎的驗證流程，請確保您已加入下列至少一項服務：
- 為使用者啟用電話登入功能。
- 為網頁、Android 或 iOS 應用程式啟用多重驗證。

建立服務帳戶

如要將 Identity Platform 與 reCAPTCHA Enterprise API 整合，每個使用 reCAPTCHA 的專案都必須有 Identity Platform 服務帳戶。這樣一來，Identity Platform 就能代您管理 reCAPTCHA 金鑰。如果您已建立服務帳戶，請授予該帳戶 reCAPTCHA 存取權。

如果您尚未建立服務帳戶，或有其他想透過 reCAPTCHA 保護的專案，請按照下列步驟操作：

使用 Google Cloud CLI 建立服務帳戶：

gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID

將 PROJECT_ID 替換為專案 ID。

授予服務帳戶 reCAPTCHA 的存取權：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent

更改下列內容：

PROJECT_ID：專案 ID
PROJECT_NUMBER：專案帳戶號碼

reCAPTCHA 機器人防護模式

reCAPTCHA 機器人防護功能提供兩種模式，可協助您保護使用者：稽核和強制執行。這些模式的行為會因身分識別提供者而異。

電子郵件地址/密碼供應商

在電子郵件地址和密碼驗證流程中，稽核和強制執行模式的行為如下。

稽核模式

將電子郵件/密碼強制執行設定為稽核模式時，Identity Platform 會在專案中建立一或多個 reCAPTCHA 金鑰，用於評估 Identity Platform API 的流量，不會封鎖任何要求。使用稽核模式期間發出的指標，判斷是否應啟用 reCAPTCHA 強制執行。

強制執行模式

將電子郵件/密碼強制執行模式設為「強制執行」時，Identity Platform 會在專案中建立一或多個 reCAPTCHA 金鑰，用於評估 Identity Platform API 的流量。如果 API 要求未包含 reCAPTCHA 權杖，系統會拒絕要求。請務必先將所有用戶端遷移至支援 reCAPTCHA 的 SDK，再啟用強制執行功能。

手機供應商

電話驗證流程的稽核和強制執行模式行為如下。

稽核模式

將電話驗證強制執行模式設為稽核模式時，Identity Platform 會使用 reCAPTCHA 機器人防護功能驗證應用程式。如果使用者要求通過簡訊費用詐欺評估，系統就會傳送驗證碼簡訊。如果使用者要求未通過簡訊費用詐欺評估，且您使用用戶端 SDK，Identity Platform 會觸發備用驗證方法，完成電話號碼驗證流程。可接受的回退方法取決於應用程式的平台。

在下列情況下，用戶端 SDK 會觸發備用驗證方法：

缺少 reCAPTCHA 權杖。
reCAPTCHA 權杖無效或已過期。
reCAPTCHA 權杖未通過分數門檻。
reCAPTCHA 設定有誤。

請確保已為應用程式平台設定備用驗證方法，並視需要透過用戶端 SDK 觸發這些方法。

網頁

如果初步的機器人防護評估失敗，稽核模式會依賴 reCAPTCHA 第 2 版進行驗證。因此，您必須設定 reCAPTCHA 驗證器 (RecaptchaVerifier)，並將其傳遞至下列電話號碼驗證作業：

verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber

如果沒有 reCAPTCHA 驗證器，Identity Platform 就無法啟動 reCAPTCHA v2，並會傳回 auth/argument-error。如要進一步瞭解如何設定 reCAPTCHA 驗證器，請參閱 Firebase 說明文件中的「設定 reCAPTCHA 驗證器」。

Android

如果初步的機器人防護評估失敗，稽核模式會根據 Play Integrity API 驗證您的應用程式。如果驗證失敗，系統會觸發 reCAPTCHA 第 2 版。在下列情況下，系統可能會觸發 reCAPTCHA v2：

如果使用者的裝置未安裝 Google Play 服務。
如果應用程式不是透過 Google Play 商店發布 (適用於 Authentication SDK v21.2.0 以上版本)。
如果取得的 SafetyNet 權杖無效 (適用於 Authentication SDK 21.2.0 之前的版本)。

如要進一步瞭解如何設定 Android 應用程式驗證，請參閱 Firebase 說明文件中的「啟用應用程式驗證」。

iOS

如果初始機器人防護評估失敗，稽核模式會依賴無聲推播通知進行驗證。這個驗證方法會透過無聲推送通知，將權杖傳送至要求裝置上的應用程式。如果應用程式順利收到通知，手機驗證流程就會繼續進行。如果應用程式未收到推送通知，系統會觸發 reCAPTCHA v2。如果無聲推送通知設定有誤，系統可能會觸發 reCAPTCHA 第 2 版。

如要進一步瞭解如何設定 iOS 應用程式驗證，請參閱 Firebase 說明文件中的「啟用應用程式驗證」。

強制執行模式

將電話驗證強制執行模式設為強制執行模式後，Identity Platform 會使用 reCAPTCHA 機器人防護機制驗證應用程式。如果使用者要求通過簡訊費用詐欺評估，系統就會傳送驗證碼簡訊。如果使用者要求未通過簡訊費用詐欺評估，Identity Platform 會封鎖要求，不會傳送內含驗證碼的簡訊。

強制執行模式不需要備援驗證，因此您不必為應用程式設定任何額外的驗證方法。不過，我們建議為網頁應用程式設定 reCAPTCHA 驗證器，確保在您決定將應用程式的 reCAPTCHA 模式變更為 AUDIT 或 OFF 時，系統會啟用 reCAPTCHA v2。

設定 Identity Platform 與 reCAPTCHA Enterprise API 的整合

如要設定 Identity Platform 與 reCAPTCHA Enterprise API 的整合，請執行下列工作：

使用 Admin SDK 設定 reCAPTCHA 強制執行狀態，並啟用機器人防護機制。
為應用程式的平台設定用戶端 SDK。

建議您先以稽核模式啟用 reCAPTCHA 強制執行功能，並監控專案發出的 reCAPTCHA 指標，確保驗證流程受到適當保護。這樣做可避免在稽核使用者 reCAPTCHA 使用情形時，中斷使用者流量。確認驗證流程受到保護後，請將機器人防護設定為 ENFORCE。

啟用 reCAPTCHA 機器人防護功能

電子郵件地址/密碼供應商

如要為電子郵件地址/密碼驗證流程啟用 reCAPTCHA 機器人防護機制，請按照下列步驟操作：

如果尚未啟用，請為專案啟用 reCAPTCHA Enterprise API。
如要為專案啟用機器人防護功能，請使用 Admin SDK。Node.js Admin SDK 11.7.0 以上版本支援 reCAPTCHA。

例如：
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }]
  }
};
const updateProjectConfigWithRecaptcha = () => {
  getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
    console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating project config:', error);
  });
}
```
更改下列內容：
- ENFORCE_MODE：要為 reCAPTCHA 電子郵件/密碼驗證強制執行設定的模式。有效值為 OFF、AUDIT 和 ENFORCE。如要啟用機器人防護功能，這個參數必須設為 AUDIT 或 ENFORCE。首次啟用機器人防護功能時，建議將這個參數設為 AUDIT，並確保驗證流程受到保護，再將這個參數設為 ENFORCE。如要進一步瞭解模式的運作方式，請參閱 reCAPTCHA 機器人防護模式。
- END_SCORE：要求失敗前可擁有的最低機器人防護評估分數。您可以將分數設為介於 0.0 和 1.0 之間。舉例來說，如果將門檻設為 0.6，reCAPTCHA 就會拒絕分數為 0.5 或更低的要求。因此，分數越高，規則就越嚴格。
您也可以使用 Admin SDK，透過相同的設定方法為租戶啟用機器人防護功能。如要進一步瞭解如何更新租戶，請參閱「更新租戶」。
如果您在 iOS 或 Android 上使用 Identity Platform，請務必從 Firebase 主控台註冊應用程式：
- 如果是 iOS，請註冊使用 Identity Platform 的每個軟體包 ID
- 如果是 Android，請註冊使用 Identity Platform 的每個 Android 套件名稱
如果您在網路上使用 Identity Platform，則必須為每個使用 reCAPTCHA 的網域新增已授權網域。如要新增授權網域，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「Identity Platform」頁面。
  
  前往 Identity Platform
2. 依序前往「設定」>「安全性」。
3. 按一下「新增網域」。
4. 輸入網域名稱，然後按一下「新增」儲存網域。
佈建 reCAPTCHA 金鑰可能需要幾分鐘才能完成。
如果已將強制執行模式設為稽核模式，建議您監控reCAPTCHA 機器人防護指標，確保流程受到保護。

手機供應商

如要為簡訊驗證流程啟用 reCAPTCHA 機器人防護功能，請按照下列步驟操作：

如果尚未啟用，請為專案啟用 reCAPTCHA Enterprise API。
如要為專案啟用機器人防護功能，請使用 Admin SDK。 Node.js Admin SDK 12.7.0 以上版本支援 reCAPTCHA。

例如：
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE_MODE',
    managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
    useSmsBotScore: 'true',
  }
}
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
更改下列內容：
- ENFORCE_MODE：您要為 reCAPTCHA 手機驗證強制執行設定的模式。有效值為 OFF、AUDIT 和 ENFORCE。如要為簡訊流程啟用機器人防護功能，這個參數必須設為 AUDIT 或 ENFORCE，且 useSmsBotScore 必須設為 true。
  
  首次啟用機器人防護功能時，建議將這個參數設為 AUDIT，並確保驗證流程受到保護，再將這個參數設為 ENFORCE。如要進一步瞭解模式的運作方式，請參閱 reCAPTCHA 機器人防護模式。
- END_SCORE：要求失敗前可擁有的最低機器人防護評估分數。您可以將分數設為介於 0.0 和 1.0 之間。舉例來說，如果將門檻設為 0.6，reCAPTCHA 就會拒絕分數為 0.5 或更低的要求。因此，分數越高，規則就越嚴格。
您也可以使用 Admin SDK，透過相同的設定方法為租戶啟用機器人防護功能。如要進一步瞭解如何更新租戶，請參閱「更新租戶」。

注意： 在行動平台上，Identity Platform 不支援透過手機驗證和簡訊多重驗證功能，使用多個租戶。
如果您在 iOS 或 Android 上使用 Identity Platform，請務必透過 Firebase 控制台註冊應用程式：
- 如果是 iOS，請註冊使用 Identity Platform 的每個軟體包 ID
- 如果是 Android，請註冊使用 Identity Platform 的每個 Android 套件名稱
如果您在網路上使用 Identity Platform，則必須為每個使用 reCAPTCHA 的網域新增授權網域。如要新增已授權網域，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「Identity Platform」頁面。
  
  前往 Identity Platform
2. 依序前往「設定」>「安全性」。
3. 按一下「新增網域」。
4. 輸入網域名稱，然後按一下「新增」儲存網域。
reCAPTCHA 金鑰佈建程序可能需要幾分鐘才能完成。
如果已將強制執行模式設為稽核模式，建議您監控reCAPTCHA 機器人防護指標，確保流程受到保護。

設定用戶端 SDK

根據應用程式的平台設定用戶端 SDK。

網頁版

更新至最新版網頁 SDK。
- JavaScript SDK 9.20.0 以上版本支援在網頁應用程式中，使用 reCAPTCHA 進行電子郵件和密碼驗證。
- JavaScript SDK 11 以上版本支援網頁應用程式的電話號碼驗證 reCAPTCHA。
將網頁 SDK 整合至應用程式後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應商啟用保護機制。

如有需要，您可以強制擷取 reCAPTCHA 信號，方法如下：

import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

更新至最新版 Android SDK。Android SDK 23.1.0 以上版本支援在 Android 應用程式中，對電子郵件和密碼驗證以及電話驗證使用 reCAPTCHA。

此外，reCAPTCHA 支援功能需要 API 級別 23 (Marshmallow) 以上版本，以及 Android 6 以上版本。

將 Android SDK 整合至應用程式後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應商啟用保護機制。
在應用程式層級 build.gradle 檔案的依附元件區段中，新增下列建構規則：
```
implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
```
請務必使用 reCAPTCHA SDK 18.5.1 以上版本。

如有需要，您可以強制擷取 reCAPTCHA 信號，方法如下：

Kotlin：

// Initialize Firebase Authentication
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}

Java：

// Initialize Firebase Authentication
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

更新至 iOS SDK 11.6.0 以上版本。將 iOS SDK 整合至應用程式後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應商啟用保護機制。
如要將 reCAPTCHA iOS SDK 整合至應用程式，請參閱「準備環境」。
確認連結器標記中列有 -ObjC。依序前往「Target」 >「Build Settings」 >「All」 >「Linking」，並確認 Other Linker Flags 顯示 -ObjC。

如有需要，您可以強制擷取 reCAPTCHA 信號，方法如下：

Swift：

// Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()

Objective-C：

// Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

監控 reCAPTCHA 指標，防範機器人攻擊

建議您先使用稽核模式，並監控專案發出的 reCAPTCHA 指標，確保驗證流程受到保護，再將 reCAPTCHA 強制執行模式設為強制執行模式。舉例來說，這些指標可協助您判斷是否已正確設定 Identity Platform 與 reCAPTCHA Enterprise API 的整合。此外，這類資料也有助於微調使用者流量的分數門檻。如果 reCAPTCHA 金鑰佈建失敗，或是未建立必要服務帳戶，reCAPTCHA 驗證嘗試仍會正常成功。

請檢查專案傳送至 Cloud Monitoring 的下列指標，確認 reCAPTCHA 驗證是否正常運作：

identitytoolkit.googleapis.com/recaptcha/verdict_count：追蹤 reCAPTCHA 傳回的不同判定結果。
identitytoolkit.googleapis.com/recaptcha/token_count：追蹤 Identity Platform 後端收到的 reCAPTCHA 權杖數量和狀態。
identitytoolkit.googleapis.com/recaptcha/risk_scores：追蹤機器人防護分數分布。

詳情請參閱「監控 reCAPTCHA 指標」。

強制執行 reCAPTCHA 機器人防護

確認應用程式收到可接受的使用者流量後，即可啟用 reCAPTCHA 強制執行功能，保護使用者。請確保不會干擾現有使用者，包括可能使用舊版應用程式的使用者。

電子郵件地址/密碼供應商

如要為專案或租戶啟用電子郵件/密碼驗證流程的 reCAPTCHA 強制執行功能，請使用 Admin SDK 執行下列指令：

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

手機供應商

如要為專案或租戶啟用簡訊驗證流程的 reCAPTCHA 強制執行功能，請使用 Admin SDK 執行下列指令：

const enforceRequest = {
  recaptchaConfig: {
    phoneEnforcementState:  'ENFORCE',
    useSmsBotScore: 'true'
    }]
  }
};

停用 reCAPTCHA 機器人防護功能

電子郵件地址/密碼供應商

如要停用電子郵件/密碼驗證流程的機器人防護功能，請使用 Admin SDK 執行下列指令：

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

手機供應商

如要停用簡訊驗證流程的機器人防護功能，請使用 Admin SDK 執行下列指令：

const disableRequest = {
  recaptchaConfig: {
    phoneEnforcementState:  'OFF',
    useSmsBotScore: 'false'
  }
};

使用 Cloud Run 函式覆寫 reCAPTCHA 判定結果

除了設定分數門檻，您也可以使用封鎖函式，根據自訂因素允許或封鎖流程，藉此覆寫特定權杖的 reCAPTCHA 判決。如果特定使用者登入時的 reCAPTCHA 分數偏低，但使用者值得信任或已透過其他方式驗證，因此允許完成登入，這項功能就很有幫助。

以下範例說明如何使用封鎖函式，覆寫 reCAPTCHA 判決：

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

後續步驟

針對簡訊驗證流程啟用 reCAPTCHA SMS defense。
瞭解如何使用自己的 reCAPTCHA 金鑰。
進一步瞭解如何監控 reCAPTCHA 指標。
進一步瞭解 reCAPTCHA。