将 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，Identity Platform 会触发备用验证方法来完成手机身份验证流程。接受的后备方法取决于应用的平台。

在以下情况下，客户端 SDK 会触发备用验证方法：

• 缺少 reCAPTCHA 令牌。
• reCAPTCHA 令牌无效或已过期。
• reCAPTCHA 令牌未通过得分阈值。
• reCAPTCHA 未正确配置。

确保为应用平台设置了备用验证方法，并且这些方法已准备就绪，可在必要时由客户端 SDK 触发。

强制模式

当您将手机身份验证强制执行模式设置为“强制”模式时，Identity Platform 会使用 reCAPTCHA 机器人防护功能进行应用验证。如果用户请求通过了话费欺诈评估，系统会发送短信验证码。如果用户请求未通过话费欺诈评估，Identity Platform 会阻止该请求，并且不会发送包含验证码的短信。

在强制执行模式下，无需进行回退验证，您无需为应用设置任何其他验证方法。不过，我们建议为 Web 应用设置 reCAPTCHA 验证器，以确保在您决定将应用的 reCAPTCHA 模式更改为 AUDIT 或 OFF 时，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. 如需为项目启用机器人保护功能，请使用 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，通过相同的配置方法为租户启用机器人保护功能。如需详细了解如何更新租户，请参阅更新租户。

3. 如果您在 iOS 或 Android 上使用 Identity Platform，则必须通过 Firebase 控制台注册您的应用：

   • 对于 iOS，注册使用 Identity Platform 的每个软件包 ID
   • 对于 Android，注册使用 Identity Platform 的每个 Android 软件包名称

   如果您在 Web 上使用 Identity Platform，则必须为使用 reCAPTCHA 的每个网域添加已获授权的网域。如需添加已获授权的网域，请执行以下操作：

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

      前往 Identity Platform

   2. 依次前往设置 > 安全。

   3. 点击添加网域。

   4. 输入域名，然后点击添加以保存该域名。

   reCAPTCHA 密钥配置可能需要几分钟才能完成。

4. 如果您已将强制执行模式设置为审核模式，建议您监控用于防范机器人的 reCAPTCHA 指标，以确保您的流程受到保护。

Web

1. 更新到最新版本的 Web SDK。

   • JavaScript SDK 9.20.0 版及更高版本支持在 Web 应用中对电子邮件地址和密码身份验证使用 reCAPTCHA。
   • JavaScript SDK 11 版及更高版本支持在 Web 应用中通过 手机号码进行身份验证。

   将 Web 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 SDK 版本 23.1.0 及更高版本支持在 Android 应用中通过电子邮件地址和密码进行身份验证以及通过手机进行身份验证时使用 reCAPTCHA。

   此外，reCAPTCHA 支持需要 API 级别 23 (Marshmallow) 或更高级别以及 Android 6 或更高版本。

   将 Android SDK 与应用集成后，该 SDK 会自动提取 reCAPTCHA 配置，并为已配置的提供程序启用保护功能。

2. 将以下 build 规则添加到应用级 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。依次前往目标 > 构建设置 > 所有 > 链接，然后验证 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 强制执行，请使用 Admin SDK 运行以下命令：

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

电子邮件地址与密码提供方

如需针对电子邮件地址-密码身份验证流程停用机器人保护功能，请使用 Admin SDK 运行以下命令：

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

电话服务提供商

如需针对基于短信的身份验证流程停用机器人保护功能，请使用 Admin SDK 运行以下命令：

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