Catch up on everthing we announced at this year's Firebase Summit. Learn more

在 Web 应用程序中使用 reCAPTCHA v3 启用应用程序检查

此页面向您展示如何使用内置的 reCAPTCHA v3 提供程序在 Web 应用程序中启用应用程序检查。启用 App Check 有助于确保只有您的应用可以访问您项目的 Firebase 资源。看到一个概述此功能。

reCAPTCHA v3 是一项免费服务。应用程序检查还支持reCAPTCHA的企业,具有免配额有偿服务。要了解reCAPTCHA的V3和验证码企业之间的差异,看到的功能比较

请注意,reCAPTCHA v3 对用户不可见。 reCAPTCHA v3 提供程序不会要求用户随时解决挑战。查看验证码v3的文档

如果你想使用App中检查你自定义的供应商,请参阅实现自定义应用程序检查供应商

1. 设置您的 Firebase 项目

  1. 添加火力地堡到你的JavaScript项目,如果你还没有这样做。

  2. 注册您的网站的reCAPTCHA V3 ,让你的reCAPTCHA V3网站密钥和秘密密钥。

  3. 注册您的应用程序使用应用程序检查与在该验证码提供项目设置>应用程序检查的火力地堡控制台部分。您将需要提供您在上一步中得到的密钥

    您通常需要注册项目的所有应用,因为一旦您为 Firebase 产品启用强制执行,只有注册的应用才能访问产品的后端资源。

  4. 可选:在应用注册设置,设置一个自定义的时间生存(TTL)为App检查令牌由供应商发出的。您可以将 TTL 设置为 30 分钟到 7 天之间的任何值。更改此值时,请注意以下权衡:

    • 安全性:较短的 TTL 提供更强的安全性,因为它减少了攻击者可以滥用泄漏或拦截的令牌的窗口。
    • 性能:更短的 TTL 意味着您的应用程序将更频繁地执行证明。由于应用证明过程会在每次执行时增加网络请求的延迟,因此较短的 TTL 可能会影响应用的性能。
    • 配额和成本:更短的 TTL 和频繁的重新认证会更快地耗尽您的配额,而对于付费服务,可能会花费更多。见配额和限制

    1天的默认TTL是合理的大多数应用程序。请注意,App Check 库会在大约一半的 TTL 持续时间刷新令牌。

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

添加火力地堡到您的Web应用程序,如果你还没有准备好。请务必导入 App Check 库。

3. 初始化应用检查

在您访问任何 Firebase 服务之前,将以下初始化代码添加到您的应用程序中。您将需要通过你的reCAPTCHA网站密钥,您在验证码控制台创建,以activate()

网页版 9

const { initializeApp } = require("firebase/app");
const { initializeAppCheck, ReCaptchaV3Provider } = require("firebase/app-check");

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

// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaV3Provider('abcdefghijklmnopqrstuvwxy-1234567890abcd'),

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  isTokenAutoRefreshEnabled: true
});

网页版 8

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

const appCheck = firebase.appCheck();
// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
appCheck.activate(
  'abcdefghijklmnopqrstuvwxy-1234567890abcd',

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  true);

在您的应用程序中安装 App Check 库后,部署它。

更新后的客户端应用将开始发送 App Check 令牌以及它向 Firebase 发出的每个请求,但 Firebase 产品不需要令牌有效,直到您在 Firebase 控制台的 App Check 部分启用强制执行。有关详细信息,请参阅接下来的两节。

4. 监控请求指标

现在您的更新应用已掌握在用户手中,您可以为您使用的 Firebase 产品启用 App Check 的强制执行。但是,在您这样做之前,您应该确保这样做不会干扰您现有的合法用户。

实时数据库、Cloud Firestore 和 Cloud Storage

您可以用来为实时数据库、Cloud Firestore 和 Cloud Storage 做出此决定的一个重要工具是 App Check 请求指标屏幕。

要查看应用程序检查请求指标的产物,打开项目设置>应用检查的火力地堡控制台的部分。例如:

App Check 指标页面的屏幕截图

每个产品的请求指标分为四类:

  • 验证请求是那些具有有效的应用程序检查令牌。启用 App Check 强制后,只有此类别中的请求才会成功。

  • 过时的客户端请求是那些缺少应用程序检查令牌。在 App Check 包含在应用中之前,这些请求可能来自旧版本的 Firebase SDK。

  • 来历不明的请求是那些缺少应用程序检查令牌,不要像他们来自火力地堡SDK。这些可能来自使用被盗 API 密钥发出的请求或在没有 Firebase SDK 的情况下发出的伪造请求。

  • 无效的请求是那些有一个无效的应用程序检查令牌,这可能是从不真实客户端试图假冒您的应用程序,或从模拟环境。

当您决定启用强制执行时,您的应用程序的这些类别的分布应该通知。以下是一些指导方针:

  • 如果几乎所有最近的请求都来自经过验证的客户端,请考虑启用强制措施以开始保护您的后端资源。

  • 如果最近请求的很大一部分来自可能已经过时的客户端,为避免干扰用户,请考虑等待更多用户更新您的应用,然后再启用强制执行。对已发布的应用程序强制执行 App Check 将破坏未与 App Check SDK 集成的先前应用程序版本。

  • 如果您的应用程序尚未启动,您应该立即启用 App Check 强制执行,因为没有任何过时的客户端在使用。

云功能

对于 Cloud Functions,您可以通过检查函数的日志来获取 App Check 指标。可调用函数的每次调用都会发出一个结构化的日志条目,如下例所示:

{
  "severity": "INFO",    // INFO, WARNING, or ERROR
  "logging.googleapis.com/labels": {"firebase-log-type": "callable-request-verification"},
  "jsonPayload": {
    "message": "Callable header verifications passed.",
    "verifications": {
      // ...
      "app": "MISSING",  // VALID, INVALID, or MISSING
    }
  }
}

您可以通过分析在谷歌云端控制台这些指标建立一个日志,基于计数器的度量与以下数据过滤器:

resource.type="cloud_function"
resource.labels.function_name="YOUR_CLOUD_FUNCTION"
resource.labels.region="us-central1"
labels.firebase-log-type="callable-request-verification"

标签的指标使用领域jsonPayload.verifications.appCheck

5. 启用执行

要启用强制执行,请按照以下每个产品的说明进行操作。为产品启用强制执行后,所有对该产品的未经验证的请求都将被拒绝。

实时数据库、Cloud Firestore 和 Cloud Storage

要为实时数据库、Cloud Firestore(iOS 和 Android)和 Cloud Storage 启用强制措施:

  1. 打开项目设置>应用程序检查的火力地堡控制台部分。

  2. 展开要为其启用强制执行的产品的指标视图。

  3. 点击强制执行,并确认您的选择。

请注意,启用强制执行后最多可能需要 10 分钟才能生效。

云功能

请参阅启用应用检查执法云功能

下一步

如果在为 App Check 注册您的应用程序后,您希望在 App Check 通常不会将其归类为有效的环境中运行您的应用程序,例如在开发过程中的本地或持续集成 (CI) 环境中,您可以创建使用 App Check 调试提供程序而不是真正的证明提供程序的应用程序的调试版本。

请参阅使用App请与网络应用程序的调试提供商