agentsready
API / Auth / MCP Сложно

OAuth Discovery для агентов: чтобы агент сам нашёл, где логиниться

Что такое OAuth Authorization Server Metadata (RFC 8414), зачем агентам авто-обнаружение OAuth-эндпоинтов, пример, ошибки и как проверить.

Обновлено:

Что это

OAuth Discovery (RFC 8414) — JSON-документ по адресу /.well-known/oauth-authorization-server, описывающий ваш OAuth-сервер: где authorization_endpoint, token_endpoint, какие grant-типы и scopes поддерживаются. Агенту не нужно хардкодить эти URL — он их находит автоматически.

Зачем это AI-агентам

Чтобы вызвать защищённый API, агент должен сперва получить токен. Без discovery интегратор зашивает OAuth-эндпоинты руками — хрупко и не масштабируется. С метаданными агент (или MCP-клиент) сам узнаёт, как пройти авторизацию. Это фундамент автономной авторизации — на нём строится, в частности, OAuth-флоу в MCP.

Минимальный рабочий пример

GET /.well-known/oauth-authorization-server HTTP/1.1
{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "scopes_supported": ["read", "write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

Правильно vs неправильно

ПравильноНеправильно
Документ по /.well-known/oauth-authorization-serverПроизвольный путь
issuer совпадает с базовым URLissuer не совпадает — клиенты отвергают
Абсолютные HTTPS-эндпоинтыHTTP или относительные пути
Перечислены реальные grant-типы и scopesЗаявлено то, что сервер не поддерживает

Типичные ошибки

  • issuer ≠ базовый URL — нарушает проверку RFC 8414, клиент откажет.
  • HTTP вместо HTTPS в эндпоинтах.
  • Неполные метаданные (нет token_endpoint) — флоу не собрать.
  • Заявленные scopes/grants не работают на практике.

Как проверить

Скан проверит наличие и валидность метаданных. Вручную:

curl -s https://example.com/.well-known/oauth-authorization-server | jq .

Ждём валидный JSON с issuer, authorization_endpoint, token_endpoint.

Источники