OAuth 2.1 实现指南

本指南概述了如何安全地授权关联的应用平台访问您的服务。对于关联的应用 MCP 集成，我们强烈建议使用 OAuth 2.1（委托授权的业界标准）和用于代码交换的证明密钥 (PKCE)，以确保用户数据的最高安全性以及“智能体”流程的可靠性。关联的应用平台支持授权代码授权类型，并使用用于代码交换的证明密钥 (PKCE) 参数。

PKCE 对于所有 OAuth 2.1 都是强制性的，对于 OAuth 2.0 是可选的。

为了实现自动发现并简化初始配置流程，您的授权服务器必须支持授权服务器元数据扩展（也称为 OAuth 发现）。

Gemini MCP 如何提取配置 JSON

Gemini MCP 控制台会尝试从以下网址获取配置 JSON，顺序如下。

如果您的授权服务器网址位于网域的顶层（例如 https://auth.example.com），Gemini 会将标准的“well-known”目录附加到您的网域，并按以下顺序查找服务器：

  1. https://auth.example.com/.well-known/oauth-authorization-server
  2. https://auth.example.com/.well-known/openid-configuration

如果您的授权服务器网址位于网域中的特定子目录或路径（例如 https://auth.example.com/realms/master），Gemini 会直接将相同的“well-known”路径附加到该子目录，顺序如下。

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration（嵌套路径支持）

必需的 JSON 功能

您的元数据响应必须包含以下字段。如果缺少必填字段或找不到有效类型，则集成会失败。

authorization_endpoint
必须是有效的字符串网址。
token_endpoint
必须是有效的字符串网址。
response_types_supported
必须包含字符串 code。
registration_endpoint

目前，Play 管理中心依赖于 Dynamic Client。

注册 (RFC 7591)。您必须在元数据中提供注册端点，或直接在 Play 管理中心界面中输入客户端 ID/密钥。

如果您的授权服务器不支持动态客户端注册 (DCR)，您必须在 Play 管理中心界面中手动实现并填充客户端 ID 和客户端密钥字段，才能完成集成。

如果您的实现支持用于代码交换的证明密钥 (PKCE) 或永久性会话，则必须在发现 JSON 中包含相关功能字段（例如质询方法和授权类型）。这有助于确保与 Gemini 的安全和连接标准兼容。如果您支持范围，则必须包含 scopes_supported 字段。

配置示例

以下是满足客户要求的有效 JSON 响应。

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

对于包含 PKCE 的情况，以下代码段展示了 JSON 块中可能包含的内容示例。

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

对于包含 scopes_supported 字段的情况，以下代码段展示了 JSON 块中可能包含的内容示例。

"scopes_supported": ["mcp", "cart.order"],

授权代码流程（简化版）

以下步骤概述了标准授权代码流程。此序列图展示了 Connected Apps Platform 如何安全地从您的服务器获取必要的访问令牌，以便代表用户执行操作。

  1. 授权请求：Google 平台确定需要调用您的函数，但用户尚未获得授权。聊天机器人通过将用户的浏览器重定向（或显示链接）到您的授权端点来启动流程。

    此请求包含您的客户端 ID（或通过 DCR 自动生成）、Gemini 重定向 URI 以及关键 PKCE 参数（code_challenge 和 code_challenge_method）。

    将以下网址列入许可清单，以便进行 OAuth 设置：

    • https://oauth-redirect.googleusercontent.com/r/*
    • https://oauth-redirect-sandbox.googleusercontent.com/r/*
    • https://oauth-redirect-test.googleusercontent.com/r/*
    • https://oauth-redirect.googleusercontent.com/a/*
    • https://oauth-redirect-sandbox.googleusercontent.com/a/*
    • https://oauth-redirect-test.googleusercontent.com/a/*

  2. 用户同意：您的授权服务器会验证请求、对用户进行身份验证（登录），并要求用户授予 Google 平台访问其数据或服务的权限。

  3. 代码授权：用户同意后，您的服务器会将用户的浏览器重定向回 Gemini RedirectURI，并在网址中附加一个临时授权代码。

  4. 令牌交换：Gemini 背后的后端会向您的令牌端点发送 POST 请求，将授权代码交换为访问令牌。

  5. 授予访问权限：您的令牌端点会验证代码和 PKCE 参数，签发访问令牌和（可选）刷新令牌，并将其返回给 Gemini。

PKCE 的主要要求

PKCE 增加了一层安全保护，可防止未经授权拦截授权代码。

  • code_verifier：Gemini 在流程开始时生成的加密随机字符串。此信息不会公开。
  • code_challenge：code_verifier 的转换，通常是 SHA256 哈希。此代码会公开发送，如授权代码流程的第 1 步中所述。
  • 验证：您的令牌端点（在授权代码流程的第 4 步中进行了介绍）必须验证收到的 code_verifier 在转换后是否与原始 code_challenge 匹配。

调试

您可以在 Logs Explorer 中查看详细的关联错误信息。如需启用和查看错误，请按照在 Google 控制台项目中监控账号关联错误中的说明操作。

Google 账号关联配置要求

如需了解 Google 账号关联配置，请参阅以下 API 指南。

如需成功注册 OAuth 集成，您需要配置有关授权服务器的具体详细信息。确保您已准备好以下端点、凭据和资产。

配置字段

说明

开发者责任

客户端 ID 和密钥

您的授权服务器专门为关联应用平台生成的唯一凭据。客户端密钥是与客户端 ID 关联的安全凭证（密码）。

注意：如果客户端 ID 是由开发者签发的，则必须由开发者提供。如果客户端 ID 是由 Google 签发的，开发者可能需要注册或验证密钥。

在所有授权请求中使用平台提供的 ID。

授权端点

用于重定向用户以进行身份验证和授权同意的网址

托管端点，例如 https://yourdomain.com/oauth/authorize

令牌端点

用于将授权代码交换为访问/刷新令牌以及刷新过期令牌的后端端点。

托管此端点，例如 https://yourdomain.com/oauth/token

撤销端点
可选

用于在用户断开连接时通知您的系统使令牌失效的网址。

当用户在“关联的应用”平台中解除关联或断开与您的集成的连接时，我们会向 /revoke 端点发出 POST 请求，其中包含访问令牌或刷新令牌。

如需了解详情，请参阅解除账号关联。

托管端点，例如 https://yourdomain.com/oauth/revoke

您的服务器必须通过永久使所提供的令牌失效来处理此请求。这样可确保“关联的应用”平台后续尝试使用该令牌时都会失败，从而在断开关联后保障用户数据的安全。

重定向 URI

平台提供的特定回调网址，授权服务器在用户同意后会将代码发送回该网址。

将您的授权服务器配置为仅接受来自平台的官方注册重定向 URI。

刷新

/token 与 grant_type=refresh_token 合作

一种机制，允许关联的应用平台在当前访问令牌过期时获取新的访问令牌，从而保持集成无缝连接，而无需用户重复登录。

当现有访问令牌过期时，关联应用平台会自动向您的 /token 端点发出 POST 请求。请求载荷将包含 grant_type=refresh_token 以及您的服务器之前签发的刷新令牌。

您的服务器必须验证所提供的刷新令牌，并在 JSON 响应中返回新的访问令牌。此外，如需实现永久关联，您必须避免在此交换期间轮替刷新令牌。请勿签发新令牌，而是在 JSON 响应中返回完全相同的刷新令牌，并在后端延长其失效日期。

响应类型

此参数必须配置为 CODE，以支持授权代码流程。

镜

一组特定的权限和访问权限级别，用于定义令牌有权执行的操作。这些权限和访问权限级别必须在您的配置中预先定义，以便 Google 可以在初始授权握手期间请求它们。

您需要提供一个默认范围列表（例如 openid, profile, email），供关联的应用平台在启动流程时请求。

请求的范围应尽可能缩小（最小权限原则），但应完全足以支持 MCP 集成所支持的关键用户历程 (CUJ)。

界面素材资源：徽标

要在账号关联和权限请求页面上显示的开发者徽标。

必须是方形矢量图像 (SVG)，外观为圆形，且尺寸至少为 500 x 500 像素。例如，请参阅 https://[partner-domain]/assets/logo.svg 或原始 SVG 文件。

原生应用关联 (App Flip)

为了支持直接从原生 Android 或 iOS 应用进行账号关联，我们强烈建议您不要依赖标准 WebView。相反，我们强烈建议您实现 App Flip，以提供顺畅的用户体验。

如需了解详情，请参阅通过基于 OAuth 的 App Flip 实现 Google 账号关联。

完成 Play 商店和应用商店验证，并将 Google 的重定向 URI 直接嵌入到您的原生应用中，以确保安全的应用到应用授权切换。

令牌有效期

（可选）访问令牌在需要刷新之前有效的时长。这对于在 GAL 中配置超时政策非常有用。

常见的到期时间从几分钟、几小时到几天不等，具体取决于安全需求，例如 30 days

常见集成错误

以下列出了集成过程中可能出现的常见错误和可能的解决方案。

  • 缺少“code”授权：Gemini 平台的自动化系统会明确检查 response_types_supported 是否包含值“code”。
  • 缺少注册端点：即使您的服务器支持客户端 ID 元数据文档，Gemini 应用（作为连接到您服务器的 OAuth 客户端）目前也要求在发现 JSON 中提供专用的 registration_endpoint。
  • 非 200 错误：如果 Gemini 的自动化元数据发现机制访问您的 well-known 网址并收到 404 或 500 错误，则不会尝试猜测其他网址。请确保发现网址可公开访问。