OAuth Защищённый Ресурс Метаданные

OAuth Protected Resource Metadata endpoint (RFC 9728) позволяет MCP клиентам обнаружить какой OAuth сервер авторизации защищает API AACWorkflow без требования предварительной конфигурации. Это позволяет seamless интеграцию с Claude, ChatGPT и другими MCP хостами.

Endpoint обнаружения

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"]
}

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 чтобы узнать как аутентифицироваться."

Клиент затем:

1. Получает метаданные из URL в resource_metadata
2. Читает authorization_servers чтобы найти где регистрировать и получить токены
3. Завершает OAuth поток используя метаданные
4. Повторяет запрос с новым access токеном

Поток: zero-configuration клиент

Клиент который знает только URL API AACWorkflow может bootstrappen авторизацию:

Клиент: 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", ...],
          ...
        }

Клиент: Инициирует OAuth с https://aacworkflow.example.com
        (обнаруживает AS метаданные из /.well-known/oauth-authorization-server)
        Завершает auth-code + PKCE поток
        Получает access токен

Клиент: GET /api/issues
        Authorization: Bearer <access_token>
Сервер: 200 OK
        [список issues]

Соответствие RFC 9728

Метаданные endpoint соответствует RFC 9728 — OAuth 2.0 Protected Resource Metadata:

• Требуемые поля: resource, authorization_servers, scopes_supported
• Опциональные поля: bearer_methods_supported (для ясности; используется только header)
• Cache headers: ответы включают appropriate cache-control директивы

Интеграция с authorization-server метаданными

Protected-resource метаданные endpoint работает в тандеме с authorization server метаданные endpoint:

Полный bootstrap поток:

1. Попытайтесь получить доступ /api/issues → 401 + WWW-Authenticate header
2. Получите /.well-known/oauth-protected-resource → изучите AS URL
3. Получите /.well-known/oauth-authorization-server → изучите endpoints
4. Завершите OAuth поток на этих endpoints
5. Повторите с токеном

Use cases

Claude (через MCP)

Claude плагин в Claude.ai или Claude Desktop:

1. Пользователь предоставляет только AACWorkflow URL
2. Claude получает protected-resource метаданные
3. Claude представляет OAuth логин
4. Пользователь авторизует; Claude получает токен
5. Claude теперь может вызывать MCP инструменты от имени пользователя

ChatGPT

ChatGPT коннектор установка:

1. Пользователь вводит AACWorkflow URL в настройках ChatGPT
2. ChatGPT получает protected-resource метаданные чтобы обнаружить AS
3. ChatGPT обрабатывает OAuth поток (пользователь видит логин)
4. ChatGPT сохраняет токен безопасно
5. ChatGPT может вызывать инструменты в следующих диалогах

Пользовательские MCP серверы

Пользовательский MCP сервер который обёртывает AACWorkflow:

1. Читает protected-resource метаданные
2. Проверяет что ресурс URL совпадает
3. Проверяет что все требуемые scopes в scopes_supported
4. Знает точно где отправлять OAuth запросы

Безопасность

• Метаданные public — не требует аутентификации
• Метаданные cacheable — CDN/browser кеширование в порядке
• Метаданные static — URL сервера авторизации не часто меняется
• Валидация токена всё ещё требует полные проверки scope и подписи; метаданные только для обнаружения