將 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
:專案 IDPROJECT_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 v2 進行驗證。因此,您必須設定 reCAPTCHA 驗證器 (RecaptchaVerifier
),並將其傳遞至下列電話號碼驗證作業:
verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber
auth/argument-error
。如要進一步瞭解如何設定 reCAPTCHA 驗證器,請參閱 Firebase 說明文件中的「設定 reCAPTCHA 驗證器」。
Android
如果初步的機器人防護評估失敗,稽核模式會根據 Play Integrity API 驗證您的應用程式。如果驗證失敗,系統會觸發 reCAPTCHA 第 2 版。 在下列情況下,系統可能會觸發 reCAPTCHA v2:
- 如果使用者的裝置未安裝 Google Play 服務。
- 如果應用程式不是透過 Google Play 商店發布 (適用於 Authentication SDK v21.2.0 以上版本)。
- 如果取得的 SafetyNet 權杖無效 (適用於 21.2.0 之前的 Authentication SDK 版本)。
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 的網域新增已授權網域。如要新增授權網域,請按照下列步驟操作:
前往 Google Cloud 控制台的「Identity Platform」頁面。
依序前往「設定」>「安全性」。
按一下「新增網域」。
輸入網域名稱,然後按一下「新增」儲存網域。
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,透過相同的設定方法為租戶啟用機器人防護功能。如要進一步瞭解如何更新租戶,請參閱「更新租戶」。
如果您在 iOS 或 Android 上使用 Identity Platform,請務必透過 Firebase 控制台註冊應用程式:
- 如果是 iOS,請註冊使用 Identity Platform 的每個軟體包 ID
- 如果是 Android,請註冊每個使用 Identity Platform 的 Android 套件名稱
如果您在網路上使用 Identity Platform,則必須為每個使用 reCAPTCHA 的網域新增授權網域。如要新增已授權網域,請按照下列步驟操作:
前往 Google Cloud 控制台的「Identity Platform」頁面。
依序前往「設定」>「安全性」。
按一下「新增網域」。
輸入網域名稱,然後按一下「新增」儲存網域。
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 判決
除了設定分數門檻,您也可以使用自訂 Cloud Run 函式封鎖函式,覆寫特定權杖的 reCAPTCHA 判決。如果特定使用者登入時的 reCAPTCHA 分數偏低,但使用者值得信任或已透過其他方式驗證,因此允許完成登入,這項功能就很有幫助。
如要進一步瞭解如何使用 reCAPTCHA 設定封鎖函式,請參閱「使用封鎖 Cloud Functions 擴充 Firebase Authentication」。
後續步驟
- 針對簡訊驗證流程啟用 reCAPTCHA SMS defense。
- 瞭解如何使用自己的 reCAPTCHA 金鑰。
- 進一步瞭解如何監控 reCAPTCHA 指標。
- 進一步瞭解 reCAPTCHA。