自建 Gemini 企业界面的三层认证
基于 Gemini Enterprise 的 :streamAssist API 自建界面时,开发者需分别处理用户或工作负载身份、第三方连接器授权,以及自定义 ADK Agent 的工具授权。文章说明身份联合、Keystore 和 GCP Auth Manager 等组件的分工。
AI 深度解读
给 Gemini Enterprise 换一个自定义聊天界面,接上的不只是消息流,还有原来由官方界面代办的三层认证:员工身份、第三方连接器授权,以及自定义 Agent 的工具授权。能调用 StreamAssist,只是第一步。
这篇 Google Developers Blog 的核心建议是:需要员工权限隔离时,保留用户身份;连接第三方系统时,分别处理连接器和工具的 OAuth。对准备把企业 AI 嵌进内部门户的前端、全栈团队,这比聊天框怎么画更值得先弄清楚。
请求能成功,不代表带对了用户身份
官方 Gemini Enterprise 网页会处理登录、文档访问控制列表(ACL)和授权弹窗。自建 Customer UI,再由 Customer BE 调用 StreamAssist API 后,这些责任就落到了业务团队身上。下文分别称它们为前端和后端。
首先要选的是:请求代表员工,还是代表机器。
凡是需要按员工隔离文档权限、聊天历史和 Agent 使用权限的应用,都应该传递员工身份。
原文给出三种无密钥认证模式:
- Pattern 1A:Google Identity。 员工使用 Google Workspace 或 Cloud Identity 登录,前端通过 Google Identity Services 发起 OAuth 2.0 登录,请求 Google Cloud Platform scope,后端将用户 access token 作为 Bearer token 直接交给 StreamAssist。
- Pattern 1B:Workforce Identity Federation。 员工使用 Microsoft Entra ID 或 Okta 登录,后端把取得的 OIDC token 交给 Google Security Token Service(STS),换取代表该员工的短期 Google access token。
- Pattern 1C:Workload Identity Federation。 后端从外部 IdP 获取机器 JWT,再通过 Google STS 换取 token,调用 StreamAssist。它使用项目级 Workload Identity Pool,不需要在磁盘保存 Service Account JSON keys。
Workforce 和 Workload 只差几个字母,授权语义却不同:前者代表人,后者代表工作负载。Pattern 1C 下,Gemini Enterprise 将请求都视为来自同一个工作负载身份,适合共享知识库机器人,不能拿来替代员工级授权。
Pattern 1B 还要求复用 Gemini Enterprise 已连接的 Workforce Pool,并把自定义应用的 Entra ID 或 Okta Client ID 加进现有 OIDC Provider。
此外,所有调用主体都需要项目上的 Discovery Engine User IAM role;Pattern 1A、Pattern 1B 的用户或 Workforce Pool group,还必须在 Admin Console 获得有效的 Gemini Enterprise 用户许可证。登录成功、具备调用角色、拥有许可证,是分别需要满足的条件。
连接器授权,要把弹窗之后的链路接完
带着员工身份进入 Gemini Enterprise,不等于已经拿到该员工在 SharePoint 或 Jira 中的访问授权。
Federated Connectors 会实时请求第三方 API,因此每位员工还需要完成一次三方 OAuth(3-Legged OAuth,3LO)。Google Drive、Microsoft SharePoint Online、Jira、Box、ServiceNow 和 Confluence 都属于原文列举的连接器。
这里的重点是:第三方 refresh token 存进 Gemini Enterprise 托管的 Keystore,业务后端负责组织流程。
原文把它拆成 11 步,可以归为三段。
第一段是发现连接器、检查授权。前端向后端取连接器列表,后端使用员工的 Bearer token 查询引擎挂载的 Federated Connectors,并检查 Keystore。已有授权时,GE Server 自动刷新并返回 token;没有授权时,返回 authorization URL,前端据此显示授权按钮。
第二段是弹窗和回传。员工同意授权后,第三方将弹窗重定向到 Google 托管的 GE FE Server /oauth-redirect 页面。该页面通过浏览器 postMessage 把包含 authorization code 和 state 的 callback URL 发回自定义前端,然后关闭弹窗。
第三段是兑换和保存。前端将 callback URL 交给后端,后端调用 GE Server 兑换授权码,将 refresh token 保存进 Keystore。完成后,后端还需要在 StreamAssist 请求中带上对应的 data store ID,查询才会覆盖这个实时连接器。
前端团队最容易低估的是回传配置。/oauth-redirect 默认只向官方网页的 origin 发送 postMessage。自定义域名需要联系 Gemini Enterprise 团队启用 custom origin flag,否则流程会卡在弹窗回传这一步。
所以,这不是放一个 Connect 按钮就能结束的工作。发现连接器、显示授权状态、处理回调、确认授权、携带查询范围,都属于自定义界面的职责。
Agent 为什么要到调用工具时才授权
原生连接器适合联合搜索和内置操作。需要多步推理、自定义 Python 逻辑,或者跨多个企业 API 编排时,作者建议构建 ADK Agent,部署到 Vertex AI Agent Engine,再注册进 Gemini Enterprise。
问题出在 OAuth 配置放在哪里。
如果把静态 OAuth 配置挂在根 Agent 注册层,授权会挡在整个 Agent 前面。一个同时接 Google Drive 和 SharePoint 的助手,可能连普通政策问答都要先完成所有登录。原文还指出,这种根级授权围绕官方网页设计,无法自然满足自定义 UI 从 StreamAssist 接收工具级授权提示的需要。
作者给出的方案是按需授权:普通 Python 工具直接运行;受保护工具使用 AuthenticatedFunctionTool 和 GcpAuthProvider 包装,指向 GCP Auth Manager 中的 Auth Provider。
部署时还要开启 Agent Identity,让 Agent 获得 SPIFFE 身份,并授予 Agent Identity Service Agent IAM role,以便访问 GCP Auth Manager 的 Token Vault。
每个第三方 OAuth 应用都需要创建一个 3LO Auth Provider:Default Continue URI 设置为自定义前端的 <website-url>/validateUserId,第三方应用的 Redirect URI 则配置为 GCP Auth Manager 的 /oauthcallback。
这里有两个身份:员工决定第三方数据的访问范围,Agent Identity 用于让 Agent 访问 Token Vault,二者不能混为一谈。
完整链路有 19 步,最需要理解的是授权后的收尾。首次调用受保护工具时,Token Vault 未命中,authorization URL 沿 Agent Engine、GE Server、业务后端返回前端。员工同意后,/oauthcallback 兑换 token,但先暂存,随后将携带 validation state token 的弹窗重定向到 /validateUserId。
前端把 validation state token 交给后端。后端必须使用员工的 Bearer token 调用 Validate User Authorization API,由 GE Server 核验会话归属,再通过 FinalizeCredentials 将凭据正式保存进 Token Vault。
收到 HTTP 200 OK 后,后端才在同一 session 自动重试原来的 StreamAssist 查询。此时 Agent 命中缓存,用 3LO token 调用 Microsoft Graph 或 Google Drive,返回有数据依据的回答。
OAuth 回调完成之后,还有用户归属验证和原查询重试两步。
原文称后续查询无需弹窗,但没有展开 token 过期、授权撤销或 scope 变化时的恢复方式,实际接入仍需补齐这些分支。
我的判断
这套方案说得最对的地方,是把「登录企业 AI」「授权第三方搜索」「授权 Agent 工具」分开处理。它们服务于不同的权限边界,共用一个登录成功状态,很容易让产品看起来已经就绪,真正查询时才暴露缺口。
按工具触发授权也更贴合用户意图。员工准备访问 SharePoint 时再解释所需权限,比打开助手就要求连接所有系统更容易理解。不过,原文没有提供授权完成率、查询延迟或故障率的对照数据,不能据此断言体验提升了多少。
可迁移性也有前提。连接器使用 Gemini Enterprise Keystore,自定义工具使用 GCP Auth Manager Token Vault,两条链路各有回调和保存逻辑。接入方减少了自建凭据存储的工作,同时也依赖 Google 托管组件、IAM 配置及自定义 origin 支持。
作者提供了可运行蓝图,包含交互测试 UI、CLI、curl 和部署脚本,但没有给出生产压测或完整异常处理结果。它适合帮助团队验证架构,生产可用性还需要自己验收。
能拿来做什么
- 开工前先确定请求身份。员工助手优先评估 Pattern 1A、Pattern 1B;共享机器人再评估 Pattern 1C,并把 IAM role、许可证和身份池配置一起纳入接入检查。
- 前端将「已登录」「连接器已授权」「工具等待授权」分别建模,落实弹窗回传和
/validateUserId处理,不要用一个布尔值覆盖全部认证状态。 - 如果业务后端使用 Node,可以按原文职责实现 token 转发、回调提交和同 session 重试;原文蓝图提供的是 Python、CLI 与 curl 示例,没有给出 Node 实现。
- 验证时分别参考
01_user_auth_streamassist/、02_federated_connector_oauth/、03_adk_agent_oauth/,先跑通用户身份,再接连接器,最后验证工具授权后的自动重试,便于定位失败发生在哪一层。