将 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 概览。

重要提示： 在本文档中，您将使用 Google Cloud的以下收费组件：

• reCAPTCHA Enterprise
• Identity Platform

如需根据您的预计使用量来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

准备工作

根据您要使用 reCAPTCHA 保护的身份验证流程类型，请确保您已设置以下内容：

• 对于电子邮件地址-密码身份验证流程，请确保您已配置用户电子邮件地址登录。

• 对于基于短信的身份验证流程，请确保您已至少加入以下其中一项：

  • 为用户启用手机登录功能。
  • 为您的 Web、Android 或 iOS 应用启用多重身份验证。

创建服务账号

Identity Platform 与 reCAPTCHA Enterprise API 的集成需要为每个将使用 reCAPTCHA 的项目创建一个 Identity Platform 服务账号。这样，Identity Platform 就可以代表您管理 reCAPTCHA 密钥。如果您已创建服务账号，请向其授予对 reCAPTCHA 的访问权限。

如果您尚未创建服务账号，或者您有其他想要使用 reCAPTCHA 保护的项目，请执行以下操作：

1. 使用 Google Cloud CLI 创建服务账号：

   gcloud beta services identity create \
       --service=identitytoolkit.googleapis.com \
       --project=PROJECT_ID
   

   将 PROJECT_ID 替换为项目的 ID。

2. 为该服务账号授予对 reCAPTCHA 的访问权限：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit. \
       --role=roles/identitytoolkit.serviceAgent
   

   替换以下内容：

   • PROJECT_ID：项目 ID
   • PROJECT_NUMBER：项目账号

各提供方的 reCAPTCHA 机器人防护行为

reCAPTCHA 机器人防护行为取决于您配置的身份提供方：

电子邮件地址/密码提供商

对于电子邮件密码身份验证流程，reCAPTCHA 机器人防护支持两种模式：审核和强制执行。

审核模式

将电子邮件密码强制执行设置为审核模式时，Identity Platform 会在您的项目中创建一个或多个 reCAPTCHA 密钥，用于评估对 Identity Platform API 的流量，而不会阻止任何请求。使用在审核模式下发出的指标来确定是否应启用 reCAPTCHA 强制执行。

实施模式

将电子邮件密码强制执行设置为强制执行模式后，Identity Platform 会在您的项目中创建一个或多个 reCAPTCHA 密钥，用于评估 Identity Platform API 的流量。不包含 reCAPTCHA 令牌的 API 请求会被拒绝。只有在将所有客户端迁移到支持 reCAPTCHA 的 SDK 后，才能启用强制执行。

电话服务提供商

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

通过将 phoneEnforcementState 设置为 ENFORCE 并将 useSmsBotScore 设置为 true 为手机身份验证流程启用漫游器防护功能时，Identity Platform 会使用 reCAPTCHA 漫游器防护功能进行应用验证。如果用户的请求通过了机器人防护评估，系统会发送短信验证码。如果用户的请求未通过机器人防护评估，Identity Platform 会屏蔽该请求，并且不会发送包含验证码的短信。

为手机身份验证流程启用机器人防护后，无需进行后备验证，您也无需为应用设置任何其他验证方法。不过，我们建议您为 Web 应用设置 reCAPTCHA 验证方，以确保在您决定停用机器人防护时 reCAPTCHA v2 可用。

设置 Identity Platform 与 reCAPTCHA Enterprise API 的集成

如需设置 Identity Platform 与 reCAPTCHA Enterprise API 的集成，请执行以下任务：

• 使用 Admin SDK 设置 reCAPTCHA 强制执行状态并启用漫游器防护。
• 为应用的平台配置客户端 SDK。

对于电子邮件密码身份验证流程，我们建议您先在审核模式下启用 reCAPTCHA 强制执行，并监控项目发出的 reCAPTCHA 指标，以避免中断用户流量，同时验证身份验证流程是否受到保护。验证身份验证流程受到保护后，将漫游器防护设置为 ENFORCE。对于手机身份验证流程，请通过将 phoneEnforcementState 设置为 ENFORCE 并将 useSmsBotScore 设置为 true 来启用漫游器防护，并监控 reCAPTCHA 指标以微调得分阈值。

启用 reCAPTCHA 机器人防护

重要提示：除非 reCAPTCHA 已停用，否则请勿修改或删除名为 Key for Identity Platform integration with reCAPTCHA 的 reCAPTCHA 密钥。这样做会阻止 Identity Platform 应用 reCAPTCHA 保护。此外，Identity Platform SDK 无法通过您自行生成的 reCAPTCHA 密钥生成令牌。

电子邮件地址/密码提供商

如需为电子邮件密码身份验证流程启用 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 软件包名称

   如果您在 Web 上使用 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',
       managedRules: [{
         endScore: END_SCORE,
         action: 'BLOCK'
       }],
       useSmsBotScore: true,
     }
   };
   let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
   

   将 END_SCORE 替换为请求在失败之前可以具有的最低漫游器保护评估分数。您可以将此分数设置为 0.0 到 1.0 之间的值。例如，如果您将阈值设置为 0.6，则 reCAPTCHA 会使任何得分为 0.5 或更低的请求失败。因此，您设置的分数越高，规则就越严格。

   将 phoneEnforcementState 设置为 ENFORCE，并将 useSmsBotScore 设置为 true，即可为基于短信的身份验证流程启用机器人防护措施。如需详细了解手机服务提供商的违规处置措施如何运作，请参阅各服务提供商的 reCAPTCHA 机器人防护行为。

   您还可以使用 Admin SDK，通过相同的配置方法为租户启用机器人防护。如需详细了解如何更新租户，请参阅更新租户。

   注意：Identity Platform 不支持在移动平台上对多个租户使用手机验证和短信多重身份验证。

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 指标，确保您的流程受到保护。

配置客户端 SDK

根据应用的平台配置客户端 SDK。

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 规则添加到应用级 build.gradle 文件的 dependencies 部分：

   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 指标以实现机器人防护

监控项目发出的 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 漫游器防护

对于您最初在 AUDIT 模式下配置的电子邮件密码身份验证流程，在验证应用收到可接受的用户流量后，您可以将 emailPasswordEnforcementState 切换为 ENFORCE，以阻止未通过 reCAPTCHA 评估的请求。确保您不会干扰现有用户，包括可能正在使用旧版应用的用户。

如需为项目或租户的邮箱/密码身份验证流程启用 reCAPTCHA 强制执行，请使用 Admin SDK 运行以下代码：

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

停用 reCAPTCHA 机器人防护

电子邮件地址/密码提供商

如需为电子邮件密码身份验证流程停用机器人防护，请使用 Admin SDK 运行以下命令：

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

电话服务提供商

如需为基于短信的身份验证流程停用所有手机 reCAPTCHA 保护（包括漫游器保护），请使用 Admin SDK 运行以下命令：

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

如果您还在使用 reCAPTCHA SMS defense，并希望在停用漫游器防护的同时保持其启用状态，请将 useSmsBotScore 设置为 false，并将 phoneEnforcementState 保持设置为 ENFORCE：

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

使用 Cloud Run functions 替换 reCAPTCHA 判定结果

除了配置分数阈值之外，您还可以使用屏蔽函数根据自定义因素允许或屏蔽流程，从而替换给定令牌的 reCAPTCHA 判定结果。如果给定用户登录的 reCAPTCHA 评分可能较低，但用户受信任或已通过其他方式进行验证，因此可以完成登录，则此功能非常有用。

以下示例展示了如何使用屏蔽函数替换 reCAPTCHA 判定结果：

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

后续步骤

• 为基于短信的身份验证流程启用 reCAPTCHA SMS defense。
• 了解如何使用您自己的 reCAPTCHA 密钥。
• 详细了解如何监控 reCAPTCHA 指标。
• 详细了解 reCAPTCHA。