使用 App Check 保护您的 API 密钥

Firebase App Check 可屏蔽来自合法应用以外的流量，为您的应用对 Google Maps Platform 的调用提供保护。为此，它会检查来自 reCAPTCHA Enterprise 等证明提供方的令牌。将应用与 App Check 集成，有助于防范恶意请求，让您不会为未经授权的 API 调用付费。

App Check 适合我吗？

在大多数情况下，我们都建议使用 App Check，但在以下情况下，不需要使用 App Check 或不支持使用 App Check：

  • 您使用原始 Places SDK。App Check 仅支持 Places SDK（新版）。
  • 私有应用或实验性应用。如果您的应用无法公开访问，则不需要使用 App Check。
  • 如果您的应用仅用于服务器到服务器的通信，则不需要使用 App Check。不过，如果与 GMP 通信的服务器由公共客户端（例如移动应用）使用，请考虑使用 App Check 保护该服务器，而不是使用 GMP。

实现步骤概览

从宏观层面来看，您需要按照以下步骤将应用与 App Check 集成：

  1. 将 Firebase 添加到您的应用。
  2. 添加并初始化 App Check 库。
  3. 将令牌提供方添加到您的应用。
  4. 初始化 Places API 和 App Check API。
  5. 启用调试。
  6. 监控应用请求，并决定是否强制执行。

与 App Check 集成后，您将能够在 Firebase 控制台中查看后端流量指标。这些指标可按请求是否附带有效的 App Check 令牌对其进行细分。如需了解详情，请参阅 Firebase App Check 文档。

当您确定大多数请求都来自合法来源，并且用户已更新到包含 App Check 实现的应用的最新版本时，即可启用强制执行。启用强制执行后，App Check 将拒绝所有没有有效 App Check 令牌的流量。

规划 App Check 集成时的注意事项

在规划集成时，请考虑以下事项：

  • 我们推荐的证明提供方之一 reCAPTCHA Enterprise 每月评估次数超过 10,000 次时会收费。

    我们推荐的另一个证明提供方 reCAPTCHA v3 有配额限制，超过配额后，系统将不再评估流量。

    您可以选择使用自定义证明提供方，但这是一个高级用例。如需了解详情，请参阅App Check 文档。

  • 您的应用的用户在启动时会遇到一些延迟。不过，之后，任何定期重新证明都会在后台进行，用户应该不会再遇到任何延迟时间。启动时的确切延迟时间取决于您选择的证明提供方。

    App Check 令牌的有效时长（即存留时间，或 TTL）决定了重新证明的频率。您可以在 Firebase 控制台中配置此时长。当 TTL 大约一半的时间已过时，系统会重新证明。如需了解详情，请参阅证明提供方的 Firebase 文档。

将应用与 App Check 集成

前提条件和要求

  • 加载了 Maps JS API、Core 和 Places 库的最新每周或每季度版本的应用。
  • 启用了 Maps JS 和 Places API（新版）API 的云项目。
  • 您必须是 Cloud 控制台中应用的所有者。
  • 您需要从 Cloud 控制台获取应用的项目 ID

第 1 步：将 Firebase 添加到您的应用

按照 Firebase 开发者文档中的说明 将 Firebase 添加到您的应用。

第 2 步：添加 App Check 库并初始化 App Check

Firebase 为每个默认证明提供方提供了说明。这些说明介绍了如何设置 Firebase 项目并将 App Check 库添加到您的应用。按照提供的代码示例初始化 App Check。

第 3 步：加载 Maps JS API 库

  1. 按照以下代码段所示加载 Core、Maps 和 Places 库。如需了解详情和说明，请参阅 Maps JavaScript API 地点类文档。

    async function init() {
  const {Settings} = await google.maps.importLibrary('core');
  const {Map} = await google.maps.importLibrary('maps');
  const {Place} = await google.maps.importLibrary('places');
}

第 4 步：初始化 Places API 和 App Check API

  1. 使用 Firebase 控制台提供的配置初始化 App Check。
  2. 确保对 Maps JS API 的请求附带 App Check 令牌： 
      async function init() {
    const {Settings} = await google.maps.importLibrary('core');
    const {Map} = await google.maps.importLibrary('maps');
    const {Place} = await google.maps.importLibrary('places');
  
    const app = initializeApp({
      // Your firebase configuration object
    });
  
    // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider(
        'abcdefghijklmnopqrstuvwxy-1234567890abcd',
      ),
  
      // Optional argument. If true, the SDK automatically refreshes App Check
      // tokens as needed.
      isTokenAutoRefreshEnabled: true,
    });
  
    Settings.getInstance().fetchAppCheckToken = () =>
        getToken(appCheck, /* forceRefresh = */ false);
  
    // Make a Places JS request
    const place = new Place({id: 'ChIJN5Nz71W3j4ARhx5bwpTQEGg'});
    await place.fetchFields({fields: ['*']});
  
    // Load a map
    map = new Map(document.getElementById("map"), {
      center: { lat: 37.4161493, lng: -122.0812166 },
      zoom: 8,
    });
  }

第 5 步：启用调试（可选）

如果您想在本地开发和测试应用，或在持续集成 (CI) 环境中运行应用，可以创建应用的调试 build，该 build 使用调试密钥来获取有效的 App Check 令牌。这可以让您避免在调试 build 中使用真实的证明提供方。

如需在本地测试应用，请执行以下操作：

  • 启用调试提供方以进行开发。
  • 您将从 SDK 的调试日志中收到自动生成的随机 UUID4（在 App Check 文档中称为“调试令牌”）。 __将此令牌添加到 Firebase 控制台。
  • 如需了解详情和说明，请参阅 App Check 文档。

如需在 CI 环境中运行应用，请执行以下操作：

  • 从 Firebase 控制台生成随机 UUID4。
  • 将 UUID4 添加为调试令牌，然后将其复制到 CI 测试每次运行都会访问的 Secret 存储区。
  • 如需了解详情和说明，请参阅 App Check 文档。

第 6 步：监控应用请求，并决定是否强制执行

在开始强制执行之前，您需要确保不会干扰应用的合法用户。为此，请访问 App Check 指标界面，查看应用的流量中有多少百分比是经过验证的、过时的或非法的。如果您发现大部分流量都已通过验证，即可启用强制执行。

如需了解详情和说明，请参阅 Firebase App Check 文档。