diff --git a/architecture/constraints.md b/architecture/constraints.md index d3990b2..e25bc21 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -30,3 +30,9 @@ 通用变更约束:先做适用的 plan/check/diff,再操作现场;不将凭据和 Terraform state 写入知识库;不更新 homelab-infra 的冻结 `CHANGELOG.md`。 + +## 待评估草案 + +[独立 IAM 与 agent 身份草案](independent-iam-draft.md)(2026-09-25,draft)提出以 Hydra +解耦认证与签发,通过 OIDC 接入人类、machine 和 agent,并作为 Ayatori 的独立外部依赖。 +它尚未替代上表的人类身份、SPIFFE 或 DNS 约束;采纳时须显式修订这些边界。 diff --git a/architecture/independent-iam-draft.md b/architecture/independent-iam-draft.md new file mode 100644 index 0000000..0503fda --- /dev/null +++ b/architecture/independent-iam-draft.md @@ -0,0 +1,171 @@ +--- +title: 独立 IAM 草案:人类、机器与 AI Agent 的统一应用接入 +status: draft +last_reviewed: 2026-09-25 +last_verified: null +sources: + - 维护者于 2026-09-25 的架构讨论与草案记录要求 +--- + +# 独立 IAM 草案:人类、机器与 AI Agent 的统一应用接入 + +本页记录设计意图,状态为 **draft**;尚未采纳为现役架构,也未部署或完成端到端验证。 +名称、资源模型、接口及具体实现均未定。本次仅整理讨论,不表示已启动迁移。 + +## 动机与首要目标 + +首要目标是降低下游应用集成成本。原生接入 SPIFFE 的应用覆盖有限,OIDC/OAuth 则已有 +广泛的应用与 CLI 生态。通过独立 IAM 集中处理身份验证,让应用沿用标准登录和授权流程, +即可接入人类、传统机器账户和 AI agent,无需每个应用自行验证 SVID 或集成 SPIRE。 + +维护者认为,现有方案缺少好用的、真正区分 AI agent 与传统 service account 的身份及 +授权模型,这是考虑自行建设的主要原因。拟自建的是主体语义、认证编排与授权能力, +OAuth2/OIDC 协议和 token 签发优先交给 Hydra。 + +Hydra 的核心价值是把“如何验证身份”与“如何完成标准授权流程并签发 token”解耦。 +统一 token 格式不是主要目标,也不要求所有应用 API 直接接受 Hydra token。 + +## 独立服务边界 + +IAM 应当能够独立部署、运行和恢复,不依赖 Ayatori 的 API、CRD、controller 或领域资源。 +Ayatori 是其消费者,依赖关系类似 OpenStack 其他服务对 Keystone 的依赖;这一类比 +不意味着复刻 Keystone 的全部 API 或功能。即使未来命名为 Ayatori IAM,也不改变边界。 + +| 部分 | 拟承担的职责 | +|---|---| +| 人类认证后端 | 人类登录、MFA、账号生命周期;可选 ZITADEL,过渡期保留 Samba AD | +| SPIRE | workload 身份证明与 SVID 签发,可辅助 machine 或 agent 认证 | +| Login / Consent 与身份授权服务 | 验证不同主体的证明,映射稳定身份,处理登录、授权、组和必要的动态审批 | +| Hydra | OAuth2/OIDC 流程、client 与 token 签发 | +| 下游应用 | 关联本地账号,执行应用自身权限,按原有机制签发或使用应用凭据 | + +```text +人类:交互登录 / 上游 IdP ──────┐ +机器:SPIFFE 等预配置身份 ─────┼→ 独立身份验证与授权 → Hydra → OIDC/OAuth 消费者 +Agent:人类授权 / SPIFFE / │ ├→ Gitea 等应用 + 后续专门认证方式 ──────┘ └→ Ayatori API server +``` + +Ayatori 使用裁剪的 kube-apiserver,目标是让它信任 Hydra 签发的 token 来验证身份, +再由自身 RBAC 执行资源授权。具体 token 类型、claims、audience 与 JWT authenticator +兼容性需要验证;不能预先把任意 Hydra access token 都视为 API server 可用凭据。 + +## 主体类型与认证方式分离 + +人类、machine、agent 是不同的主体类型,不能按所用认证协议决定分类。 +Agent 可以使用 SPIFFE 辅助证明执行环境,而仍然是 agent 主体,不必冒充传统机器账户。 +Agent 的负责人、委托人及当前执行实例也不应与 agent 自身身份混为一谈。 + +| 维度 | 传统机器账户 / CI | AI agent | +|---|---|---| +| 任务特征 | 预定义流程与资源范围 | 能理解任务、作出决策,可能跨应用并在执行中改变操作路径 | +| 权限需求 | 通常可以预先配置 | 潜在范围更广,可能执行中动态申请 | +| 授权方式 | 审核配置后按固定规则授予 | 基础权限与任务、会话或限时授权组合,由策略或人类批准 | +| 交互能力 | 固定程序处理约定流程 | 可使用 CLI、MCP 和 skills,自主组织请求并在需要时请求批准 | +| 审计语义 | 哪个 workload 执行了操作 | 哪个 agent、哪次执行、代表谁、依据哪次授权执行 | + +更广的潜在权限不等于常驻全权。动态批准应转化为服务端认可的授权和适当凭据, +不能由 agent 自报身份或声明 scope 就自动生效。申请、批准、期限、撤销以及下游已有 +会话和 token 的失效语义需要明确设计,不能假设 Hydra 自动提供完整实现。 + +认证入口保持可扩展: + +- Remote MCP 的 OAuth 可提供人类参与的授权入口。设计上允许人类在流程中确认或选择 + agent 身份、委托关系与权限,再由服务端绑定凭据。普通 MCP OAuth 并不自动定义 + agent 主体语义;具体绑定属于本方案要实现的能力。 +- SPIFFE 路径以经人类审核的 workload/身份绑定规则为信任来源,运行时验证证明是否 + 满足规则。交互批准和预配置批准都是可用的信任建立方式。 +- MCP 和 skills 是 agent 参与流程的工具及操作约定,本身不替代可验证凭据。 + 后续可以增加专门的 agent 认证方式,不必现在锁定一个唯一协议。 + +Agent 可以独立使用自身权限,也可以接受人类委托。人类授权 agent 不等于 agent +变成人类账号;需要时保留“agent A,经用户 B 授权”的关系与审计信息。 + +## 无浏览器的标准登录与 Gitea 示例 + +Authorization code flow 不要求必须使用图形浏览器。对于可通过 HTTP 完成的流程, +agent 可以用 curl/CLI 保存 cookies、跟随重定向、提交表单和身份证明,并到达 callback。 +必须保留 state、nonce、PKCE 等协议绑定;以 HTTP 客户端执行不意味着跳过这些校验。 +专用登录 helper 可以作为便利工具,但不是架构前提。 + +关键是 Login 服务支持 machine/agent 的身份证明,而不强迫它们完成人类密码、 +交互 MFA 等认证。Consent 按已有授权策略处理,必要时请求人类批准。 + +Gitea 的目标路径包含内外两层授权: + +```text +官方 tea CLI 发起 Gitea OAuth 授权 + → Gitea 经 OIDC 请求 Hydra 登录 + → Login 服务验证 agent 或 machine 的身份 + → 接受 login challenge,按策略完成 Hydra consent + → Hydra 回调 Gitea,Gitea 关联对应 bot 账号 + → 完成 Gitea 自身对 tea 的授权确认 + → Gitea 回调 tea,由 tea 完成 code 交换并取得 Gitea token + → tea 按 bot 的 Gitea 权限调用 API +``` + +这里 Hydra token 用于 Gitea 的身份登录,Gitea token 用于 CLI 调用应用 API。 +因此不要求 Gitea API 直接接受 Hydra bearer token,也不以自建 PAT 分发 broker 为前提。 +Bot 是下游账号映射,不代表所有 agent 共享一个万能 bot。 + +该路径尚未端到端验证。需要验证官方 CLI 的授权 URL/callback 交接、Gitea 本地会话与 +首次授权确认、账号关联和 scope,以及刷新与重新登录。其他应用可复用相同思路, +但支持 OIDC 不等于所有应用的无交互授权路径均已兼容,须按具体流程验收。 + +## 统一组与下游授权 + +集中维护较统一的粗粒度用户组,避免每个应用都独立维护一套 admins 成员关系。 +应用仍保留自身角色、team 和资源权限,由明确映射决定中央组在应用内的权限。 +统一组不等于一个全局 admins 自动拥有所有服务的管理权。 + +Agent 的动态授权需要落到应用可识别的 scope、角色、账号权限或其他已有授权机制上。 +仅在 Hydra token 中增加一个 claim,不意味着下游会自动执行或撤销相应权限。 +具体组名、角色模型及同步方式尚未确定。 + +## 人类后端、Samba AD 与 DNS 演进 + +人类同样使用这套独立 IAM。过渡期可以保留 Samba AD,通过 ZITADEL 连接 LDAP; +后续可以把人类账号迁出 Samba。ZITADEL 是候选后端,不是本草案已经确定的依赖。 +更换认证后端时应保持稳定主体与下游账号关联,避免按可变邮箱或用户名重新识别账号。 + +维护者认为 Samba AD 使用率较低,长期希望完全删除它。退役需处理 LDAP、Kerberos、 +SMB 域身份、域成员和域 DNS 等实际依赖,不能用网页登录迁移成功代替全部退出条件。 + +DNS 可独立评估迁往 PowerDNS Authoritative,主要考虑其 API 与资源成本。可从简单后端 +开始评估,不预先要求完整 Recursor/UI/数据库集群。实际资源占用尚未测量。 +AD 存续期间保留其域记录权威与动态更新边界;普通记录的迁移、Blocky/路由器解析链和 +最终域退役应分别设计。PowerDNS 不是 IAM 的必需组件。 + +## 与现役约束的关系 + +现役记录仍以 [架构约束](constraints.md)、[Authelia](../services/authelia.md) 和 +[SPIFFE/SPIRE](../services/spire.md) 为准。当前文档中的 Authelia 主 OIDC 入口、 +服务直接验证 SPIFFE 后签发自身 token 的规则,未因本草案而被替换。 + +本草案提出的变化是:增加独立的多主体 IAM,通过 Hydra 解耦认证与签发,让尚不支持 +SPIFFE 的下游复用 OIDC;并为 agent 增加区别于传统 service account 的身份授权语义。 +若采纳,应显式更新现役约束和相关服务文档。已能直接使用 SPIFFE 的服务无需强制改道。 +这也不构成恢复已归档 [workload-sts](workload-sts-history.md) 项目的决定。 + +## 后续验证问题 + +以下是草案的验证范围,不是已启动的实施任务或第二份动态进度表: + +1. 一个 SPIFFE 主体,通过官方 tea 的 OAuth 入口,用 CLI/HTTP 完成无浏览器登录, + 以指定 bot 成功调用 Gitea API,同时验证错误身份不能取得该账号。 +2. 人类和 agent 使用不同认证方式后,下游仍能通过同一 OIDC 接口识别正确身份与组。 +3. Ayatori 的 kube-apiserver 验证 Hydra token,并正确映射主体、组与 RBAC。 +4. Agent 动态申请权限,经过策略或人类批准后生效;到期与撤销行为覆盖下游凭据。 +5. 明确稳定 agent、执行实例、委托者的绑定方式,以及可供 agent 使用的 MCP/CLI 接口。 +6. 独立评估 Samba 退出条件、PowerDNS 资源成本与 DNS 迁移边界。 + +## 上游依据 + +以下文档用于说明协议与产品能力,不代表本方案已验证或已选定具体版本: + +- [Hydra Login / Consent 流程](https://www.ory.com/docs/oauth2-oidc/custom-login-consent/flow) +- [Gitea OAuth2 provider 与 tea 内置客户端](https://docs.gitea.com/development/oauth2-provider/) +- [tea 登录命令定义](https://pkg.go.dev/code.gitea.io/tea/cmd/login) +- [Kubernetes 身份验证](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) +- [ZITADEL LDAP 上游](https://zitadel.com/docs/guides/integrate/identity-providers/ldap) +- [PowerDNS Authoritative HTTP API](https://doc.powerdns.com/authoritative/http-api/index.html) diff --git a/guides/task-index.md b/guides/task-index.md index 9c7010a..e27dce9 100644 --- a/guides/task-index.md +++ b/guides/task-index.md @@ -10,6 +10,7 @@ last_reviewed: 2026-09-25 | 要做什么 | 先读 | 需要时再读 | |---|---|---| +| 评估独立 IAM 与 AI agent 身份 | [独立 IAM 草案](../architecture/independent-iam-draft.md) | 草案未替代现役身份架构;下游以 OIDC/OAuth 接入 | | 设计或实现 Ayatori 控制面能力 | [Ayatori 控制面边界](../architecture/ayatori-control-plane.md) | Ayatori 仓库 ADR、对应领域 API 与 adapter 文档 | | 发布新的 LAN Web 服务 | [发布新服务](publish-service.md) | [DNS](../services/lan-dns.md)、[Authelia](../services/authelia.md) | | 写 CI 或选择 Pod/VM runner | [Gitea / Actions](../services/gitea.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[SPIFFE](../services/spire.md)、[`ci-actions@v1`](https://git.ddupan.top/panxiao81/ci-actions/src/tag/v1) |