將 Identity Platform 與 reCAPTCHA Enterprise API 整合

電子郵件密碼提供者

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

稽核模式

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

強制執行模式

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

電話供應商

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

稽核模式

將電話驗證強制執行設為稽核模式時，Identity Platform 會使用 reCAPTCHA 機器人保護機制進行應用程式驗證。如果使用者要求通過機器人防護評估，身分識別平台就會傳送含有驗證碼的簡訊至使用者的手機。如果要求無法通過機器人防護評估，且您使用的是用戶端 SDK，系統會觸發備用驗證方法，以便完成電話驗證流程。系統接受的備用方法取決於應用程式的平台。

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

• 缺少 reCAPTCHA 權杖。
• reCAPTCHA 權杖無效或已過期。
• reCAPTCHA 權杖未通過分數門檻。
• reCAPTCHA 設定不正確。

請確認已為應用程式平台設定備用驗證方法，並準備好在必要時由用戶端 SDK 觸發。

強制執行模式

將電話驗證強制執行設為強制模式時，Identity Platform 會使用 reCAPTCHA 機器人防護功能進行應用程式驗證。如果使用者要求通過機器人防護評估，身分識別平台就會傳送含有驗證碼的簡訊至使用者的手機。如果要求未通過機器人防護評估，Identity Platform 會封鎖要求，且不會傳送內含驗證碼的簡訊。

強制模式不需要備用驗證機制，因此您不必為應用程式設定任何額外的驗證方法。不過，如果您決定將應用程式的 reCAPTCHA 模式變更為 AUDIT 或 OFF，建議您為網頁應用程式設定 reCAPTCHA 驗證器，以確保啟用 reCAPTCHA v2。

電子郵件密碼提供者

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

1. 如果您尚未在專案中啟用 reCAPTCHA Enterprise API，請先完成這項作業。

2. 如要為專案啟用機器人防護功能，請使用 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 為租用戶啟用相同的設定方法來防範機器人。如要進一步瞭解如何更新租用戶，請參閱「更新租用戶」。

3. 如果您在 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 金鑰佈建作業可能需要幾分鐘才能完成。

4. 如果您已將強制執行設為稽核模式，建議您監控 reCAPTCHA 指標以防機器人攻擊，確保流程受到保護。

電話供應商

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

1. 如果您尚未在專案中啟用 reCAPTCHA Enterprise API，請先完成這項作業。

2. 如要為專案啟用機器人防護功能，請使用管理員 SDK。Node.js 管理員 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 為租用戶啟用相同的設定方法來防範機器人。如要進一步瞭解如何更新租用戶，請參閱「更新租用戶」。

3. 如果您在 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 金鑰佈建作業可能需要幾分鐘才能完成。

4. 如果您已將強制執行設為稽核模式，建議您監控 reCAPTCHA 指標以防機器人攻擊，確保流程受到保護。

網頁版

1. 更新至最新版的 Web SDK。

   • JavaScript SDK 9.20.0 以上版本支援在網頁應用程式中使用 reCAPTCHA 進行電子郵件和密碼驗證。
   • JavaScript SDK 11 以上版本支援在網頁應用程式中使用 reCAPTCHA 進行電話驗證。

   將網路 SDK 與應用程式整合後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應商啟用防護功能。

2. 如有需要，您可以強制擷取 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

1. 請更新至最新版的 Android SDK。在 Android 應用程式中，reCAPTCHA 支援電子郵件和密碼驗證，以及電話驗證功能，適用於 Android SDK 23.1.0 以上版本。

   此外，使用 reCAPTCHA 需要 API 級別 23 (Marshmallow) 以上版本和 Android 6 以上版本。

   將 Android SDK 與應用程式整合後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應者啟用保護機制。

2. 在應用程式層級 build.gradle 檔案的依附元件區段中新增下列建構規則：

   implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
   

   請務必使用 reCAPTCHA SDK 18.5.1 以上版本。

3. 如有需要，您可以強制擷取 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

1. 更新至 iOS SDK 11.6.0 以上版本。將 iOS SDK 與應用程式整合後，SDK 會自動擷取 reCAPTCHA 設定，並為您設定的供應商啟用保護功能。

2. 如要將 reCAPTCHA iOS SDK 整合至應用程式，請參閱「準備環境」。

3. 請確認 -ObjC 已列於連結器標記中。依序前往「Target」 >「Build Settings」 >「All」 >「Linking」，確認 Other Linker Flags 顯示 -ObjC。

4. 如有需要，您可以強制擷取 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 強制執行功能，請使用 Admin SDK 執行下列操作：

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

電話供應商

如要在專案或租用戶上啟用 reCAPTCHA 強制執行功能，以便針對簡訊驗證流程執行 reCAPTCHA，請使用 Admin SDK 執行下列操作：

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

電子郵件密碼提供者

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

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

電話供應商

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

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