将 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 机器人防范功能进行应用验证。如果用户请求通过了聊天机器人防范评估，Identity Platform 会向用户的手机发送一条包含验证码的短信。如果请求未通过聊天机器人防范评估，并且您使用的是客户端 SDK，系统会触发后备验证方法来完成手机身份验证流程。接受的回退方法取决于应用的平台。

客户端 SDK 会在以下情况下触发回退验证方法：

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

确保已为应用的平台设置回退验证方法，并准备好在必要时由客户端 SDK 触发。

强制模式

当您将手机身份验证强制执行设置为强制模式时，Identity Platform 会使用 reCAPTCHA 机器人防范功能进行应用验证。如果用户请求通过了聊天机器人防范评估，Identity Platform 会向用户的手机发送一条包含验证码的短信。如果请求未通过聊天机器人防范评估，Identity Platform 会屏蔽该请求，并且不会发送包含验证码的短信。

强制执行模式不需要回退验证，因此您无需为应用设置任何其他验证方法。不过，如果您决定将应用的 reCAPTCHA 模式更改为 AUDIT 或 OFF，我们建议您为 Web 应用设置 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 为tenant使用相同的配置方法启用聊天机器人防范功能。如需详细了解如何更新租户，请参阅更新租户。

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 为tenant使用相同的配置方法启用聊天机器人防范功能。如需详细了解如何更新租户，请参阅更新租户。

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 应用中使用 reCAPTCHA 进行手机验证。

   将 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.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'
  }
};