Google Tag Manager(无脚本) Google Tag Manager(无脚本)结束 HTML Gemini Enterprise 自定义 UI 如何处理用户、连接器与智能体认证 2026 年 11 月 20 日 Neeraj Agrawal 前沿部署工程师 Google Cloud meta-image-1600x900

使用开箱即用的 Gemini Enterprise Web 应用中,身份和访问管理在后台完成。员工通过 Google Identity 或 Workforce Identity Federation(例如 Microsoft Entra ID 或 Okta)登录,搜索结果会自动遵循每位用户的访问控制列表(ACL),针对 Federated Connectors 或 自定义智能体 的第三方登录提示会自动出现在聊天界面中。

但在实践中,许多企业会构建自己的 Customer UI ,将 Gemini Enterprise 嵌入内部门户、内联网或业务线应用。为此, Customer BE 会调用 Gemini Enterprise 的 StreamAssist API.

。一旦应用构建自定义 UI 并直接调用 StreamAssist API,原本由内置 Web 应用自动处理的三种身份验证流程便转由 Customer UI 和 Customer BE:

  1. StreamAssist 身份验证(用户身份与工作负载身份): 对于需要考虑文档 ACL、隔离的聊天记录和受限智能体权限的面向用户的应用, Customer UI 和 Customer BE 必须通过 Google Identity 传递已登录员工的身份(Pattern 1A),或通过 Workforce Identity Federation(Pattern 1B)。对于非个性化后端机器人或共享服务门户, Customer BE 可以使用 Workload Identity Federation 进行无密钥身份验证(Pattern 1C).
  2. 通过 Customer UI 对 Federated Connectors 进行身份验证: 实时 Federated Connectors 使用三方 OAuth(3LO),因此它们只会检索已登录员工有权查看的 Google Drive 文件、SharePoint 站点、Jira 问题或 ServiceNow 事件。由于 Customer UI 没有 Gemini Enterprise 的内置“Connect”按钮, Customer BE 和 Customer UI 必须发现该引擎的连接器,检查 Keystore 中是否存在有效令牌,在需要时触发 3LO 同意弹窗,并将刷新令牌保存到 Keystore,并将连接器数据存储纳入 StreamAssist 查询。
  3. 处理自定义 ADK 智能体中各工具的 OAuth: 部署一个自定义 ADK 智能体 至 Vertex AI Agent Engine ,且该智能体连接多个企业系统(例如 Google Drive 和 Microsoft SharePoint)时,在根智能体注册层级附加静态 OAuth 配置会预先阻塞整个智能体。对此,可改为使用 GcpAuthProvider (由 GCP Auth Manager 的 Token Vault提供支持),并在部署智能体时启用 Agent Identity ,StreamAssist 仅在调用受保护的工具时才会按需触发 3LO 弹窗。

本指南将介绍所有三个层面的架构、组件流程和可运行代码(图 1):

fig1-end-to-end-identity-architecture 图 1:涵盖 StreamAssist 登录(Google Identity、Workforce STS 或 Workload STS)、Federated Connectors(Keystore)和自定义 ADK 智能体(Vertex AI Agent Engine + GCP Auth Manager Token Vault)的端到端身份验证架构。

第 1 部分:向 StreamAssist 进行身份验证的三种模式(用户与工作负载)

取决于 Customer UI 是代表单个员工执行操作,还是作为共享后端机器人运行,客户架构会采用三种主要的无密钥身份验证模式:

part1-authentication-patterns-table fig2-inbound-streamassist-scenarios 图 2:对比调用 StreamAssist 的模式 1A(纯 Google Identity)、模式 1B(Workforce Identity Federation + Google STS)和模式 1C(Workload Identity Federation + Google STS)。

所需的 IAM 角色和许可证: 每个调用 StreamAssist API 的主体都必须被授予 Discovery Engine User IAM 角色。对于人类用户模式(模式 1A 和 模式 1B),还必须在 Admin Console 中为该用户(或 Workforce Pool 群组)分配有效的 Gemini Enterprise 用户许可证。

模式 1A:纯 Google Identity(通过 Google 登录界面登录 StreamAssist)

当员工使用 Google Workspace 或 Cloud Identity 登录,且 Gemini Enterprise 引擎配置为使用 Google Identity 时,整个流程无需任何额外跳转:

  1. 客户 UI 使用以下服务让员工登录: Google Identity Services(OAuth 2.0) 并请求 Google Cloud Platform 权限范围。
  2. Google 会返回一个权限范围限定为已登录员工的用户访问令牌。
  3. 客户后端 将该 Bearer 令牌直接发送至 StreamAssist API。

模式 1B:Workforce Identity Federation(外部 IdP UI → Google STS → StreamAssist)

当员工登录 客户 UI 使用 Microsoft Entra ID 或 Okta,而 Gemini Enterprise 使用 Workforce Identity Federation(WIF)时,可复用已连接到 Gemini Enterprise 的同一 Workforce Pool:

  1. 在现有 WIF Provider 上注册客户 UI: 将自定义 Web 应用的 Entra ID 或 Okta Client ID 添加到 Google Cloud Workforce Pool OIDC Provider。
  2. 在 Google STS 处交换 IdP 令牌: 员工登录 客户 UI ,并从 Entra ID 或 Okta 接收 OIDC 令牌, 客户后端 在 Google Security Token Service(STS)处,使用 Workforce Pool Provider 交换该令牌。
  3. 使用联合身份用户令牌调用 StreamAssist: Google STS 返回一个代表该特定 Workforce Pool 用户的短期 Google 访问令牌,并强制执行该员工的所有群组权限和文档 ACL。

模式 1C:Workload Identity Federation(后端/共享机器人 → Google STS → StreamAssist)

当后端服务、Slack/Teams Webhook 或非个性化知识机器人需要在不使用任何 Service Account JSON 密钥的情况下调用 StreamAssist 时,请使用项目范围的 Workload Identity Pool:

  1. 从外部 IdP 获取机器 JWT: 客户后端 从外部 IdP 请求应用令牌(例如,在 Entra ID 中使用 OAuth 2.0 客户端凭据)。
  2. 在 Google STS 处交换: 客户后端 在 Google STS 处,使用该项目的 Workload Identity Pool Provider 交换该机器 JWT,全程无需在磁盘上存储密钥。
  3. 调用 StreamAssist: 客户后端 将返回的 Google STS 令牌发送给 StreamAssist。

何时使用模式 1C,而不是模式 1A 和 1B: 由于 Workload Identity Federation 验证的是机器而非单个人类员工的身份,因此 Gemini Enterprise 会将每个请求都视为来自同一个工作负载身份。请使用 模式 1C 来处理基于共享知识库的非个性化机器人,并使用 模式 1A 或 模式 1B 只要您需要按用户设置文档 ACL、用户专属的 3LO 连接器或受限的自定义智能体。

第 2 部分:通过自定义界面对联合连接器进行身份验证

一旦 客户界面 和 客户后端 以已登录员工的身份调用 StreamAssist,用户便可以查询原生 联合连接器 (例如 Google Drive、Microsoft SharePoint Online、Jira、Box、ServiceNow 和 Confluence),它们会实时搜索第三方 API。

由于联合连接器会在第三方系统中强制执行用户级权限,因此每位员工都要使用三方 OAuth(3LO)对连接器进行一次授权。Gemini Enterprise 会将这些用户专属的刷新令牌存储在其自行管理的 密钥库中,因此 客户后端 无需在自己的数据库中存储第三方凭据。

fig3-federated-connector-3lo-flow 图 3:跨客户界面、客户后端、第三方认证服务器、GE 前端服务器、GE 服务器和密钥库对 Gemini Enterprise 联合连接器进行身份验证的组件架构及 11 步 3LO 流程。
  • 第 1 阶段:发现连接器并检查密钥库(步骤 1 至 4): 客户界面 向 客户后端 (请求可用的连接器(步骤 1)。). 客户后端 调用 GE 服务器 ,使用用户在第 1 部分中的 Bearer 令牌列出挂接到该引擎的联合连接器,并检查用户是否已拥有每个连接器的有效访问令牌(步骤 2). GE 服务器 检查 密钥库:如果用户之前已授权该连接器, GE 服务器 会自动刷新并返回令牌;否则,它会返回一个授权 URL(步骤 3). 客户后端 将连接器列表返回给 客户界面,后者会为任何需要用户同意的连接器呈现一个 授权按钮 (步骤 4).
  • 第 2 阶段:3LO 用户同意弹窗和重定向中继(步骤 5 至 7): 当用户点击 授权按钮, 客户界面 时,系统会在弹出窗口中打开位于 三方认证服务器 (步骤 5的授权 URL(步骤 5)。用户登录并批准访问后,弹出窗口会重定向到 Google 的 GE 前端服务器 OAuth 重定向页面(步骤 6),该页面通过浏览器的 postMessage 将回调 URL(包含授权代码和状态)发送回 客户界面 ,然后关闭弹出窗口(步骤 7).
  • 第 3 阶段:交换授权代码、将刷新令牌存储在密钥库中并进行确认(步骤 8 至 11): 客户界面 将回调 URL 转发给 客户后端 (步骤 8),后者调用 GE 服务器 ,以便与第三方令牌端点交换授权代码,并将用户的刷新令牌保存到 密钥库 (步骤 9). GE 服务器 向 客户后端 (步骤 10)并向 客户界面 (步骤 11)确认连接器现已获得授权。授权完成后, 客户后端 会在其 StreamAssist 请求中包含连接器的数据存储区 ID,以便 Gemini Enterprise 在查询时搜索实时的第三方连接器。

自定义界面注意事项:启用从 GE 前端服务器自动移交弹出窗口: 所有 Gemini Enterprise 联合连接器都使用 Google 托管的 /oauth-redirect 端点,该端点位于 GE 前端服务器 上,并作为其固定回调 URL。默认情况下,该页面只会向内置 Gemini Enterprise Web 应用的源发送浏览器 postMessage 事件。部署 客户界面 部署在自定义域上时,请与您的 Gemini Enterprise 团队合作启用自定义源标志,以便 步骤 7 自动将回调 URL 发送至 客户界面 并关闭弹出窗口。

第 3 部分:通过 GCP Auth Manager Vault 为自定义 ADK 智能体配置单个工具级 OAuth

原生联合连接器非常适合联合搜索和内置操作。当工作流需要多步推理、自定义 Python 逻辑,或由单个助手跨多个企业 API 进行编排时,团队会构建自定义 ADK 智能体,将其部署到 Vertex AI Agent Engine,并在 Gemini Enterprise 中注册。

为何智能体注册中的根级 OAuth 会阻碍多工具自定义界面

在 Gemini Enterprise 中注册 ADK 智能体时,直接将静态 OAuth 配置附加到根智能体注册会给自定义界面带来两个问题:

  1. 预先阻塞所有工具: 根级 OAuth 会在第一个对话轮次到达智能体代码之前拦截整个智能体。如果一个助手同时连接到 Google Drive 和 Microsoft SharePoint Online,用户就无法提出一般性的策略问题,也无法仅查询 SharePoint,而不必预先完成所有 OAuth 登录。
  2. 内置界面耦合: 根级智能体授权是围绕内置 Gemini Enterprise Web 界面设计的,而不是通过 StreamAssist API 返回特定于工具的授权提示。

解决方案:使用 Agent Identity 和 GCP Auth Manager 实现按需工具 OAuth

要触发三方 OAuth 按工具按需授权 并让 Gemini Enterprise 和 Google Cloud 自动管理每位用户的 Token Vault ,只需完成三个简单的设置步骤:

  1. 创建子智能体工具,并使用 GcpAuthProvider 封装受保护的工具: 无需用户登录的标准工具可作为普通 Python 函数运行,完全不会触发 OAuth 提示。对于调用受保护第三方 API(如 SharePoint 或 Google Drive)的工具,请使用 ADK 的 AuthenticatedFunctionTool 和 GcpAuthProvider 封装工具函数,并将其指向 GCP Auth Manager 中的 Auth Provider 资源。
  2. 将 ADK 智能体部署到 Vertex AI Agent Engine,并启用 Agent Identity: 将 Root Router Agent 及其子智能体部署到 Vertex AI Agent Engine,并启用 Agent Identity。这会为智能体提供内置的 SPIFFE 身份。向该智能体身份授予 GCP 项目中的 Agent Identity Service Agent IAM 角色,使其能够从以下位置检索令牌: GCP Auth Manager Token Vault.
  3. 在 Google Cloud Console(Auth Manager)中添加 3LO 身份验证提供方: 在 Google Cloud Console 中,为每个第三方 OAuth 应用(如 SharePoint 和 Google Workspace)创建一个 3LO 身份验证提供方,并将 Customer UI 上的 Default Continue URI 设置为 <website-url>/validateUserId ,然后将 GCP Auth Manager 回调 URL(/oauthcallback)添加为 Microsoft Entra ID 或第三方应用中的 Redirect URI。
fig4-adk-subagent-on-demand-3lo 图 4:跨 Customer UI、Customer BE、GE Server、Vertex AI Agent Engine 和 GCP Auth Manager 的组件架构及 19 步按需工具 3LO 流程。
  • 阶段 1:查询路由与 Token Vault 检查(步骤 1 至 7): 用户从 Customer UI 向 Customer BE (步骤 1),后者在 GE Server 上使用用户的第 1 部分 Bearer 令牌调用 StreamAssist API(步骤 2). GE Server 调用部署在 Vertex AI Agent Engine (上的自定义 ADK 智能体(步骤 3)。在运行受保护工具之前,子智能体会检查 GCP Auth Manager Token Vault ,并使用其 Agent Identity(步骤 4)。首次调用时(缓存未命中), GCP Auth Manager 会返回一个授权 URL,该 URL 从 Vertex AI Agent Engine 回传至 GE Server (步骤 5), 客户后端 (步骤 6),然后 客户界面 (步骤 7).
  • 阶段 2:3LO 授权弹窗和回调重定向(步骤 8 至 10): 客户界面 会显示一个 授权按钮 ,点击后会在弹出窗口中打开授权 URL,用户在其中登录,并在 3P Auth Server (步骤 8)。随后, 3P Auth Server 将弹出窗口重定向到 GCP Auth Manager 的 托管的 OAuth 回调端点,该端点将授权代码交换为第三方令牌,并在等待验证期间保存这些令牌(步骤 9). GCP Auth Manager ,然后将弹出窗口重定向到 Customer UI 上的 /validateUserId 回调页面,并附带验证状态令牌(步骤 10).
  • 阶段 3:验证用户授权并将令牌保存到 Token Vault(步骤 11 至 14): 客户界面 将验证状态令牌传递给 客户后端 并关闭弹出窗口(步骤 11). 客户后端 调用用户授权验证 API,该 API 位于 GE Server ,并携带用户的第 1 部分 Bearer 令牌(步骤 12). GE Server 验证会话所有者,并调用由 GCP Auth Manager提供的 FinalizeCredentials,后者会将用户的 3LO 令牌永久保存在 Token Vault 中,并返回成功结果(步骤 13). GE Server 随后向 客户后端 (返回 HTTP 200 OK(步骤 14)。).
  • 阶段 4:自动重试查询和缓存执行(步骤 15 至 19): 一旦 客户后端 收到步骤 14 中的 HTTP 200 OK 后, 客户后端 会在同一会话中自动重试 StreamAssist 查询(步骤 15). GE Server 调用运行在 Vertex AI Agent Engine (步骤 16),此时它会获得一次 Token Vault 缓存命中,使用 3LO 令牌调用第三方 API(例如 Microsoft Graph 或 Google Drive),并将基于检索依据的回答流式传回 GE Server (步骤 17), 客户后端 (步骤 18),再经由 客户界面 (步骤 19)。之后的所有查询都在单个轮次中运行,不再出现弹出窗口。

探索可运行的代码蓝图

我们已将全部三层身份验证机制,以及交互式 Web 测试界面、CLI 脚本和 curl 命令打包到 gemini-enterprise-custom-ui-auth GitHub 仓库:

发布于: 上一篇 下一篇 相关文章 Multi-Turn Agentic Reinforcement Learning with Tunix and Gemma 4 on Google TPUs 人工智能 云 教程 学习

使用 Tunix 和 Gemma 4 在 Google TPU 上开展多轮智能体强化学习

2026 年 11 月 19 日
Agent Anomaly Detection: Safeguarding agents across other clouds 人工智能 云 公告

智能体异常检测:保护跨其他云运行的智能体

2026 年 11 月 20 日
Distributed LLM Training Across Metros: Streaming DiLoCo in MaxText 人工智能 云 操作指南 学习

跨都市区域的分布式大语言模型训练:在 MaxText 中实现流式 DiLoCo

2026 年 11 月 19 日