此页面由 Cloud Translation API 翻译。

启用 reCAPTCHA Enterprise

本文档介绍了如何使用 Identity Platform 与 reCAPTCHA 的集成来增强用户的安全性。此功能可提高您的应用防范垃圾内容、滥用行为和其他欺诈活动的弹性。

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

概览

当您配置 Identity Platform 与 reCAPTCHA 的集成时，Identity Platform 会预配基于得分的 reCAPTCHA 网站密钥。当用户使用以下任一操作访问您的应用或网站时，Client SDK 会加载 reCAPTCHA：

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

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

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

准备工作

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

创建服务账号

在启用 reCAPTCHA 之前，您必须为每个应用创建一个服务账号这个项目将使用 reCAPTCHA 并为每个服务账号访问 reCAPTCHA。这样，Identity Platform 就能管理代表您 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 请求会被拒绝。仅当将所有客户端迁移到具有如下支持的 SDK 后，才能启用强制执行： reCAPTCHA 支持。

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

在项目中启用 reCAPTCHA API（如果您尚未启用）。

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

例如：

// 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 的集成。例如：

// 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. 输入该域名，然后点击添加以保存该域名。
网站密钥预配可能需要几分钟才能完成。为了确保请查看指标。

配置 Client SDK

根据应用的平台配置 Client SDK。

Web

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

为了减少 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，您需要 API 级别 19 (KitKat) 或更高级别，以及 Android 4.4 或更高版本。将 Android SDK 与您的应用集成后，它会自动抓取您的 reCAPTCHA 配置，并保护您已配置的提供商。
将以下构建规则添加到应用级 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 配置，并保护您已配置的提供商。
如需将 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 指标

启用 reCAPTCHA 后，请监控您的项目发出的 reCAPTCHA 指标，以确保身份验证流程受到保护。如果 reCAPTCHA 网站密钥配置失败或未创建所需的服务账号，reCAPTCHA 身份验证会失败并开启。

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

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

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

PASSED：表示启用强制执行后允许给定请求。
FAILED_AUDIT：表示在启用 reCAPTCHA 审核模式后，系统拒绝了给定请求。
FAILED_ENFORCE：表示在 reCAPTCHA 时，给定请求被拒强制执行模式。
CLIENT_TYPE_MISSING：表示给定请求缺少客户端类型。这种情况通常发生如果请求是使用未安装 reCAPTCHA 支持。
KEYS_MISSING：表示由于以下原因，无法验证给定请求：检索或生成有效的 reCAPTCHA 密钥时， reCAPTCHA 强制执行已启用。

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

`identitytoolkit.googleapis.com/recaptcha/token_count`

跟踪 Identity Platform 后端。您可以按以下状态进行过滤：

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 的集成会破坏未与 reCAPTCHA 集成的先前应用版本。

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

在 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

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

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

使用 Cloud Run 函数替换 reCAPTCHA 判定结果

除了配置得分阈值之外，您还可以覆盖使用自定义 Cloud Run 函数屏蔽函数对给定令牌进行 reCAPTCHA 判定。如果有指定用户的 reCAPTCHA 得分，这会非常有用登录量可能很少，但该用户是受信任的用户，或者已通过其他意味着可以完成登录。

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

问题排查

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

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

或者，系统可能会根据您当前的配置屏蔽用户。请尝试以下操作：

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