# oauth-protected-resource

## Что такое OAuth Protected Resource?

**OAuth Protected Resource Metadata** (RFC 9728) — JSON-документ по адресу `/.well-known/oauth-protected-resource`, который описывает защищённый API-ресурс и сообщает AI-агентам, у какого Authorization Server нужно получить токен доступа.

```json
{
  "resource": "https://api.example.com",
  "authorization_servers": [
    "https://auth.example.com"
  ],
  "scopes_supported": ["read", "write"],
  "bearer_methods_supported": ["header"]
}
```

## Зачем нужен OAuth Protected Resource?

Когда AI-агент обращается к API и получает `401 Unauthorized`, он должен самостоятельно найти Authorization Server. RFC 9728 стандартизирует этот discovery-шаг двумя способами:

1. Сервер возвращает заголовок `WWW-Authenticate: Bearer as_uri="https://auth.example.com"`.
2. Агент проверяет `/.well-known/oauth-protected-resource` напрямую.

Без этого документа агент не может автономно пройти авторизацию — ему требуется ручная настройка. Спецификация [MCP](/glossary/mcp-server-card) требует поддержки RFC 9728 для MCP-серверов с OAuth.

## Как реализовать OAuth Protected Resource?

Опубликуйте статический JSON-файл с Content-Type `application/json` по пути `/.well-known/oauth-protected-resource`. Обязательные поля:

| Поле | Тип | Описание |
|------|-----|----------|
| `resource` | string (URI) | URI самого защищённого ресурса |
| `authorization_servers` | array | Список URL Authorization Server'ов |
| `scopes_supported` | array | Поддерживаемые OAuth-скоупы |
| `bearer_methods_supported` | array | Методы передачи токена (`header`, `body`, `query`) |

Полный discovery-флоу для MCP-сервера с авторизацией:

```
GET /.well-known/oauth-protected-resource
→ { "authorization_servers": ["https://auth.example.com"], ... }

GET https://auth.example.com/.well-known/oauth-authorization-server
→ { "token_endpoint": "...", "authorization_endpoint": "..." }

POST .../token  →  access_token
GET /api/resource  (Authorization: Bearer <token>)
```

## Как мы проверяем OAuth Protected Resource?

Сканер выполняет GET-запрос на `/.well-known/oauth-protected-resource` и проверяет:

- HTTP-статус 200 и валидный JSON
- Наличие обязательных полей: `resource`, `authorization_servers`, `scopes_supported`
- Не пустой массив `authorization_servers`

Если хотя бы одно из условий нарушено — проверка `oauth_protected_resource` возвращает `fail`. Сама авторизация по полученному токену не выполняется.

[← Все термины глоссария](/glossary)