Hermes Agent 如何配置第三方 OAuth2 认证

想要实现 Hermes Agent 与企业统一身份认证系统的平滑集成吗？如果发现当前系统仅支持本地账户登录，这通常意味着 OAuth2 认证流程尚未正确配置——可能是功能未启用，或是关键参数填写有误。无需担忧，本指南将提供一套详尽的配置步骤，助您高效打通这一核心认证链路。

一、启用 OAuth2 认证类型

此步骤是集成的基石，旨在将 Hermes Agent 的认证模式从内置的本地验证，切换为依赖外部身份提供商（IdP）进行统一鉴权。这使其能够融入企业现有的单点登录（SSO）体系。

具体操作流程如下：

1. 定位并打开 Hermes Agent 的主配置文件：~/.hermes/config.yaml。

2. 在文件中找到 backend.auth 配置节点。

3. 将其中的 type 字段值，由默认设置修改为 "oauth2"。

4. 保存并关闭配置文件。至此，认证类型的切换即告完成。

二、配置 IdP 元数据参数

仅启用 OAuth2 类型还不够，必须告知 Agent 具体对接哪个身份提供商。本步骤即是为其注入企业 IdP 的“连接凭证”，确保授权请求与令牌交换能准确无误地进行。

您需要在 config.yaml 文件的 backend.auth 区块下，准确填写以下三个核心参数：

　　client-id：相当于 Agent 在 IdP 处注册的客户端标识，需从企业 IdP 管理后台获取。

　　token-url：用于交换访问令牌的端点地址，通常形如 https://auth.example.com/oauth/token。

　　authorization-url：用于获取授权码的端点地址，例如 https://auth.example.com/oauth/authorize。

正确配置这些端点信息，是建立可信通信通道的前提。

三、安全注入客户端密钥

client-secret 属于高度敏感信息，直接明文存储在配置文件中存在安全风险。推荐采用动态命令读取的方式，以符合安全最佳实践。

1. 首先，将客户端密钥妥善存储于安全的密码管理工具中，例如 pass、1Password CLI 或 HashiCorp Vault。

2. 随后，在 config.yaml 中，不应直接写入密钥明文，而是配置一个命令字段：client-secret.cmd: "pass show oauth/client-secret"。

3. 最后，务必确保运行 Hermes Agent 的系统用户具备执行上述命令并成功读取密码的权限。这种方式实现了密钥的按需使用，且不落盘，提升了安全性。

四、配置用户属性映射规则

成功登录后，需将 IdP 返回的用户信息（声明/Claims）映射为 Hermes Agent 内部可识别的用户属性与角色。此步骤定义了身份信息的转换规则。

1. 在 config.yaml 的 backend.auth 配置节下，新增一个 user-attribute-map 子区块。

2. 在此区块内指定关键字段的映射关系。典型示例如下：

　　username: "email" —— 表示将用户邮箱映射为系统内的唯一用户名。

　　roles: "groups" —— 表示将 IdP 声明中的 groups 字段内容直接提取并赋予为用户角色。

3. 若您的 IdP 未提供类似 groups 的角色声明字段，可通过配置 default-roles 字段，为所有通过认证的用户赋予一个默认的基础角色，以确保其具备最低限度的系统访问权限。

五、验证 OAuth2 流程可用性

全部配置完成后，必须进行端到端的流程验证，以排查网络策略或 IdP 侧可能存在的配置疏漏，确保集成彻底成功。

1. 重启 Hermes Agent 服务，然后访问其登录页面，点击新出现的 OAuth 登录按钮。

2. 观察浏览器是否正常重定向至企业 IdP 的授权页面。请特别注意浏览器地址栏中 redirect_uri 参数的值，必须与您在 IdP 控制台注册的回调地址完全一致。

3. 完成 IdP 端的授权操作后，立即查看 Hermes Agent 的应用程序日志。若发现类似 "OAuth2 callback received, code exchanged for token" 的记录，则表明授权码已成功兑换为访问令牌。

4. 最终，检查 ~/.hermes/auth.json 文件，确认其中已正确写入新用户的 access_token 和 id_token。若所有环节均无误，则标志着 Hermes Agent 的 OAuth2 第三方认证集成已全部完成。