连接(每用户 OAuth2)
连接 是个人用户如何代表自己授予 AiHummer 访问第三方服务的权限。每个人运行的是标准帐户,而不是单一的共享服务帐户 OAuth2 授权码流程,生成的令牌被封存在加密保险库中,而在轮转时间,当工具需要它时,运行时会解析该用户的令牌。
这是 AiHummer 凭证模型的“个人”部分。关于更广泛的情况——何时优先使用共享凭证以及回退如何工作——请参见 个人凭证与共享凭证.
下述个人授权流程仍是默认方式。安装已签名的 Core 1.4.15 后,已配置的渠道和原生工具可以选择一个明确绑定的连接,使用专用 connection-token 密钥,且只有凭证库负责刷新。这不会共享所有用户的全部授权,也不要求每位员工单独连接。工具仍检查操作用户的当前权限。参见 Bitrix24。
连接是什么
一个连接将三件事物绑定在一起:一个 提供者 (您正在授权的 OAuth2 应用程序),一个 用户 (完成同意屏幕的人),以及一个 金库入口 (已发放的令牌存储的位置)。一旦建立,任何代表该用户操作的工具都可以透明地使用该令牌,而无需它出现在模型上下文、日志或提示中。
连接由管理员界面管理。列表显示每个用户的已连接提供商、其状态以及上次刷新时间。
授权码流程
使用规范的三方 OAuth2 授权码授权创建连接:
- 用户从管理员界面为提供者启动连接——一个
POST/GET /v1/admin/connections/oauth/start请求。 - AiHummer 将浏览器重定向到提供商的 授权 端点 具有请求的权限范围。
- 用户批准同意屏幕;提供者重定向回时带有一个
一次性 授权码 到
/v1/admin/connections/oauth/callback. - 在回调处理程序内部,AiHummer 在服务器端用该代码交换一个 访问令牌 (并且,当提供商支持时,a 刷新令牌) 在提供者的令牌端点。
- 令牌被写入保险库,连接被标记为活动状态。
代码换取令牌的过程在回调内的服务器端进行,因此客户端密钥和已发放的令牌永远不会离开网关。
[!NOTE] 不要将此流程与混淆
POST /v1/oauth/token:那是AiHummer的 拥有 OAuth2 客户端凭证端点 — 通过注册的服务账号/v1/admin/apikeys/register-client交换他们的client_id/client_secret在那里短暂存在ah-令牌。这与第三方无关 连接。
[!NOTE] 授权码流程总是涉及一个真实的浏览器同意步骤。A 仅凭 API 密钥无法以无头模式创建连接——必须使用操作用户 必须批准一次范围。
令牌所在的位置
已发放的令牌存储在 AiHummer 中 加密凭证库,不是在普通配置下。保险库使用信封加密(AES-256-GCM,使用在主密钥下的每租户数据密钥),并且机密信息从不被复制到模型上下文、提示或日志中。被撤销或已过期的连接不会留下任何可用的机密。
oauth/start ─▶ consent ─▶ code ─▶ oauth/callback (exchange at the provider) ─▶ access/refresh token ─▶ vault (encrypted)
由代理用户解决
连接的定义属性是它是 由代理用户解决当代理运行需要提供者的工具时,运行时会查找该回合运行代表的用户所拥有的连接,并使用他们的令牌。因此,与同一个代理交谈的两名员工将以各自的授权进行操作,并且只能看到各自授权允许的内容。
这就是使 Connections 适合个人、每用户集成的原因:每个人的访问都是隔离的、可审计的,并且可以单独撤销。
可用的集成
以下服务支持个人连接。启动 OAuth 需要在此服务器上完成提供商配置。
| 群组 | 服务 |
|---|---|
| 谷歌 | Gmail、谷歌日历、谷歌联系人、谷歌任务、谷歌云端硬盘、YouTube |
| 微软 | Outlook 邮件,Outlook 日历,OneDrive,Microsoft 待办事项 |
| 生产力 | Todoist、Asana、Jira Cloud、ClickUp、GitLab、Linear、monday.com |
| 健康与生活方式 | Fitbit、Oura 戒指、Strava、Spotify、三星 SmartThings |
对于可用的 OAuth 连接,请完成提供商的授权同意页面。签发的令牌会存入您的凭据库,并在工具使用该服务时选用。
OAuth 不可用时连接个人 Gmail
如果 Gmail OAuth 不可用,请向代理索取个人 Gmail 设置链接。使用该链接所属的 AiHummer 账户登录后打开。如果提示账户不匹配,请登录对应账户并重新打开链接。表单会保存独立的私人连接,与代理邮箱分别使用。
请在 Google 账户设置中创建应用专用密码。账户须已启用两步验证并支持此功能。在表单中直接输入 Gmail 地址及生成的应用专用密码。IMAP/SMTP 参数会自动设置。应用专用密码设置 · Google 账户帮助。
保存后,请代理读取您的个人 Gmail 以验证访问。mail 工具通过 account=personal_gmail 选择个人 Gmail,通过 account=agent 选择代理邮箱。每次操作都会检查当前访问权限及选定凭据。保存成功确认凭据已存储。读取成功确认邮箱可访问。发送邮件需要您的指示。如果发送结果尚未确认,请先检查原始操作回执,再考虑下一次尝试。
在管理界面中管理连接
从管理员界面,操作员可以:
- 查看每个用户连接了哪些提供商以及每个令牌的健康状况。
- 开始新的连接(启动所选提供商的授权流程)。
- 撤销连接,这将移除保险库条目并禁用解析。
连接要么是 个人的 (由特定用户拥有,该用户可以断开它们)或 与工作区共享 (标记为“共享工作区”;他们不能个人断开连接)。一个提供者可以持有 多个账户: “+ 账户”按钮会要求输入一个标签,并保存同一提供商的另一个凭证——例如,多个 Google 日历或邮箱。
因为底层凭证是个人的,所以当一个操作必须归因于特定人的授权并受其限制,而不是工作区的账户时,连接通常是最合适的工具。
接下来去哪儿
- 个人凭证与共享凭证 ——完整 范围模型以及何时选择每种模型。
- 自带密钥的大型语言模型提供商 — 自带模型密钥 每位租户。
- 市场概览与等级 ——哪里 适用于基于 OAuth 的集成。