启用 reCAPTCHA Enterprise

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

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

概览

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

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

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

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

准备工作

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

创建服务账号

在启用 reCAPTCHA 之前，您必须为每个将使用 reCAPTCHA 的项目创建一个服务帐号，并为每个服务帐号授予对 reCAPTCHA 的访问权限。这样，Identity Platform 就可以代表您管理 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.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 后，才能启用强制执行。

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

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

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

    例如：

    // 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);
  });
}

  3. 使用 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

  4. 如果您是在 Apple 平台或 Android 上使用 Identity Platform，则必须从 Firebase 控制台注册您的应用：

  5. 如果您使用的是 Web 版 Identity Platform，则必须为每个使用 reCAPTCHA 的网域添加一个已获授权的网域。如需添加已获授权的网域，请执行以下操作：

    1. 在 Google Cloud 控制台中，前往 Identity Platform 页面。

      转到 Identity Platform

    2. 依次转到设置 > 安全。

    3. 点击添加网域。

    4. 输入该域名，然后点击添加以保存该域名。

    网站密钥配置可能需要几分钟才能完成。为了确保您的数据流受到保护，请查看metrics。

配置 Client SDK

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

Web

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

  2. 为了减少 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 设备

  1. 更新到 Android SDK 31.5.0 或更高版本。reCAPTCHA 支持要求 API 级别 19 (KitKat) 或更高版本以及 Android 4.4 或更高版本。将 Android SDK 与应用集成后，它会自动提取您的 reCAPTCHA 配置并保护您配置的提供方。

  2. 将以下构建规则添加到应用级 build.gradle 文件的依赖项部分：

    implementation 'com.google.android.recaptcha:recaptcha:18.4.0'

    请务必使用 reCAPTCHA SDK 18.4.0 或更高版本。

  3. 为了减少 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

  1. 更新至 iOS SDK 10.14.0 或更高版本。 将 iOS SDK 与您的应用集成后，它会自动提取您的 reCAPTCHA 配置并保护您配置的提供方。

  2. 如需将 reCAPTCHA iOS SDK 集成到您的应用中，请参阅准备环境。

  3. 确保链接器标志上列出了 -ObjC。依次前往“Target”>“Build Settings”>“All”>“关联”，然后验证 Other Linker Flags 是否显示 -ObjC。

  4. 为了减少 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 身份验证将无法打开。

通过检查项目发送到 Cloud Monitoring 的以下指标，确保 reCAPTCHA 身份验证正常运行：

identitytoolkit.googleapis.com/recaptcha/verdict_count

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

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

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

identitytoolkit.googleapis.com/recaptcha/token_count

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

  • 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 集成的先前应用版本。

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

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

    转到 Metrics Explorer

  2. 在选择指标中，输入 Identity Toolkit 租户。如果您使用的是多租户，则可以通过将 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 Functions 替换 reCAPTCHA 判定结果

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

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

问题排查

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

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

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

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