启用 reCAPTCHA Enterprise

本文档介绍了如何使用 Identity Platform 与 reCAPTCHA Enterprise 的集成来增强用户的安全性。此功能可让您的应用更灵活地抵御垃圾内容、滥用行为和其他欺诈活动。

Identity Platform 与 reCAPTCHA Enterprise 的集成可代表您创建 reCAPTCHA Enterprise 评估，以验证用户请求。如需了解价格信息，请参阅 reCAPTCHA Enterprise 价格。

概览

配置 Identity Platform 与 reCAPTCHA Enterprise 的集成时，Identity Platform 会代表您在项目中预配基于得分的 reCAPTCHA Enterprise 网站密钥。当用户通过以下任一操作访问您的应用或网站时，客户端 SDK 会加载 reCAPTCHA Enterprise：

操作	方法
电子邮件地址和密码登录	`signInWithPassword`
电子邮件地址和密码注册	`signUpPassword`
电子邮件链接登录	`getOobCode`
重设密码	`getOobCode`

然后，reCAPTCHA 会向 Identity Platform 提供风险信号，以根据您的配置和风险容忍度评估请求的风险。

如需了解详情，请参阅 reCAPTCHA Enterprise 概览。

准备工作

为用户配置电子邮件登录。

创建服务账号

在启用 reCAPTCHA Enterprise 之前，您必须为将使用 reCAPTCHA 的每个项目创建一个服务帐号，并为每个服务帐号授予对 reCAPTCHA Enterprise 的访问权限。这样，Identity Platform 就可以代表您管理 reCAPTCHA 密钥。

如需创建服务账号，请执行以下操作：

使用 Google Cloud CLI 创建服务帐号：

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

将 PROJECT_ID 替换为该项目的 ID。

向服务帐号授予对 reCAPTCHA Enterprise 的访问权限：

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 Enterprise

reCAPTCHA 有两种模式可帮助您保护用户：

审核：启用后，Identity Platform 会在您的项目中创建一个或多个 reCAPTCHA Enterprise 密钥，用于评估流向 Identity Platform API 的流量，而不会屏蔽任何请求。使用审核模式下发出的指标来确定是否应启用 reCAPTCHA 强制执行。
强制执行：启用后，Identity Platform 会在您的项目中创建一个或多个 reCAPTCHA Enterprise 密钥，用于评估通向 Identity Platform API 的流量。不包含 reCAPTCHA 令牌的 API 请求会被拒绝。请仅在将所有客户端迁移到具有 reCAPTCHA Enterprise 支持的 SDK 后，才启用强制执行。

如需启用 reCAPTCHA Enterprise，请执行以下操作：

如果您还没有在项目中启用 reCAPTCHA Enterprise API，请执行此操作。

使用 Admin SDK 为项目启用 Identity Platform 与 reCAPTCHA Enterprise 的集成。Node.js Admin SDK 11.7.0 及更高版本提供 reCAPTCHA Enterprise 支持。

例如：

// Get project config
const getProjectConfig = () => {
  getAuth().projectConfigManager().getProjectConfig()
  .then((response) => {
    console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error getting project config:', error);
  });
}

// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      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);
  });
}

使用 Admin SDK 为租户启用 Identity Platform 与 reCAPTCHA Enterprise 集成。例如：

// Update tenant with reCAPTCHA config
const updateTenantRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateTenantWithRecaptchaConfig = () => {
  getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
  .then((response) => {
    console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating the tenant:', error);
  });
}

替换以下内容：

TENANT_ID：租户 ID

如果您在 Apple 平台或 Android 上使用 Identity Platform，则必须从 Firebase 控制台注册您的应用：
- 对于 Apple 平台，请注册使用 Identity Platform 的每个软件包 ID
- 对于 Android，请注册使用 Identity Platform 的每个 Android 软件包名称
如果您使用的是 Web 版 Identity Platform，则必须为每个使用 reCAPTCHA 的网域添加一个已获授权的网域。如需添加已获授权的网域，请执行以下操作：
1. 在 Google Cloud 控制台中，转到 Identity Platform 页面。
  
  转到 Identity Platform
2. 依次转到设置 > 安全。
3. 点击添加网域。
4. 输入域名，然后点击添加以保存此域名。
网站密钥配置可能需要几分钟才能完成。为了确保您的流受到保护，请检查metrics。

配置客户端 SDK

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

网站

请更新到最新版本的 Web SDK。JavaScript SDK 9.20.0 及更高版本提供 reCAPTCHA Enterprise 支持。将 Web SDK 与应用集成后，它会自动提取您的 reCAPTCHA Enterprise 配置并保护您配置的提供方。

为了减少 SDK 发出的网络调用次数并更好地收集 reCAPTCHA 信号，我们建议您按如下方式明确配置：

import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Auth
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 版本 31.5.0 或更高版本。若要支持 reCAPTCHA Enterprise，要求 API 级别为 19 (KitKat) 或更高级别，以及 Android 4.4 或更高版本。将 Android SDK 与应用集成后，它会自动提取您的 reCAPTCHA Enterprise 配置并保护您配置的提供程序。
将以下构建规则添加到应用级 build.gradle 文件的依赖项部分：
```
implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
```
请务必使用 reCAPTCHA SDK 18.4.0 或更高版本。

为了减少 SDK 发出的网络调用次数，并提高 reCAPTCHA 信号收集效率，我们建议按如下方式明确配置：

Kotlin：

// Initialize Firebase Auth
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 Auth
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 10.14.0 或更高版本。将 iOS SDK 与应用集成后，它会自动提取您的 reCAPTCHA Enterprise 配置并保护您配置的提供方。
要将 reCAPTCHA iOS SDK 集成到您的应用中，请参阅准备环境。
确保链接器标志中列出了 -ObjC。依次转到“目标”>“构建设置”>“全部”>“关联”，然后验证 Other Linker Flags 是否显示 -ObjC。

为了减少 SDK 发出的网络调用次数，并提高 reCAPTCHA 信号收集效率，我们建议您明确对其进行配置，如下所示：

Swift：

// Initialize Firebase Auth
try await Auth.auth().initializeRecaptchaConfig()

Objective-C：

// Initialize Firebase Auth
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Auth initialization finished
}];

reCAPTCHA Enterprise 指标

启用 reCAPTCHA Enterprise 后，请监控项目发出的 reCAPTCHA 指标，以确保身份验证流程受到保护。如果 reCAPTCHA 网站密钥预配失败，或者未创建必需的服务帐号，则 reCAPTCHA 身份验证无法打开。

请检查项目向 Cloud Monitoring 发出的以下指标，确保 reCAPTCHA 身份验证正常运行：

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

跟踪 reCAPTCHA Enterprise 返回的不同判定结果。如果存在令牌，则生成判定结果。您可以按以下判定结果进行过滤：

PASSED：表示在强制执行已启用的情况下，允许指定的请求。
FAILED_AUDIT：表示在启用 reCAPTCHA 审核模式后，给定请求会被拒绝。
FAILED_ENFORCE：表示启用 reCAPTCHA 强制执行模式后，给定请求会被拒绝。
CLIENT_TYPE_MISSING：表示在启用 reCAPTCHA 强制执行后，给定请求缺少客户端类型。如果请求是使用不支持 reCAPTCHA 的过时客户端 SDK 版本发送的，通常就会发生这种情况。
KEYS_MISSING：表示如果启用了 reCAPTCHA 强制执行，则表示给定请求因无法检索或生成有效的 reCAPTCHA 密钥而无法验证。

如需修改得分范围以更改通过与失败判定结果的比率，请参阅启用 reCAPTCHA Enterprise。

`identitytoolkit.googleapis.com/recaptcha/token_count`

跟踪 Identity Platform 后端收到的 reCAPTCHA Enterprise 令牌的数量和状态。您可以按以下状态进行过滤：

VALID：表示传入的 reCAPTCHA 令牌有效。
EXPIRED：表示传入的 reCAPTCHA 令牌已过期。令牌过期可能表示客户端网络问题或滥用。
DUPLICATE：表示传入的 reCAPTCHA 令牌重复。令牌重复可能表示客户端网络问题或滥用。
INVALID：表示传入的 reCAPTCHA 令牌无效。无效令牌可能表示存在滥用行为。
MISSING：表示给定请求中不存在 reCAPTCHA 令牌。缺少令牌可能表示客户端应用已过时。
UNCHECKED：表示 reCAPTCHA 令牌因 CLIENT_TYPE_MISSING 或 KEYS_MISSING 判定结果而未检查。

如果您的应用已成功向用户发布，您将看到包含有效令牌的流量。有效令牌的数量可能与使用新版应用的用户数量成正比。

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

跟踪 reCAPTCHA 得分的分布情况。这有助于您为自己的配置定义最佳得分范围。

您可以根据这些指标来判断您是否可以启用强制执行。在启用强制执行之前，您应该考虑以下事项：

如果大多数近期请求都具有有效令牌，并且 PASSED 与 FAILED_AUDIT 或 FAILED_ENFORCE 判定结果的比率对您的业务案例而言是可接受的，请考虑启用强制执行。
如果近期的大部分请求可能来自过时的客户端，请考虑等待更多用户更新其应用，然后再启用强制执行。强制执行 Identity Platform 与 reCAPTCHA Enterprise 的集成会导致之前未与 reCAPTCHA Enterprise 集成的应用版本中断。

如需查看这些指标，请执行以下操作：

在 Google Cloud 控制台中，转到 Metrics Explorer 页面。

转到 Metrics Explorer
在选择指标中，输入 Identity Toolkit Tenant。如果您使用的是多租户，则可以将 tenant_name 留空，以查看每个租户以及父项目的指标。

启用强制执行

确认应用能够接收可接受的用户流量后，您可以启用 reCAPTCHA 强制执行来保护用户。确保您不会干扰现有用户，包括可能正在使用旧版应用的用户。

如需为项目或租户启用 reCAPTCHA 强制执行，请使用 Admin SDK 运行以下命令：

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

停用 reCAPTCHA Enterprise

如需停用 reCAPTCHA Enterprise，请使用 Admin SDK 运行以下命令：

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

使用 Cloud Functions 替换 reCAPTCHA Enterprise 判定结果

除了配置得分阈值之外，您还可以使用自定义 Cloud Functions 屏蔽函数来替换给定令牌的 reCAPTCHA Enterprise 判定结果。如果指定用户登录的 reCAPTCHA 得分可能较低，但用户可信或已通过其他方式通过验证，因此可以完成登录，则此操作非常有用。

如需详细了解如何使用 reCAPTCHA Enterprise 配置屏蔽函数，请参阅使用屏蔽 Cloud Functions 函数扩展 Firebase Authentication。

问题排查

用户无法登录、注册或重置密码

用户可能使用的应用版本可能已过时。如果您尚未提供使用客户端 SDK 的更新版本，请立即关闭强制执行模式。否则，请让用户更新应用。

此外，用户可能会被根据您当前的配置而被屏蔽。请尝试以下操作：

请考虑通过调整更宽松的配置。reCAPTCHA 密钥得分。
让用户尝试其他设备、浏览器或网络。
请还原到审核模式并监控指标，然后再重新启用强制执行模式。