為簡訊驗證功能啟用 reCAPTCHA SMS defense

本文說明如何使用 reCAPTCHA 保護 Identity Platform 的簡訊驗證流程 (例如手機和多重驗證)，以免遭受簡訊費用詐欺 (又稱為垃圾簡訊攻擊)。

總覽

如果應用程式仰賴以簡訊為基礎的驗證流程，您可以啟用 Firebase 驗證或 Identity Platform 與 reCAPTCHA 的整合功能。啟用後，當使用者透過以下 phoneProvider 作業，從應用程式或網站要求驗證簡訊時，Firebase Authentication 和 Identity Platform 就會叫用 reCAPTCHA SMS defense 功能：

作業 方法
使用電話號碼註冊或登入 sendVerificationCode
多重身分驗證電話號碼註冊 mfaSmsEnrollment
使用多重驗證的電話號碼登入 mfaSmsSignIn

接著，reCAPTCHA 會向 Firebase 驗證或 Identity Platform 提供風險分數，指出使用者電話號碼遭受簡訊費用詐欺的可能性。Firebase 驗證和 Identity Platform 會將這項分數與您在 reCAPTCHA 簡訊防護設定中設定的門檻進行比較，然後根據您在設定中設定的動作處理要求。

如要進一步瞭解 reCAPTCHA 簡訊防護功能，請參閱「偵測及防範簡訊詐欺」。

事前準備

為 Identity Platform 啟用 reCAPTCHA SMS defense 之前，請先完成下列工作：

reCAPTCHA 電話驗證強制執行模式

如要使用 reCAPTCHA SMS defense，您必須設定 reCAPTCHA 電話驗證強制執行模式，該模式有兩種模式：稽核和強制執行。

稽核模式

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

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

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

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

網頁

如果初始詐欺評估失敗，稽核模式會使用 reCAPTCHA v2 進行驗證。因此，您必須設定 reCAPTCHA 驗證器 (RecaptchaVerifier)，並將其傳遞至下列電話驗證作業：

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

Android

如果初始的詐欺評估作業失敗，稽核模式會根據 Play Integrity API 驗證您的應用程式。如果這項驗證失敗，系統會觸發 reCAPTCHA v2。在下列情況下，系統可能會觸發 reCAPTCHA v2：

  • 如果使用者的裝置未安裝 Google Play 服務。
  • 如果應用程式並非透過 Google Play 商店發行 (在 Authentication SDK 21.2.0 以上版本)。
  • 如果取得的 SafetyNet 權杖無效 (在 Authentication SDK 21.2.0 以下版本)。
如要進一步瞭解如何設定 Android 應用程式驗證，請參閱 Firebase 說明文件中的「啟用應用程式驗證」一文。

iOS

如果初步的詐欺評估失敗，稽核模式會使用靜默推播通知進行驗證。這個驗證方法會透過靜默推送通知，將權杖傳送至要求裝置上的應用程式。如果應用程式成功收到通知，手機驗證流程就會繼續。如果應用程式未收到推送通知，系統會觸發 reCAPTCHA v2。如果未正確設定靜默推送通知，系統可能會觸發 reCAPTCHA v2。

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

強制執行模式

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

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

啟用 reCAPTCHA SMS defense

如要啟用 reCAPTCHA SMS defense，請按照下列步驟操作：

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

  2. 使用 reCAPTCHA 啟用 reCAPTCHA SMS defense。如需操作說明，請參閱 reCAPTCHA 說明文件「偵測及防範簡訊詐騙」頁面中的「開始前」一節。

  3. 如要為 Firebase 驗證或 Identity Platform 專案啟用 reCAPTCHA 簡訊防護機制，請使用 Google API Explorer 呼叫 updateConfig，方法是在您登入 Google Cloud 控制台的新瀏覽器視窗中，複製並貼上下列 HTTP 網址。

    https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"ENFORCE_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}

    注意：請先在前述 HTTP 網址中替換下列變數，再複製貼上。

    • PROJECT_ID：已啟用身分識別平台的專案 ID。

    • ENFORCE_MODE：您要為 reCAPTCHA 電話驗證強制執行設定的模式。有效值為 OFF、AUDIT 和 ENFORCE。如要啟用 reCAPTCHA SMS defense，請將這個參數設為 AUDIT 或 ENFORCE，並將 useSmsTollFraudProtection 設為 true。

      首次啟用 reCAPTCHA SMS defense 時，建議您將強制執行狀態設為 AUDIT，並確保驗證流程受到保護，再將其設為 ENFORCE。如要進一步瞭解這些模式的運作方式，請參閱「reCAPTCHA 電話驗證強制執行模式」。

    • START_SCORE：要求失敗前可獲得的最高通話詐欺評估分數。您可以將分數設為介於 0.0 和 1.0 之間。分數超過您設定的門檻，就會視為簡訊費用詐欺。舉例來說，如果您設定門檻為 0.3，reCAPTCHA 就會拒絕任何 0.4 以上等級的要求。因此，分數越低，規則就越嚴格。

  4. 如果您在網頁或 Android 上使用 Identity Platform，請透過 Firebase 主控台註冊應用程式：

    • 如果是 Android，請註冊每個使用 Identity Platform 的 Android 套件名稱。

    • 針對網站，請為每個使用 reCAPTCHA 的網域新增授權網域。如要新增已授權網域，請按照下列步驟操作：

      1. 在 Google Cloud 控制台中，前往「Identity Platform」頁面。

        前往 Identity Platform

      2. 依序前往「設定」>「安全性」。

      3. 按一下「新增網域」。

      4. 輸入網域名稱，然後按一下「新增」，儲存網域。

    reCAPTCHA 金鑰佈建程序可能需要幾分鐘的時間才能完成。

  5. 如果您已將強制執行設為稽核模式，建議您監控 reCAPTCHA 的 reCAPTCHA 簡訊防護機制指標，確保流程受到保護。

設定用戶端 SDK

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

網頁版

  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 SMS defense 的 reCAPTCHA 指標

在將 reCAPTCHA 強制執行模式設為強制執行模式前，建議您使用稽核模式並監控專案發出的 reCAPTCHA 指標，確保以簡訊為基礎的驗證流程受到保護。舉例來說，這些指標可協助您判斷是否已正確設定 Identity Platform 與 reCAPTCHA Enterprise API 的整合。您也可以利用這些資訊，微調使用者流量的評分門檻。

檢查專案向 Cloud Monitoring 發出的下列指標，確保 reCAPTCHA SMS defense 功能運作正常：

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

強制執行 reCAPTCHA SMS defense

確認應用程式收到可接受的使用者流量後，您就可以啟用 reCAPTCHA 強制執行機制來保護使用者。請務必確保不會影響現有使用者，包括可能使用舊版應用程式的使用者。

如要在專案或租用戶上啟用 reCAPTCHA 強制執行功能，以便針對以簡訊為基礎的驗證流程執行，請使用 Google APIs Explorer 更新專案設定：

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }

停用 reCAPTCHA SMS defense

如要停用 reCAPTCHA SMS defense，請使用 Google APIs Explorer 更新專案設定：

    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }

如要在使用機器人防護功能時停用 reCAPTCHA SMS defense，請參閱「使用機器人防護功能時停用 reCAPTCHA SMS defense」一文。

使用 reCAPTCHA SMS defense 搭配機器人防護功能

您可以同時使用 reCAPTCHA SMS defense 和 Bot Protection。針對同時使用兩種防護功能的設定，請考量下列事項：

  • 將電話驗證強制執行狀態設為稽核後，Identity Platform 會在要求符合至少一項評估條件時通過。建議您監控 reCAPTCHA 指標，確保 reCAPTCHA 簡訊防護和機器人防護功能都設有合理的分數設定。
  • 如果您將電話驗證強制執行狀態設為強制執行，Identity Platform 只會在要求同時符合兩項評估條件，且要求失敗並關閉而未改用其他驗證方法時，才會通過要求。

如要啟用這兩項功能，請使用 Google APIs Explorer 更新專案設定：

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }

將 ENFORCE_MODE 替換為 reCAPTCHA 電話驗證強制執行模式。有效值為 OFF、AUDIT 和 ENFORCE。如要啟用 reCAPTCHA SMS defense，請將這個參數設為 AUDIT 或 ENFORCE。首次啟用 reCAPTCHA 簡訊防護功能時，建議您將這個參數設為 AUDIT，並確保驗證流程受到保護，然後再將這個參數設為 ENFORCE。如要進一步瞭解這些模式的運作方式，請參閱「reCAPTCHA 電話驗證強制執行模式」。

使用機器人防護功能時停用 reCAPTCHA SMS defense

如果您同時使用 reCAPTCHA SMS defense 和 bot protection，且想停用 reCAPTCHA SMS defense 而不停用 bot protection，請使用 Google API Explorer 更新專案設定：

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

將 ENFORCE_MODE 替換為先前設定的 reCAPTCHA 電話驗證強制執行模式。這個值應為 AUDIT 或 ENFORCE。如要進一步瞭解這些模式的運作方式，請參閱「reCAPTCHA 電話驗證強制執行模式」。

後續步驟