将 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 保护的身份验证流程类型，确保您已设置以下内容：

对于电子邮件地址与密码身份验证流程，请确保您已为用户配置电子邮件地址登录。
对于基于短信的身份验证流程，请确保您已至少加入以下其中一项：
- 用户电话号码登录。
- 适用于 Web、 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：项目 ID
PROJECT_NUMBER：项目账号

reCAPTCHA 机器人防护模式

reCAPTCHA 机器人防护有两种模式，可帮助您保护用户：审核模式 和 强制执行模式。这些模式的行为因身份提供方而异。

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

对于电子邮件地址与密码身份验证流程，审核模式和强制执行模式的行为如下所示。

审核模式

当您将电子邮件地址与密码强制执行设置为审核模式时，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 触发。

Web

如果初始机器人防护评估失败，审核模式会依赖 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 验证程序，以确保在您决定将应用的 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 软件包名称
如果您在 Web 上使用 Identity Platform，则必须为每个使用 reCAPTCHA 的网域添加已获授权的网域。如需添加已获授权的网域，请执行以下操作：
1. 在 Google Cloud 控制台中，前往 Identity Platform 页面。
  
  前往 Identity Platform
2. 依次前往设置 > 安全。
3. 点击添加网域 。
4. 输入网域名，然后点击添加以保存网域。
预配 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 软件包名称
如果您在 Web 上使用 Identity Platform，则必须为每个使用 reCAPTCHA 的网域添加已获授权的网域。如需添加已获授权的网域，请执行以下操作：
1. 在 Google Cloud 控制台中，前往 Identity Platform 页面。
  
  前往 Identity Platform
2. 依次前往设置 > 安全。
3. 点击添加网域 。
4. 输入网域名，然后点击添加以保存网域。
预配 reCAPTCHA 密钥可能需要几分钟才能完成。
如果您已将强制执行设置为审核模式，我们建议您监控机器人防护的 reCAPTCHA 指标，以确保您的流程受到保护。

配置客户端 SDK

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

Web

更新到最新版本的 Web SDK。
- JavaScript SDK 9.20.0 版及更高版本支持在 Web 应用中对电子邮件地址与密码身份验证使用 reCAPTCHA。
- JavaScript SDK 11 及更高版本支持在 Web 应用中对手机号码身份验证使用 reCAPTCHA。
将 Web 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。reCAPTCHA 支持在 Android 应用中对电子邮件地址与密码身份验证和手机号码身份验证使用 Android SDK 23.1.0 版及更高版本。

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

将 Android SDK 与应用集成后，SDK 会自动提取 reCAPTCHA 配置，并为已配置的提供商启用保护。
将以下 build 规则添加到应用级 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。依次前往目标 > 构建设置 > 所有 > 链接，然后验证 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 判定结果

除了配置得分阈值之外，您还可以使用屏蔽函数根据自定义因素允许或屏蔽流程，从而替换给定令牌的 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。