使用入门：将 App Check 与 reCAPTCHA Enterprise 搭配使用（Web 应用）

本页介绍了如何使用 reCAPTCHA Enterprise 提供方在 Web 应用中启用 App Check。启用 App Check 有助于确保只有您的应用可以访问项目的后端资源。请查看此功能的概览。

请注意，App Check 使用基于 reCAPTCHA Enterprise 分数的网站密钥，因此对用户来说是不可见的。reCAPTCHA Enterprise 提供方永远不会要求用户进行验证。

如果您的应用场景需要 App Check 未实现的 reCAPTCHA Enterprise 功能，或者您想将 App Check 与自己的自定义提供方搭配使用，请参阅实现自定义 App Check 提供方。

1. 设置您的 Firebase 项目

将 Firebase 添加到您的 JavaScript 项目（如果尚未添加）。
打开 Cloud 控制台的 reCAPTCHA Enterprise 部分，并执行以下操作：
1. 如果系统提示您启用 reCAPTCHA Enterprise API，请执行此操作。
2. 创建一个网站类型的密钥。您需要指定用于托管 Web 应用的网域。请勿选择“使用复选框验证”选项。
在 Firebase 控制台的 App Check 部分中注册您的应用，以便将 App Check 与 reCAPTCHA Enterprise 提供方搭配使用。您需要提供上一步中获取的网站密钥。

您通常需要注册项目的所有应用，因为在您为 Firebase 产品启用强制执行后，只有注册的应用才能访问产品的后端资源。
可选：在应用注册设置中，为提供方颁发的 App Check 令牌设置自定义存留时间 (TTL)。您可以将 TTL 设置为 30 分钟到 7 天之间的任何值。更改此值时，请注意权衡以下几个方面：
- 安全性：较短的 TTL 可以提供更强的安全性，因为它可以缩短攻击者可能滥用已泄露或者已被拦截的令牌的时长。
- 性能：较短的 TTL 意味着您的应用将更频繁地执行证明操作。由于每次执行应用证明过程都会增加网络请求的延迟时间，因此短 TTL 可能会影响应用的性能。
- 配额和费用：较短的 TTL 和频繁的重新证明会更快地耗尽您的配额，而对于付费服务，费用可能更高。请参阅配额和限制。
对于大多数应用而言，默认的 TTL（1 小时）比较合理。请注意，App Check 库会在达到 TTL 时长约一半时刷新令牌。

配置高级设置（可选）

当用户访问您的 Web 应用时，reCAPTCHA Enterprise 会评估用户互动所带来的风险等级，并返回一个介于 0.0 和 1.0 之间的得分，增量为 0.1。1.0 分表示互动风险低，很可能是合法的；而 0.0 分表示互动风险高，可能具有欺诈性。借助 App Check，您可以配置应用风险阈值，以便可调整您对此风险的容忍度。

对于大多数应用场景，建议使用默认阈值 0.5。如果您的应用场景需要调整，可以在 Firebase 控制台的 App Check 部分中为每个 Web 应用进行配置。

详细信息

App Check 会使用您配置的应用风险阈值作为用户互动被视为合法所需的最低 reCAPTCHA Enterprise 得分。所有 reCAPTCHA Enterprise 得分严格低于所配置阈值的请求都将被拒绝。调整应用风险阈值时，请注意以下几点：

在您向项目添加 Google Cloud Billing 账号之前，在 11 个可能的 reCAPTCHA Enterprise 得分级别中，只有以下 4 个得分级别可用：0.1、0.3、0.7 和 0.9。在此期间，App Check 将相应地仅允许应用风险阈值设置为 0.1、0.3、0.5、0.7 和 0.9。对于大多数应用场景，仍建议将应用风险阈值设置为 0.5。
- 如需启用全部 11 个 reCAPTCHA Enterprise 得分级别，请向您的项目添加 Google Cloud Billing 账号。完成此操作的一种方法是升级到 Blaze 定价方案。完成上述操作后，App Check 将允许您以 0.1 为增量配置介于 0.0 和 1.0 之间的任何应用风险阈值。
  
  注意：将 Google Cloud Billing 账号添加到项目后，系统会对您的项目触发自动安全审核。如需了解详情，请参阅 reCAPTCHA Enterprise 文档。
如需监控 Web 应用的 reCAPTCHA Enterprise 高得分和低得分的分布情况，请访问 Google Cloud 控制台中的 reCAPTCHA Enterprise 页面，然后选择您的 Web 应用使用的网站密钥。
如果您对应用风险的容忍度较低，请向左移动滑块以提高应用风险阈值。
- 不建议使用 1.0 值，因为此设置也可能会拒绝不满足此高信任度阈值的合法用户访问。
警告：在提高应用风险阈值之前，您应考虑暂时不对当前强制执行的所有服务强制执行 App Check 保护，以免干扰合法用户。您应监控 App Check 请求指标，以验证流量是否未中断，然后再恢复强制执行。
如果您对应用风险的容忍度较高，请向右移动滑块以降低应用风险阈值。
- 不建议使用 0.0 值，因为此设置会停用滥用防护功能。

如需了解更多详情，请参阅 reCAPTCHA Enterprise 文档。

2. 将 App Check 库添加到您的应用中

将 Firebase 添加到您的 Web 应用（如果尚未添加）。请务必导入 App Check 库。

3. 初始化 App Check

在访问 Firebase 服务之前，请将以下初始化代码添加到您的应用中。您需要将您在 Cloud 控制台中创建的 reCAPTCHA Enterprise 网站密钥传递给 activate()。

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to initializeAppCheck().
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(/* reCAPTCHA Enterprise site key */),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to activate().
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    /* reCAPTCHA Enterprise site key */
  ),
  true // Set to true to allow auto-refresh.
);

后续步骤

将 App Check 库安装到您的应用中之后，请部署该应用。

更新后的客户端应用会开始将 App Check 令牌随其发出的每个请求一起发送到 Firebase；不过，您在 Firebase 控制台的 App Check 部分中启用强制执行之前，Firebase 产品并不会要求令牌必须有效。

监控指标并启用强制执行

不过，在启用强制执行之前，您应该确保这样做不会干扰现有的合法用户。另一方面，如果您发现自己的应用资源被非法使用，建议您尽快启用强制执行。

为帮助您做出相关决策，建议您查看自己使用的服务的 App Check 指标：

针对 Firebase AI Logic、Data Connect、Realtime Database、Cloud Firestore、Cloud Storage、Authentication、Google Identity for iOS、Maps JavaScript API 和 Places API（新版）监控 App Check 请求指标。
监控 Cloud Functions 的 App Check 请求指标。

启用 App Check 强制执行

在了解 App Check 对用户有何影响并为后续操作做好准备之后，您便可以启用 App Check 强制执行：

针对 Firebase AI Logic、Data Connect、Realtime Database、Cloud Firestore、Cloud Storage、Authentication、Google Identity for iOS、Maps JavaScript API 和 Places API（新版）启用 App Check 强制执行。
为 Cloud Functions 启用 App Check 强制执行。

在调试环境中使用 App Check

为 App Check 注册应用后，如果您希望在 App Check 通常不会归类为有效提供方的环境（例如开发期间的本地环境）或持续集成 (CI) 环境中运行您的应用，可以创建应用的调试 build，该 build 使用 App Check 调试提供方，而不是真正的证明提供方。

请参阅将 App Check 与调试提供方搭配使用（Web 应用）。

费用说明

每次运行 Web 应用的浏览器刷新其 App Check 令牌时，App Check 都会代表您创建评估，以验证用户的响应令牌。对于超出免费配额的每项创建的评估，我们会对您的项目收费。如需了解详情，请参阅 reCAPTCHA 价格。

默认情况下，您的 Web 应用每 1 小时会刷新此令牌两次。如需控制应用刷新 App Check 令牌的频率（以及新评估的创建频率），请配置其 TTL。