# OAuth для MCP

MCP-клиенты (Claude.ai, ChatGPT, Codex и собственные агенты) получают доступ к `https://aos.edgelab.space/mcp` по OAuth 2.1 без client secret: public client, authorization code с PKCE **S256**, refresh rotation. Issuer – `https://aos.edgelab.space`, единственный поддержанный resource – **`https://aos.edgelab.space/mcp`** (без завершающего `/`). Client secret, Basic auth, implicit и client credentials не поддерживаются.

Access token – непрозрачный bearer `aos3.sk_…`, не JWT. Права, срок и отзыв проверяются сервером; лимиты и scopes те же, что у [API-ключа](/docs/auth).

## Поток авторизации

```mermaid
sequenceDiagram
  actor Student as Студент
  participant Client as MCP-клиент
  participant AS as AgentOS OAuth
  Client->>AS: POST /oauth/register (DCR)
  AS-->>Client: client_id, без client_secret
  Client->>AS: GET /oauth/authorize + PKCE S256 + resource
  AS->>Student: Вход и форма согласия
  Student->>AS: Разрешить
  AS-->>Client: Callback: code + state + iss
  Client->>AS: POST /oauth/token (code, code_verifier)
  AS-->>Client: Access token (1 час), refresh (30 суток)
  Client->>AS: POST /oauth/token (refresh_token)
  AS-->>Client: Новая пара токенов
```

1. Клиент читает discovery и регистрируется через DCR.
2. Открывает в браузере `/oauth/authorize` с PKCE S256 и `resource`.
3. Студент входит (кабинет или код на email) и подтверждает доступ.
4. Клиент меняет `code` на токены и ходит в `https://aos.edgelab.space/mcp` с `Authorization: Bearer …`.

> [!WARNING]
> Refresh token одноразовый. Сериализуйте refresh и сохраняйте последнюю пару токенов атомарно: повтор уже использованного refresh token отзывает всё подключение.

## Discovery

| Документ | Назначение |
| --- | --- |
| `GET /.well-known/oauth-authorization-server` | Метаданные сервера авторизации: endpoints, `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported: ["none"]`, scopes |
| `GET /.well-known/oauth-protected-resource/mcp` | Метаданные ресурса MCP: `resource`, `authorization_servers`, scopes |

Оба документа публичные, без авторизации. Неавторизованный `POST /mcp` возвращает `401` и `WWW-Authenticate: Bearer resource_metadata="https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp"`; при недействительном токене добавляется `error="invalid_token"`.

```bash
curl -sS https://aos.edgelab.space/.well-known/oauth-authorization-server
curl -sS https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp
```

## Dynamic Client Registration

`POST /oauth/register`, тело `application/json` до 16 KiB, авторизация не нужна.

| Поле | Тип | Обязательно | Значение |
| --- | --- | --- | --- |
| `redirect_uris` | string[] | да | 1–10 URI из списка ниже |
| `client_name` | string | нет | 1–100 символов; по умолчанию `MCP client` |
| `token_endpoint_auth_method` | string | нет | Только `none` |
| `grant_types` | string[] | нет | `authorization_code` и, по желанию, `refresh_token`; по умолчанию оба |
| `response_types` | string[] | нет | `["code"]` |
| `scope` | string | нет | Scopes через пробел; согласие студента всё равно обязательно |
| `logo_uri` | string URL | нет | Только HTTPS |

Ответ `201`: поля регистрации, `client_id` и `client_id_issued_at`. `client_secret` не выдаётся. Клиент без `refresh_token` в `grant_types` получает только access token.

```bash
curl -sS https://aos.edgelab.space/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Example client","redirect_uris":["http://localhost:8765/callback"],"token_endpoint_auth_method":"none"}'
```

Разрешённые redirect URIs:

- `https://claude.ai/api/mcp/auth_callback` и `https://claude.com/api/mcp/auth_callback`;
- `https://chatgpt.com/connector_platform_oauth_redirect` и `https://chatgpt.com/connector/oauth/{callback_id}`;
- локальные `http://localhost[:port]/...`, `http://127.0.0.1[:port]/...`, `http://[::1][:port]/...` – для них может меняться только порт.

HTTPS-адрес должен совпасть с зарегистрированным посимвольно. При обмене code нужен **тот же `redirect_uri`, что был в authorize**, включая порт.

## Авторизация и согласие

`GET /oauth/authorize` открывается в браузере студента. Без сессии кабинета показывается вход по коду из email (6 цифр, действует 10 минут) со ссылкой на другие способы входа; затем – форма согласия с именем клиента и запрошенными правами.

| Параметр | Обязательно | Значение |
| --- | --- | --- |
| `client_id` | да | Из DCR |
| `redirect_uri` | да | Один из зарегистрированных |
| `response_type` | да | `code` |
| `code_challenge` | да | `BASE64URL(SHA256(code_verifier))`, 43 символа |
| `code_challenge_method` | да | `S256` |
| `resource` | да | `https://aos.edgelab.space/mcp` |
| `scope` | нет | Через пробел; по умолчанию `course:read profile:read` |
| `state` | нет | До 2048 символов, возвращается без изменений |

Нужен хотя бы один scope из `course:read`, `profile:read`, `progress:write`, `tutor:read`, `mentoring:read`; дополнительно можно `offline_access`. Пустой, неизвестный scope или один `offline_access` отклоняются. После решения студента браузер возвращается на callback: при согласии – `code` (действует **90 секунд**, одноразовый), при отказе – `error=access_denied`; в обоих случаях `state` и `iss`. Клиент обязан проверить `state` и `iss`.

```bash
curl -i -G https://aos.edgelab.space/oauth/authorize \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'redirect_uri=http://localhost:8765/callback' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'resource=https://aos.edgelab.space/mcp' \
  --data-urlencode 'code_challenge=PKCE_S256_CHALLENGE_43_CHARACTERS_PLACEHOLDER' \
  --data-urlencode 'code_challenge_method=S256' \
  --data-urlencode 'scope=course:read profile:read offline_access' \
  --data-urlencode 'state=CLIENT_RANDOM_STATE'
```

## Токены

`POST /oauth/token`, тело `application/x-www-form-urlencoded` до 16 KiB. Клиент идентифицируется `client_id`; заголовок `Authorization` и поле `client_secret` дают `401 invalid_client`.

| Поле | Когда | Значение |
| --- | --- | --- |
| `grant_type` | всегда | `authorization_code` или `refresh_token` |
| `client_id` | всегда | Из DCR |
| `code` | code | Код из callback |
| `redirect_uri` | code | Точная строка из authorize |
| `code_verifier` | code | 43–128 символов `[A-Za-z0-9._~-]` |
| `resource` | code | `https://aos.edgelab.space/mcp`; при refresh можно опустить |
| `refresh_token` | refresh | Последний выданный refresh token |
| `scope` | нет | Подмножество изначально выданных scope; шире нельзя |

```json
{
  "access_token": "aos3.sk_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_PLACEHOLDER",
  "scope": "course:read profile:read offline_access"
}
```

Refresh token выдаётся клиентам с `refresh_token` в `grant_types`. Каждый refresh выдаёт новую пару и заново проверяет участие студента в курсе. `scope` в refresh сужает только новый access token; refresh token сохраняет изначально выданные права, и следующий refresh без `scope` (или с более широким подмножеством) может вернуть их. Шире изначально выданных scope права не становятся никогда: такой запрос получает `400 invalid_grant`, а refresh token остаётся действующим. Повтор использованного code или refresh тем же клиентом отзывает подключение со всеми токенами.

```bash
curl -sS https://aos.edgelab.space/oauth/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'code=AUTHORIZATION_CODE_PLACEHOLDER' \
  --data-urlencode 'redirect_uri=http://localhost:8765/callback' \
  --data-urlencode 'code_verifier=CLIENT_PKCE_VERIFIER_PLACEHOLDER' \
  --data-urlencode 'resource=https://aos.edgelab.space/mcp'

curl -sS https://aos.edgelab.space/oauth/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'refresh_token=LATEST_REFRESH_TOKEN_PLACEHOLDER'
```

## Отзыв и подключения

- `POST /oauth/revoke` (form `application/x-www-form-urlencoded`: `client_id`, `token`) отзывает всё подключение, к которому относится токен клиента. Корректный запрос, прошедший проверки, получает `200` с пустым телом, даже если токен неизвестен или уже отозван. Неполная или повторяющая параметры форма даёт `400 invalid_request`, `client_secret` или заголовок `Authorization` – `401 invalid_client`. При `429 temporarily_unavailable` токен не отозван: повторите тот же запрос после `Retry-After`.
- Студент видит и отключает свои подключения на странице `/oauth/connections` (вход в кабинет обязателен).
- Если участие в курсе закончилось, все подключения и токены студента отзываются; после восстановления нужно подключиться заново.

## Сроки

| Объект | Срок |
| --- | --- |
| Вход по email в рамках авторизации | 30 минут |
| Authorization code | 90 секунд, один раз |
| Access token | 1 час (3600 секунд) |
| Refresh token | 30 суток с каждой выдачи, одноразовый |
| Подключение с refresh | до 30 дней после последнего использования |

## Ошибки

OAuth-ошибки приходят как JSON с полем `error` или как параметр `error` на callback.

| Код | Когда |
| --- | --- |
| `invalid_request` | Неверная или неполная форма, PKCE challenge, повтор параметров |
| `invalid_redirect_uri`, `invalid_client_metadata` | DCR: redirect URI не из списка или поля не прошли проверку |
| `invalid_scope`, `invalid_target`, `unsupported_response_type` | Authorize: неверные scope, `resource` или `response_type` |
| `access_denied` | Студент отказал |
| `invalid_client`, `unauthorized_client`, `unsupported_grant_type` | Token: неизвестный клиент, незарегистрированный grant, неверный `grant_type` |
| `invalid_grant` | Code или refresh истёк, использован, не совпали PKCE/redirect/scope, участие закончилось |
| `temporarily_unavailable` | `429` или `503`: повторите после `Retry-After` (если заголовка нет – с экспоненциальной паузой) |
| `server_error` | `500`, непредвиденная ошибка |

Регистрация, обмен и отзыв токенов ограничены по частоте; при `429` или `503` ждите время из `Retry-After`. Полный справочник – [Ошибки](/docs/errors#oauth).

## Scope `mentoring:read`

Discovery, DCR, согласие и выдача токенов поддерживают и `mentoring:read` – чтение [личного менторинга](/docs/api/mentoring). Он никогда не выдаётся по умолчанию, не добавляется к существующим ключам, подключениям и refresh-токенам, а refresh не расширяет grant. Нужен тариф «Лично».
