Auth.md 与 OAuth Metadata
Auth.md 和 OAuth metadata 帮助 AI agents 理解认证方式、授权服务器、受保护资源、scope 和用户授权边界。
发布于 2026-07-04
·
更新于 2026-07-22
·
2 分钟阅读
Auth.md 与 OAuth Metadata
“Auth.md” 是认证说明文档的非正式叫法，不是 IETF 标准、已注册的 well-known URI，也不能替代 OAuth discovery。OAuth metadata 才是让客户端定位授权服务器、理解受保护资源的标准化层。
对 agent-ready 网站来说，核心原则很简单：不要让 agent 猜你的认证模型。
区分说明文档与协议元数据
| 层级 | 受众 | 适合承载的内容 |
|---|---|---|
| 产品文档 | 用户与 agent 开发者 | 登录流程、授权预期、示例、支持和安全联系方式 |
| Authorization server metadata | OAuth 客户端 | issuer、授权端点、token 端点、grant 与签名能力 |
| Protected resource metadata | OAuth 客户端 | resource identifier、授权服务器、scope 与 bearer token 方法 |
任何公开 Markdown 或 metadata 文件都不应包含 secret、client credential、私有端点或 access token。
应该说明什么
- 哪些公开资源不需要认证
- 哪些工作流需要用户授权
- OAuth authorization server metadata
- Protected resource metadata
- 支持的 scopes
- token audience 和 issuer 要求
- 人类支持或安全联系渠道
SEO 与产品建议
当 agents 不只是读页面，而是代表用户执行动作时，认证元数据会变得重要。产品网站可能允许 agent 读取发票、比较套餐、提交客服工单或开始结账。这些工作流都需要明确授权和边界。
公开内容保持公开。私有工作流必须置于用户同意后的授权层之后。认证解决“谁在操作”，授权解决“可以做什么”，有效文档不能把两者混成一件事。
实施顺序
- 按 RFC 8414 在 issuer 对应的 well-known 位置发布授权服务器 metadata。
- 对需要发现授权服务器与 scopes 的 API 发布 RFC 9728 protected resource metadata。
- 在真实客户端流程中验证 issuer、audience、redirect URI、PKCE、scope、token 时效与撤销行为。
- 先保证机器可读端点正确，再补充易读文档。
- 为示例标明版本、复查日期与安全联系人。
Agent-readable index 可以链接这些端点，但不应另造一套并行认证协议。
常见失败方式
- 授权服务器 metadata 的 issuer 与实际 token issuer 不完全一致。
- 受保护资源接受了发给其他 audience 的 token。
- 文档声称支持的 scope 比 consent screen 或 API 实际执行的更宽。
- 公共 discovery 文件暴露内部主机名或运营秘密。
- 高风险动作没有在执行前取得用户的最新确认。
除了成功路径，还应测试过期 token、错误 audience、scope 缺失、授权撤销和请求重放，确保它们都能稳定失败。