OAuth 受保护资源元数据

OAuth 受保护资源元数据端点 (RFC 9728) 允许 MCP 客户端发现哪个 OAuth 授权服务器保护 AACWorkflow 的 API，无需事先配置。这启用与 Claude、ChatGPT 和其他 MCP 宿主的无缝集成。

发现端点

GET /.well-known/oauth-protected-resource

{
  "resource": "https://aacworkflow.example.com/mcp",
  "authorization_servers": ["https://aacworkflow.example.com"],
  "scopes_supported": [
    "issues:read",
    "issues:write",
    "comments:read",
    "comments:write",
    "agents:read",
    "agents:write",
    "runtimes:read",
    "autopilot:run",
    "dashboard:read"
  ],
  "bearer_methods_supported": ["header"]
}

字段	含义
`resource`	受保护的 MCP 资源 URL
`authorization_servers`	可为此资源颁发访问令牌的 OAuth 授权服务器 URL 数组
`scopes_supported`	资源识别的范围列表
`bearer_methods_supported`	令牌如何传递 (`header` = `Authorization: Bearer <token>`)

WWW-Authenticate header 发现

当 MCP 客户端在没有令牌或令牌无效的情况下请求受保护资源时，服务器以 401 Unauthorized 应答并包含 WWW-Authenticate header：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://aacworkflow.example.com/.well-known/oauth-protected-resource"

此 header 告诉客户端：「此资源受 OAuth 保护。从此 URL 获取元数据以了解如何认证。」

客户端然后：

从 resource_metadata 中的 URL 获取元数据
读取 authorization_servers 找到注册和获取令牌的位置
使用元数据完成 OAuth 流程
使用新访问令牌重试请求

流程：零配置客户端

仅知道 AACWorkflow API URL 的客户端可以引导认证：

客户端: GET /api/issues
       (无 Authorization header)

服务器: 401 Unauthorized
       WWW-Authenticate: Bearer resource_metadata="https://aacworkflow.example.com/.well-known/oauth-protected-resource"

客户端: GET /.well-known/oauth-protected-resource
服务器: 200 OK
       {
         "authorization_servers": ["https://aacworkflow.example.com"],
         "scopes_supported": ["issues:read", "issues:write", ...],
         ...
       }

客户端: 使用 https://aacworkflow.example.com 启动 OAuth
       (从 /.well-known/oauth-authorization-server 发现 AS 元数据)
       完成 auth-code + PKCE 流程
       接收访问令牌

客户端: GET /api/issues
       Authorization: Bearer <access_token>
服务器: 200 OK
       [issue 列表]

RFC 9728 合规性

元数据端点符合 RFC 9728 — OAuth 2.0 受保护资源元数据：

必需字段： resource、authorization_servers、scopes_supported
可选字段： bearer_methods_supported (为清晰起见；仅使用 header)
缓存头： 响应包含适当的 cache-control 指令

与授权服务器元数据集成

受保护资源元数据端点与授权服务器元数据端点协同工作：

端点	RFC	目的
`/.well-known/oauth-protected-resource`	9728	发现保护资源的 AS
`/.well-known/oauth-authorization-server`	8414	发现 AS 端点和能力

完整引导流程：

1. 尝试访问 /api/issues → 401 + WWW-Authenticate header
2. 获取 /.well-known/oauth-protected-resource → 学习 AS URL
3. 获取 /.well-known/oauth-authorization-server → 学习端点
4. 在这些端点完成 OAuth 流程
5. 使用令牌重试

用例

Claude (通过 MCP)

Claude.ai 或 Claude Desktop 中的 Claude 插件：

用户仅提供 AACWorkflow URL
Claude 获取受保护资源元数据
Claude 呈现 OAuth 登录
用户授权；Claude 接收令牌
Claude 现可代表用户调用 MCP 工具

ChatGPT

ChatGPT 连接器设置：

用户在 ChatGPT 设置中输入 AACWorkflow URL
ChatGPT 获取受保护资源元数据以发现 AS
ChatGPT 处理 OAuth 流程（用户看到登录）
ChatGPT 安全存储令牌
ChatGPT 可在随后的对话中调用工具

自定义 MCP 服务器

包装 AACWorkflow 的自定义 MCP 服务器：

读取受保护资源元数据
验证资源 URL 匹配
检查所有必需范围在 scopes_supported 中
知道恰好在哪发送 OAuth 请求

无需手动配置授权服务器 URL。客户端从元数据读取。

安全

元数据是公开 — 不需认证
元数据是可缓存 — CDN/浏览器缓存可以
元数据是静态 — 授权服务器 URL 变化不频
令牌验证仍需完整范围和签名检查；元数据仅供发现

OAuth 受保护资源元数据

本页目录