需配置多用户接入与细粒度权限管理，支持五种路径：一、oauth2企业sso集成；二、本地密码+yaml角色配置；三、飞书/企微组织架构同步；四、api key级控制；五、oauth2与api key混合模式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望多个用户协同使用 Hermes Agent，并对不同成员设置差异化访问权限，则需完成多用户接入配置与细粒度权限管理。以下是实现该目标的多种配置路径：
一、基于 OAuth2 的企业单点登录（SSO）集成
该方式适用于已部署统一身份认证系统（如 Azure AD、Okta、飞书/企业微信组织架构）的企业，可实现自动同步用户身份、角色与部门信息，并由 IDP 控制登录准入与会话生命周期。
1、在 Hermes Agent 配置文件 ~/.hermes/config.yaml 中启用 OAuth2 认证模块。
2、设置 backend.auth.type = "oauth2"。
3、填写 identity provider 提供的 client-id、token-url 与 authorization-url 参数。
4、将 backend.auth.client-secret.cmd 指向安全存储命令，例如 pass show oauth/client-secret。
5、启动服务后，所有用户将被重定向至企业 SSO 登录页，登录成功即自动映射为 Hermes 内部账户。
6、用户首次登录时，其所属部门、角色标签将通过 OIDC Claims 自动注入 Hermes 用户元数据中，用于后续权限判定。
二、本地密码认证 + 多用户 YAML 配置
该方式适用于小型团队或未部署 SSO 的环境，通过明确定义用户列表与角色分配，在本地完成身份识别与权限控制，无需外部依赖。
1、编辑 ~/.hermes/config.yaml，将 backend.auth.type 设为 "password"。
2、在 backend.auth.users 下逐条声明用户条目，每项包含 username、password_hash（推荐使用 bcrypt 加密）、roles 字段。
3、为每个用户指定 roles 值，例如 ["admin"]、["viewer", "reporter"] 或 ["editor"]。
4、在 backend.permissions 节点下定义角色能力矩阵，例如 admin 可执行 /api/v1/agents/* 与 /api/v1/config/* 全路径操作。
5、viewer 角色仅允许 GET /api/v1/history 与 GET /api/v1/status，禁止任何写操作。
6、保存配置后重启 Hermes Agent 服务，新用户即可通过 /login 页面凭用户名与密码登录。
三、飞书/企业微信组织架构自动同步
该方式利用飞书或企业微信开放平台提供的组织架构 API，定期拉取成员列表、部门树与自定义字段，实现用户账户与权限的零手动维护。
1、确保 Hermes Agent 已启用 gateway 模块并完成基础部署。
2、在 ~/.hermes/config.yaml 中设置 backend.auth.type = "wecom" 或 "feishu"。
3、配置对应平台的 app_id 与 app_secret，可通过 hermes gateway setup 向导自动填入。
4、启用 sync_org_from_platform: true，并设置 sync_interval_minutes（建议设为 1440，即每日同步一次）。
5、首次同步将自动创建用户账户，其 roles 字段依据组织架构中用户的部门或自定义标签字段映射生成。
6、同步后，用户登录即绑定其组织身份，权限策略将实时依据最新组织结构生效。
四、API Key 级细粒度控制
该方式面向需要按会话、按调用方隔离权限的场景，每个 API Key 可绑定独立角色与访问策略，适用于外部系统集成或临时协作者授权。
1、在 ~/.hermes/config.yaml 中启用 backend.auth.type = "apikey"。
2、在 backend.auth.apikeys 下添加键值对，key 为 SHA256 哈希后的 API Key 字符串，value 为 JSON 对象，含 roles 和 expires_at 字段。
3、为每个 key 明确指定 roles，例如 ["limited_editor"]，且必须在 backend.permissions 中预先定义该角色的权限边界。
4、设置 expires_at 为 RFC3339 格式时间戳，例如 "2026-05-31T23:59:59Z"，过期后该 key 将拒绝认证。
5、客户端请求需在 HTTP Header 中携带 Authorization: Bearer
6、每次请求均校验 key 有效性、角色权限及路径匹配，拒绝通配符路径覆盖核心管理接口。
五、OAuth2 与 API Key 混合模式
该方式兼顾内部员工统一身份治理与外部系统轻量接入需求，支持同一实例下两种认证机制并行运行，权限策略统一收敛至角色模型。
1、在 config.yaml 中设置 backend.auth.type = "hybrid"。
2、同时配置 backend.auth.oauth2 和 backend.auth.apikey 子节，各自保持完整参数结构。
3、定义 hybrid_auth.policy = "union"，表示任一认证方式通过即进入权限判定流程。
4、所有用户（无论来源）均映射至统一 roles 数组，例如 OAuth2 用户带入 ["department_x", "editor"]，API Key 用户带入 ["system_integration"]。
5、backend.permissions 中的规则按 roles 并集匹配，不支持 role 排斥逻辑，仅支持显式白名单声明。
6、审计日志中将标记 auth_method 字段为 "oauth2" 或 "apikey"，便于溯源分析。
