配置 OIDC 身份认证

默认情况下，Holon 使用本地 Control Token 进行身份验证。如果需要部署在共享团队服务器或对外提供服务，可以切换为 OpenID Connect (OIDC) 认证。团队成员通过公司现有的身份提供商 (IdP) 登录，Holon 会在每条触发 Agent 的消息中记录具体的操作人身份。

本指南涵盖在 IdP 中注册客户端、配置 Holon 运行时、调整会话超时策略以及验证登录流程。

前置准备

一个可供用户访问的 Holon 实例（例如通过 --access tunnel、--access tailnet 或反向代理对外暴露）。
一个兼容 OIDC 的身份提供商，如 Keycloak、Okta、Authentik、Google Workspace 或 Microsoft Entra ID。
在该 IdP 中创建新应用客户端的管理权限。

安全提示： 在生产环境中，Holon 要求 OIDC Issuer URL 和回调地址必须使用 HTTPS。仅当回调主机为 localhost 时才允许使用 HTTP。

第一步：在 IdP 中注册 Holon 应用

在你的身份提供商管理后台中新建一个 OpenID Connect 应用：

Client ID：指定客户端标识符，例如 holon。
客户端身份验证（Client Authentication）：启用机密客户端（Confidential Client）并生成 Client Secret。
重定向 URI（Redirect URI）：配置回调地址：
```
https://<your-holon-host>/api/auth/oidc/callback
```
如果在本地开发环境测试（端口 7878），使用：
```
http://localhost:7878/api/auth/oidc/callback
```
作用域（Scopes）：确保客户端至少申请了 openid、profile 和 email。

记录下 IdP 的 Issuer URL、Client ID 与 Client Secret。

第二步：将 Client Secret 写入环境变量

不要把凭据密钥硬编码在磁盘上的配置文件中。在 Holon daemon 运行的环境中设置环境变量：

export HOLON_OIDC_CLIENT_SECRET="your-oidc-client-secret"

如果使用 systemd 服务或容器运行 Holon，请将该变量添加到服务单元文件或环境变量配置中。

第三步：配置 Holon 运行时

使用 holon config set 设置认证模式与提供商参数：

# 切换认证模式为 OIDC
holon config set auth.mode "oidc"

# 设置 Issuer URL（必须支持 /.well-known/openid-configuration 元数据发现）
holon config set auth.oidc.issuer_url "https://auth.example.com/realms/team"

# 设置已注册的 Client ID
holon config set auth.oidc.client_id "holon"

# 指定存放 Client Secret 的环境变量名
holon config set auth.oidc.client_secret_env "HOLON_OIDC_CLIENT_SECRET"

# 设置公开的回调地址（在反向代理后部署时建议显式设置）
holon config set auth.oidc.redirect_uri "https://holon.example.com/api/auth/oidc/callback"

第四步：配置会话策略（Session TTL）

Holon 会为浏览器颁发 HttpOnly Session Cookie，为 API 客户端颁发 Session 凭据。你可以按需配置会话的有效期：

# 空闲超时时间（秒，默认 86400，即 24 小时）
# 每次用户发起请求或交互都会刷新该计时器。
holon config set auth.session.idle_ttl_seconds 43200

# 可选的绝对超时时间（秒，必须大于或等于 idle_ttl_seconds）
# 达到该时长后会话强制失效，无论中途是否活跃。
holon config set auth.session.absolute_ttl_seconds 604800

如果不需要绝对超时上限、希望活跃用户一直保持登录状态，可以省略 auth.session.absolute_ttl_seconds 或将其设为 null。

第五步：重启 daemon 生效

认证模式变更需要重启 daemon 后生效：

holon daemon restart

如果是前台运行调试：

holon serve --access tunnel

验证与使用

1. 从 Web GUI 登录

在浏览器中打开 https://<your-holon-host>/login。
登录页面检测到 OIDC 模式后，会显示 Continue with organization login 链接。
点击该链接，浏览器将跳转至你的身份提供商登录页。
登录完成后，IdP 会重定向回 /api/auth/oidc/callback。Holon 将设置安全的 holon_session Cookie 并自动跳到控制面板首页 (/)。

2. 检查会话身份

通过 Session 检查接口确认当前身份：

curl -b "holon_session=<session-cookie>" https://<your-holon-host>/api/auth/session/me

或者将 Session 凭据放在请求头中：

curl -H "Authorization: Bearer <session-token>" https://<your-holon-host>/api/auth/session/me

接口会返回当前已认证用户的身份与认证方式：

{
  "ok": true,
  "user_id": "oidc-550e8400-e29b-41d4-a716-446655440000",
  "display_name": "Alice Chen",
  "auth_method": "oidc"
}

3. 查看消息归属（Message Attribution）

在 OIDC 模式下，用户通过 Web GUI 或控制面 API 发送的每一条 Prompt，都会在消息 origin 中记录发送者身份：

actor_id：用户在 Holon 中的稳定标识符（格式为 oidc-<uuid-v4>）。
actor_display_name：发送时刻用户的显示名称（若 IdP 未提供姓名 claim 则回退为 actor_id）。

无论用户后续在 IdP 中是否修改昵称，历史消息都完整保留发送时刻的快照。审计任务记录或调用 GET /api/agents/{agent_id}/messages/{message_id} 时，可以清晰核对每个操作的发起人。

4. 退出登录

点击 Web GUI 界面上的退出登录，或调用登出接口：

curl -X POST -H "Authorization: Bearer <session-token>" \
  https://<your-holon-host>/api/auth/session/logout

该请求会销毁服务端的会话记录，并清理浏览器中的会话 Cookie。

常见问题排查

Redirect URI 不匹配：IdP 中配置的 Callback URL 必须与 auth.oidc.redirect_uri 完全一致，包括协议（https://）、端口以及路径后缀（/api/auth/oidc/callback）。
Issuer URL 无法解析或证书无效：Issuer URL 必须能在公网或内网正常解析，且在生产环境下必须使用受信任的 HTTPS 证书。
未读取到 Client Secret：检查 auth.oidc.client_secret_env 指定的环境变量是否在启动 daemon 的当前 shell 或服务环境中正确导出。
TTL 配置校验失败：如果设置了 auth.session.absolute_ttl_seconds，其数值必须大于或等于 auth.session.idle_ttl_seconds，否则启动时配置校验会报错。