使用 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. 按照以下代码段所示加载核心库、Maps 库和 Places 库。如需了解详情和说明，请参阅 Maps JavaScript API Place 类文档。 

    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 文档。