AI agent 可以读取公开页面；但当它需要读取私密发票、创建客服工单、修改订阅，或调用受保护 API 时，问题就从“发现内容”变成了身份与权限。
正确做法不是发布一张模糊的“欢迎 agents”页面，也不是让用户把密码交给 agent。应该把边界说清楚：什么是公开的、什么需要用户同意、authorization server 在哪里，以及客户端究竟想访问哪个 protected resource。
这篇文章把 Auth.md 与 OAuth Metadata wiki 扩展成可执行的发布流程。它与 API Catalog SEO、MCP Server Card 和更大的 Agent SEO audit 集群相连。
先分清两层
OAuth metadata 和 auth.md 都和 agent 访问有关，但不能互相替代。
| 层级 | 它回答什么 | 当前状态 | 何时发布 |
|---|---|---|---|
| OAuth authorization server metadata | issuer、authorization endpoint、token endpoint、keys 和支持的 scopes 在哪里？ | IETF 标准：RFC 8414 | 你运营 OAuth authorization server |
| OAuth protected resource metadata | 哪些 authorization servers、scopes 和政策适用于资源？ | IETF 标准：RFC 9728 | 你提供 API 或其他 protected resource |
auth.md | agent 如何代表用户注册服务？ | 项目维护的演进中协议，不是 IETF 标准 | 你明确支持其注册流程 |
| 面向人的认证文档 | 用户能授权、撤销和升级什么操作？ | 产品文档 | 只要对外提供受保护工作流就应具备 |
实验性的注册约定不能替代 OAuth 配置、consent、scopes 或访问控制；反过来，标准 metadata 文件也不会说明产品的 agent 特定注册政策。
auth.md 项目把托管的 AUTH.md 文件描述为面向参与 agent 的说明，并提供 service 与 agent-provider 示例。应把它当作兼容性选择，而不是假设每个 crawler 或 AI assistant 都会理解的通用信号。
从资源出发，不要从 Agent 出发
多数团队的第一问不应是“AI agent 怎样注册”，而是“我们到底准备让获授权客户端访问什么资源”。
发布 metadata 前，先建立访问清单：
| 清单字段 | 示例 | 为什么重要 |
|---|---|---|
| 资源 | https://api.example.com/v1/invoices | 避免用泛化登录页代替真实服务 |
| 用户操作 | 读取发票、创建客服工单 | 定义 consent 覆盖范围 |
| 必要 scope | invoices.read | 让权限足够小且可审查 |
| Authorization server | https://auth.example.com | 给客户端一个可验证 issuer |
| 撤销路径 | 账户安全设置 | 用户可以收回 delegated access |
| 负责人和复查日期 | Identity platform team、每季度 | 使变更与弃用可追溯 |
不要因为方便就给 agent 一个覆盖整套账户的凭据。应使用最小权限 scopes、可见的用户同意，以及不依赖 agent 也能找到的撤销路径。
先发布标准化 Discovery
如果运营 OAuth，应在加入面向 agent 的约定之前先发布并验证标准 metadata。
RFC 8414 定义 authorization server metadata。客户端可以从如下 well-known URL 获取 JSON：
https://auth.example.com/.well-known/oauth-authorization-server
该文档至少标识 issuer、authorization endpoint 与 token endpoint；还可以公布 keys、支持的 scopes、registration endpoint 以及 token endpoint 接受的认证方式。
RFC 9728 则补足 protected resource 一侧。资源可发布：
https://api.example.com/.well-known/oauth-protected-resource
该文档可以标识 protected resource、相关 authorization servers、支持的 scopes、面向用户的文档和政策 URL。401 响应还可以通过带有 resource_metadata 的 WWW-Authenticate header 告知客户端 metadata 的位置。
示意性的 protected-resource metadata：
{
"resource": "https://api.example.com/",
"authorization_servers": ["https://auth.example.com"],
"scopes_supported": ["tickets.read", "tickets.write"],
"resource_name": "Example Support API",
"resource_documentation": "https://docs.example.com/support-api",
"resource_policy_uri": "https://example.com/api-policy"
}
这只是 discovery 信息，不是授权决定。API 仍必须验证 token、执行 scopes、检查 audience 与 issuer，并保留正常 abuse control。
判断 auth.md 是否适配
只有能书面回答以下问题后，才考虑加入 auth.md：
- 是否有真实自助工作流允许 agent 为用户发起？
- 哪些操作可在用户验证前执行，哪些必须验证后执行？
- 产品能否区分 agent、用户和所连接的服务？
- 是否提供可审查的 consent 页面、账户恢复和撤销机制？
- 能否长期支持该流程，而非只发布一次性实验？
若任何一项答案是否定的，就只保留 OAuth metadata 与正常文档。内容站、宣传站或只接受人类手动注册的产品，不需要为了显得“agent-ready”而强行发布 auth.md。
如果确实适配，让 AUTH.md 保持诚实且范围有限。链接至条款、隐私政策、用户支持、安全联系人，以及管理受保护资源的 OAuth metadata；不要暴露凭据、内部 endpoint，或绕过 consent 的说明。
五步发布流程
- 分类服务。 将入口标记为公开内容、受保护读取，或受保护动作。能公开的文档尽量不要求认证。
- 定义最小 scopes。 权限围绕操作命名，而不是围绕整个账户；读取与写入 scopes 分开。
- 发布 OAuth metadata。 在正确 well-known URL 提供 RFC 8414 authorization-server metadata 与 RFC 9728 protected-resource metadata。
- 说明人类控制面。 在人和客户端都能找到的地方发布支持、政策、consent 与撤销路径。
- 只为已支持流程添加 auth.md。 服务支持时才发布可维护的
AUTH.md，并用非生产账户测试注册旅程。
这个顺序先建立可互操作 OAuth 配置，只有产品能对结果负责时才增加 agent 专用注册。
验证线上流程
curl -i https://auth.example.com/.well-known/oauth-authorization-server
curl -i https://api.example.com/.well-known/oauth-protected-resource
curl -i https://api.example.com/v1/tickets
| 检查项 | 通过条件 |
|---|---|
| HTTPS 与 issuer | Metadata 通过 HTTPS 访问，issuer 与预期 authorization server 一致 |
| JSON 与 content type | 文档返回有效 JSON 与合适 response type |
| 资源与服务端对应 | Protected resource 只列出实际信任的 authorization servers |
| Scope 复查 | Scopes 范围小、有文档，并与实际 API enforcement 对应 |
| 未授权响应 | 受保护请求返回有用 401 challenge，且不泄露秘密 |
| 用户控制 | Consent、撤销、支持和安全路径清晰且可用 |
| 协议声明 | auth.md 是可选支持集成，不是 SEO 或访问保证 |
Bot Simulator 与 Technical SEO 可以帮助确认公开文档可访问、可阅读；它们不能证明授权设计安全。真实流程仍需 identity、产品和安全负责人测试。
常见错误
避免为并未实际执行 OAuth 的资源发布 metadata，或在 API 支持按操作切分 scopes 时只列出宽泛权限。不要把 agent 注册文档当作高影响动作可自动执行的许可。
不要把 consent 或撤销藏在不透明账户流程中。保持 AUTH.md 与线上 OAuth issuer、endpoints 和政策一致。不要声称 metadata 能提高 Google 排名、AI citation 或保证所有 agent 兼容。
OAuth 安全最佳实践建议 authorization server 发布 metadata，并让客户端在可用时用它进行配置；但这仍不能取代 redirect URI 处理、token 验证、钓鱼防护和权限审查。
Fennec 用户下一步
- 确认受保护动作合理、经用户授权且可撤销。
- 发布最新文档；只有能力真实存在时，才与 API Catalog SEO 或 MCP Server Card 连接。
- 从线上域名验证 RFC 8414 与 RFC 9728 metadata。
- 用 Agent SEO Audit 和 Bot Simulator 检查公开 discovery surface。
- 只有 OAuth 与用户控制层可靠后，才考虑
auth.md。
对于纯内容网站，保持基础设施健康即可：robots.txt、最新 sitemap、有帮助的内链和有用公开页面。认证 metadata 不能替代这些基础。
Sources
- RFC 8414：OAuth 2.0 Authorization Server Metadata
- RFC 9728：OAuth 2.0 Protected Resource Metadata
- RFC 9700：OAuth 2.0 Security Best Current Practice
- RFC 8628：OAuth 2.0 Device Authorization Grant
- auth.md reference implementation 与协议项目
问答
auth.md 能替代 OAuth 吗？
不能。auth.md 是正在演进的 agent 注册协议；OAuth authorization server metadata 与 protected resource metadata 仍是说明授权配置的标准化方式。
纯内容网站需要发布 OAuth metadata 吗？
通常不需要。只有在运营真实 authorization server 或 protected resource 时才发布 OAuth metadata。内容站应优先解决可抓取性、清晰文档和正常 Technical SEO。
认证 metadata 会提升 AI 搜索排名吗？
不会。它可以帮助兼容客户端理解如何访问真实受保护服务，但不保证收录、排名、citation 或 agent 采用。
