使用 Web 应用程序上的自定义提供程序启用应用程序检查

此页面向您展示如何使用您的自定义 App Check 提供程序在 Web 应用程序中启用 App Check。当您启用 App Check 时,您有助于确保只有您的应用可以访问您项目的 Firebase 资源。

如果您想将 App Check 与内置提供程序之一一起使用,请参阅App Check with reCAPTCHA v3App Check with reCAPTCHA Enterprise的文档。

在你开始之前

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

如果您还没有将 Firebase 添加到您的网络应用程序中。请务必导入 App Check 库。

2. 创建 App Check 提供者对象

为您的自定义提供程序创建一个 App Check 提供程序对象。此对象必须有一个getToken()方法,该方法收集您的自定义 App Check 提供程序作为真实性证明所需的任何信息,并将其发送到您的令牌获取服务以换取 App Check 令牌。 App Check SDK 处理令牌缓存,因此始终在您的getToken()实现中获取新令牌。

Web version 9

const { CustomProvider } = require("firebase/app-check");

const appCheckCustomProvider = new CustomProvider({
  getToken: () => {
    return new Promise((resolve, _reject) => {
      // TODO: Logic to exchange proof of authenticity for an App Check token and
      // expiration time.

      // ...

      const appCheckToken = {
        token: tokenFromServer,
        expireTimeMillis: expirationFromServer * 1000
      };

      resolve(appCheckToken);
    });
  }
});

Web version 8

const appCheckCustomProvider = {
  getToken: () => {
    return new Promise((resolve, _reject) => {
      // TODO: Logic to exchange proof of authenticity for an App Check token and
      // expiration time.

      // ...

      const appCheckToken = {
        token: tokenFromServer,
        expireTimeMillis: expirationFromServer * 1000
      };

      resolve(appCheckToken);
    });
  }
};

3.初始化应用检查

在您访问任何 Firebase 服务之前,将以下初始化代码添加到您的应用程序中:

Web version 9

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

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

const appCheck = initializeAppCheck(app, {
  provider: appCheckCustomProvider,

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

Web version 8

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

const appCheck = firebase.appCheck();
appCheck.activate(
  appCheckCustomProvider,

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

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

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

4. 监控请求指标

现在您的更新应用已在用户手中,您可以为您使用的 Firebase 产品启用应用检查。但是,在您这样做之前,您应该确保这样做不会破坏您现有的合法用户。

实时数据库、Cloud Firestore 和 Cloud Storage

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

要查看产品的 App Check 请求指标,请打开 Firebase 控制台的App Check部分。例如:

应用检查指标页面的屏幕截图

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

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

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

  • 未知来源请求是那些缺少应用检查令牌的请求,它们看起来不像来自 Firebase SDK。这些请求可能来自使用被盗 API 密钥发出的请求,也可能来自未使用 Firebase SDK 发出的伪造请求。

  • 无效请求是那些具有无效应用检查令牌的请求,这些请求可能来自试图模拟您的应用的不真实客户端,或来自模拟环境。

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

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

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

  • 如果您的应用尚未启动,您应该立即启用应用检查强制,因为没有任何过时的客户端在使用中。

云函数

对于 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
    }
  }
}

您可以通过使用以下指标过滤器创建基于日志的计数器指标,在 Google Cloud Console 中分析这些指标:

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. 打开 Firebase 控制台的应用检查部分。

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

  3. 单击强制并确认您的选择。

请注意,启用强制实施后最多可能需要 15 分钟才能生效。

云函数

请参阅为 Cloud Functions 启用应用检查强制