01谁在发起访问？
验证当前用户身份，确认访问不是来自匿名或无法追溯的主体。
SECURITY TOKEN SERVICE FOR AGENTS
让 Agent 的每一次资源访问
都有身份、有边界、有证据
STSforAgent 是 Agent 平台的授权决策与编排中枢。它在 Agent 访问资源前识别用户、验证 Agent 委托范围、裁决具体资源权限，并把短时凭证注入、流量转发和审计记录串成统一闭环。
STS 不替代业务系统，也不直接承载业务能力。
它负责把用户身份、Agent 能力、资源权限、策略和实际访问组织成一条受控链路，让业务系统不必各自重复实现 Agent 授权。
一、STS 回答三个核心问题
一次 Agent 访问不是单纯的“接口鉴权”，而是用户委托、Agent 能力和资源约束的组合决策。
02通过哪个 Agent？
确认用户是否允许该 Agent 在当前会话或任务中执行相应能力。
03访问什么资源？
结合资源、环境、属性和策略，决定本次访问允许、拒绝或附带哪些约束。
二、为什么需要统一授权中枢
如果把长期凭证直接交给 Agent，身份、能力和资源往往会脱节，风险边界也难以持续运营。
01身份与权限脱节
无法清楚回答哪个用户通过哪个 Agent 使用了什么能力。
02长期凭证权限过大
凭证一旦泄露，影响范围和持续时间难以控制。
03策略口径分散
不同业务系统分别实现授权，规则难以统一和复用。
04Agent 出站目标失控
缺少统一白名单时，Agent 可能访问未登记地址或扩大资源范围。
05决策与调用无法统一审计
授权结果、实际访问和策略变更分散在不同系统中。
三、L1 / L2 / L3 三层授权模型
三层令牌逐层收窄权限：身份不是委托，委托也不是最终资源访问许可。
由 Keycloak 等身份系统签发，经 auth-gw 验证，建立可追溯的用户身份。
有效期：由身份系统决定
→
表达用户对某个 Agent 的会话或任务授权上界，关联用户、Agent 和任务。
典型有效期：约 15 分钟
→
针对具体资源的短时决策结果，可携带约束，仅在访问发生前按需签发。
典型有效期：约 60 秒
关键设计：代理模式下，L3 由 Gateway 在服务端注入下游请求，Agent 本身拿不到 L3 明文。
四、一次受控访问如何完成
策略在访问发生前执行；只有明确允许时才生成短时凭证并访问下游。
确认目标 Host、Connection 和资源已经登记。
验证 L1 用户身份、L2 Agent 能力和任务上下文。
汇集注册信息与 PIP 属性，由 OPA 返回 allow / deny。
允许时签发 L3，并由 Gateway 注入下游请求。
流式返回业务结果，并回写决策、会话和调用审计。
五、As-Built 技术架构
控制与执行分离：控制面负责“是否允许”，数据面负责“如何安全完成访问”。
调用方
浏览器 / 运营人员
AgentHub / Agent
运维 / CI
CP控制面 · FastAPI
验证 L1/L2、构建决策上下文、调用 OPA、编排 L3 签发、维护注册表和 PostgreSQL 审计数据。
GW数据面 · Node Gateway
承载站点反代、MITM 出站代理和显式 Connection 代理，约束目标、注入 L3、流式转发并回写审计。
PO策略面 · OPA + PIP
管理策略 Bundle、Revision、Release、属性目录和 Provider，完成动态属性采集与 allow / deny 计算。
OP运营面 · Console + Ops Agent
提供决策审计、策略运营、Agent 注册表、网关监测、告警和确认后执行的运营操作。
外部依赖
Keycloak / auth-gw
OPA / PostgreSQL
Portal / Tools
六、三种接入方式
业务站点入口与 Agent 代理入口用途不同，必须分开配置。
| 接入方式 | 典型场景 | 匹配与约束 | 未命中结果 |
|---|---|---|---|
| 站点路由 | 浏览器或客户端直连业务站点 | gw_routes：入口 Host + path_prefix |
404 no_route |
| MITM 出站代理 | Agent 通过 HTTP(S)_PROXY 访问 Portal / Tools |
Connection metadata.mitm.hosts + port 白名单 |
403 mitm_host_denied |
| 显式连接代理 | Agent 使用 /gw/proxy/:connection/* |
仅允许已注册 Connection，仍执行资源解析与 L3 决策 | 拒绝未注册连接及 SSRF |
七、策略如何完成决策
STS 将相对稳定的注册关系、动态属性和策略规则组合起来，形成可解释的访问结果。
Agent、Tool、Connection、User Grant 和 Route。
用户、应用、租户、环境和 Portal RBAC 等属性。
基于 Bundle 和上下文返回允许、拒绝及原因。
允许时签发短时 L3；所有结果进入统一审计。
八、关键安全与运营边界
STS 的价值不仅是“能签令牌”，更在于默认拒绝、最小授权、服务端注入和可持续运营。
Agent 只能访问已注册 Connection；未登记目标不做模糊兜底。
代理模式由 Gateway 注入，减少短时资源令牌暴露面。
L3 仅代表一次具体资源决策，不作为长期凭证保存。
策略变更和 Ops Agent 高风险动作遵循建议、确认、执行、审计。
生产环境使用 auth-gw；本地签名方式仅用于开发与测试。
PostgreSQL 保存决策、策略、属性、注册表、网关日志和运行配置。