实现 Firebase App Check 以保护 API 免遭未经授权的客户端访问

如果您直接从移动应用或 Web 应用调用 API（例如，允许访问生成式 AI 模型的 API），则该 API 容易受到未经授权的客户端的滥用。为了帮助保护这些 API，您可以使用 Firebase App Check 验证所有传入的 API 调用是否来自您的实际应用。

Firebase AI Logic 提供了一个代理网关，可让您与 Firebase App Check 集成，并保护移动应用和 Web 应用调用的生成式 AI 模型 API。将 App Check 与 Firebase AI Logic SDK 搭配使用可支持我们的所有配置：

  • 同时保护“Gemini API”提供方：Gemini Developer API 和 Vertex AI Gemini API。

  • 保护所有受支持的模型，包括 Gemini 模型和 Imagen 模型。

App Check 的运作方式简要总结

使用 App Check 时，运行您的应用的设备将使用应用或设备证明提供方，用于验证以下两项或其中一项：

  • 请求来自您的正版应用
  • 请求来自真实的、未经篡改的设备

此证明会附加到您的应用使用 Firebase AI Logic SDK 发出的每个请求。启用 App Check 强制执行后，来自没有有效证明的客户端的请求将被拒绝，来自未经您授权的应用或平台的请求也将被拒绝。

我们建议您在设置 App Check 时，务必为即将推出的增强保护功能（称为重放攻击防范）做好准备。

您可以在 App Check 的文档中找到有关它的详细信息，包括其配额和限制。

可用的提供商和实现说明

App Check 文档提供了对证明提供方的说明以及实现说明。

  1. 选择默认提供商，然后按照以下链接中的实现说明操作：

    请注意，如果默认提供程序都不能满足您的需求，您可以实现自定义提供程序，从而使用第三方证明提供程序或您自己的证明方法。

  2. （推荐） 为即将推出的增强型保护功能做好准备（自 App Check 起，称为重放保护）。

  3. （必需）在向真实用户发布应用之前，请启用 App Check 的强制执行。

Flutter 需要特殊实例化

点击您的 Gemini API 提供商，以查看此页面上特定于提供商的内容和代码。

在 Flutter 应用中将 App Check 与 Firebase AI Logic 搭配使用时，您需要在实例化期间显式传入 App Check，如下所示：

// ...

final ai = await FirebaseAI.googleAI(
  appCheck: FirebaseAppCheck.instance, // for Flutter, pass in App Check explicitly
);

// ...

为即将推出的增强型保护做好准备

目前，仅 Apple 平台（v12.2.0 及更高版本）、Android（v17.2.0 及更高版本，BoM v34.2.0 及更高版本）和 Web（v12.3.0 及更高版本）支持使用限次令牌。
对其他平台的支持将在未来几周内发布。

默认情况下，App Check 使用会话令牌，该令牌的存留时间 (TTL) 可配置为介于 30 分钟和7 天之间。这些会话令牌由 App Check SDK 缓存，并随应用的请求一起发送。

未来，App Check 将添加用于为 Firebase AI Logic 启用重放保护的选项（类似于 App Check 已经为某些其他资源提供的支持）。启用重放攻击防范功能后，系统会通过以下方式增强保护：

  • App Check 仅允许附带一种称为限次使用令牌的特殊令牌的请求。

  • 在验证有限用途令牌后，系统会消耗掉该令牌，使其只能使用一次，从而防止重放攻击。

为防范重放攻击做好准备，我们建议您在设置 App Check 时启用限次令牌的使用。这样一来，当重放保护功能可用时，您就可以更快地启用该功能，因为会有更多用户使用发送限次令牌的应用版本。

如果您现在在应用中启用限制使用令牌（在重放保护功能不可用的情况下），请注意以下事项：

  • App Check 不会阻止使用有效的会话令牌。

  • 与会话令牌一样，有限用途令牌也会由 App Check SDK 缓存并随请求一起发送。与会话令牌相比，这些限次令牌可提供少量额外的保护，因为限次令牌的 TTL 更短（只有 5 分钟，且不可调整）。

  • 即使限次令牌的有效期为 5 分钟，SDK 仍会为每个请求生成一个新令牌。此过程可能会增加请求的延迟时间。

不过，如果未来 Firebase AI Logic 支持重放攻击防范（并且您启用了该功能），则无法使用会话令牌和重复使用有限用途的令牌。请注意，为每个请求生成新令牌所产生的额外延迟仍会发生。

启用有限用途令牌的使用

点击您的 Gemini API 提供商，以查看此页面上特定于提供商的内容和代码。

启用使用次数有限的令牌的方法如下：

  1. 实现 App Check，并确保您已为应用启用 App Check 强制执行。

  2. 在应用实例化期间，通过将 useLimitedUseAppCheckTokens 参数设置为 true 来启用限制使用令牌的使用：

    Swift

    
// ...

// During instantiation, enable usage of limited-use tokens
let ai = FirebaseAI.firebaseAI(
  backend: .googleAI(),
  useLimitedUseAppCheckTokens: true
)

// ...

    Kotlin 

    
// ...

// During instantiation, enable usage of limited-use tokens
val ai = Firebase.ai(
  backend = GenerativeBackend.googleAI(),
  useLimitedUseAppCheckTokens = true
)

// ...

    Java 

    
// ...

// During instantiation, enable usage of limited-use tokens
FirebaseAI ai = FirebaseAI.getInstance(
  /* backend: */ GenerativeBackend.googleAI(),
  /* useLimitedUseAppCheckTokens: */ true
);

// ...

    Web 

    
// ...

// During instantiation, enable usage of limited-use tokens
const ai = getAI(firebaseApp, {
  backend: new GoogleAIBackend(),
  useLimitedUseAppCheckTokens: true
});

// ...

    Dart

    在即将发布的版本中，我们将支持在 Flutter 应用中使用限次令牌。敬请关注！

    Unity

    在未来的版本中，我们将支持在 Unity 游戏中使用限次令牌。敬请关注！

了解 Firebase AI Logic 如何与 App Check 集成

如需使用 Firebase AI Logic SDK，必须在 Firebase 项目中启用 Firebase AI Logic API (firebasevertexai.googleapis.com)。这是因为 Firebase AI Logic SDK 发出的请求会先发送到 Firebase AI Logic 服务器，该服务器充当代理网关，Firebase App Check 验证会在请求获准继续发送到您选择的“Gemini API”提供商的后端以及用于访问 Gemini 和 Imagen 模型的 API 之前进行。