modelcontextprotocol/python-sdk
Watch
1
0
Fork
You've already forked python-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: refresh translations, and translate pages in parallel (#3458)

Browse source
This commit is contained in:
Max 2026-09-07 13:35:53 +01:00 • committed by GitHub
commit fd66270926
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 4821 additions and 2277 deletions
Download patch file Download diff file Expand all files Collapse all files

82
i18n/ru/pages/run/authorization.md
View file

@ -1,19 +1,19 @@
---
translation:
sections: [d62c13457fc4a534, 80e73abaca6e0652, d1dc4c54cd00ec9c, 14ad3bc7904036bb, 5225f127bc1b9c77, fe1626fdd5aad1da, 4556cb7ea1a04a31]
sections: [d62c13457fc4a534, 80e73abaca6e0652, 128a492d18295f64, 14ad3bc7904036bb, 54a6697833fcc1d9, fe1626fdd5aad1da, 811d083c1da8bcf6]
tool: 1
---
# Авторизация {#authorization}
Через Streamable HTTP MCP-сервер — это обычный веб-сервис, и защищается он так же, как любой веб-сервис: с помощью bearer-токенов OAuth 2.1.
При работе через Streamable HTTP ваш MCP-сервер — обычный веб-сервис, и защищают его так же, как любой веб-сервис: bearer-токенами OAuth 2.1.
В терминах OAuth ваш сервер — это **сервер ресурсов**. Он никого не аутентифицирует и не выдаёт токенов. Он делает ровно одно: смотрит на заголовок `Authorization` каждого запроса и решает, годится ли токен в нём.
В терминах OAuth ваш сервер — это **сервер ресурсов**. Он никогда не выполняет вход пользователей и никогда не выдаёт токены. Он делает одно: смотрит на заголовок `Authorization` в каждом запросе и решает, годится ли токен в нём.
Эта страница — о серверной стороне. Клиент, который обнаруживает ваш сервер авторизации и получает токен, описан на странице **[OAuth-клиенты](../client/oauth-clients.md)**.
Эта страница — о серверной стороне. Клиент, который находит ваш сервер авторизации и получает токен, описан на странице **[OAuth-клиенты](../client/oauth-clients.md)**.
## Три стороны {#the-three-parties}
* **Сервер авторизации** аутентифицирует пользователей и выдаёт токены доступа. Его вы не пишете. Это ваш провайдер идентификации (Auth0, Keycloak, Entra или ваш собственный).
* **Сервер авторизации** выполняет вход пользователей и выдаёт токены доступа. Его вы не пишете. Это ваш провайдер идентификации (Auth0, Keycloak, Entra или собственный).
* **Сервер ресурсов** — это ваш MCP-сервер. Он проверяет токен в каждом запросе.
* **Клиент** выясняет, какому серверу авторизации вы доверяете, получает у него токен и присылает его вам в виде `Authorization: Bearer <token>`.
@ -21,29 +21,33 @@ translation:
## Верификатор токенов {#a-token-verifier}
SDK ничего не предполагает о том, как выглядит действительный токен. Это определяете вы, реализуя **`TokenVerifier`**:
У SDK нет мнения о том, как выглядит действительный токен. Это сообщаете вы, реализуя **`TokenVerifier`**:
```python title="server.py" hl_lines="12-14 19-24"
```python title="server.py" hl_lines="14-16 21-27"
--8<-- "docs_src/authorization/tutorial001.py"
```
* `TokenVerifier` — это протокол с одним асинхронным методом. `verify_token` получает сырой токен из заголовка `Authorization` и возвращает **`AccessToken`**, если токен действителен, или `None`, если нет. Больше реализовывать нечего.
* Этот верификатор ищет токен в таблице. Настоящий проверяет подпись JWT или обращается к эндпоинту интроспекции токенов на сервере авторизации. Этот код — ваш; SDK его только вызывает.
* `TokenVerifier` — протокол с одним асинхронным методом. `verify_token` получает сырой токен из заголовка `Authorization` и возвращает **`AccessToken`**, если токен действителен, и `None`, если нет. Больше реализовывать нечего.
* Этот верификатор ищет токен в таблице; в каждой записи указан ресурс, для которого токен выдан. Настоящий проверяет подпись JWT или вызывает эндпоинт интроспекции токенов сервера авторизации и сообщает, для кого выдан токен (его `aud`), в `AccessToken.resource`. Этот код пишете вы; SDK его только вызывает.
* `token_verifier=` и `auth=` всегда идут в паре. Передайте один без другого — и `MCPServer(...)` выбросит `ValueError` ещё до того, как обслужит хоть один запрос.
`AuthSettings` — это публичное лицо вашего сервера ресурсов:
`AuthSettings` — публичное лицо вашего сервера ресурсов:
* `issuer_url`: сервер авторизации, который выдаёт ваши токены.
* `resource_server_url`: публичный URL этого MCP-эндпоинта. Он указывает, *для какого* ресурса предназначен токен, и по нему же размещается документ обнаружения.
* `resource_server_url`: публичный URL этого MCP-эндпоинта. Он указывает, для *какого* ресурса предназначен токен, и по нему же располагается документ обнаружения.
* `required_scopes`: каждый токен должен содержать их все.
* `validate_token_resource`: отклонять любой токен, у которого `AccessToken.resource` не равен `resource_server_url`. Если оставить его незаданным при заданном `resource_server_url`, выдаётся предупреждение (`MCPDeprecationWarning`), а поведение такое же, как при `False`; в версии 3.0 значением по умолчанию для серверов ресурсов станет `True`.
* Включите его, если ваш сервер авторизации привязывает токены к параметру `resource`, который запросил клиент, — MCP-клиенты передают его всегда. Следите, чтобы `resource_server_url` в точности совпадал с URL, к которому подключаются клиенты.
* Оставьте выключенным, если сервер авторизации использует собственные идентификаторы аудитории (идентификатор API в Auth0, идентификатор приложения в Entra), и вместо этого проверяйте `aud` в верификаторе, возвращая `None` для токена, предназначенного не этому серверу.
* Если `aud` — список, поместите в `resource` тот элемент, который равен `resource_server_url`.
!!! tip
В `examples/servers/simple-auth/` в репозитории SDK есть `IntrospectionTokenVerifier`, который обращается
к эндпоинту [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) настоящего сервера авторизации. Именно так устроено большинство верификаторов в продакшене.
В репозитории SDK, в `examples/servers/simple-auth/`, есть `IntrospectionTokenVerifier`, который обращается
к эндпоинту [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) настоящего сервера авторизации. Так устроено большинство верификаторов в реальных развёртываниях.
## Что вы получаете через HTTP {#what-you-get-over-http}
## Что появляется по HTTP {#what-you-get-over-http}
Авторизация живёт в HTTP-заголовках, поэтому существует только на HTTP-транспортах. Запускайте её на том транспорте, который развёртываете: `mcp.run(transport="streamable-http")` поднимает её на `http://127.0.0.1:8000/mcp`, а остальное — на странице **[Запуск сервера](index.md)**. Теперь у приложения два маршрута:
Авторизация живёт в HTTP-заголовках, поэтому существует только на HTTP-транспортах. Запускайте её на том, который развёртываете: `mcp.run(transport="streamable-http")` поднимает сервер на `http://127.0.0.1:8000/mcp`, а остальное — на странице **[Запуск сервера](index.md)**. Теперь у приложения два маршрута:
```text
/mcp
@ -65,11 +69,11 @@ SDK ничего не предполагает о том, как выгляди
}
```
Именно по этому документу клиент, который никогда не слышал о вашем сервере, находит к нему дорогу: читает `authorization_servers` и идёт туда за токеном. Ничего из этого вы не писали.
По этому документу клиент, никогда не слышавший о вашем сервере, находит дорогу внутрь: читает `authorization_servers` и идёт туда за токеном. Ни строчки из него вы не писали.
!!! check
Обратитесь к `/mcp` без токена (или с таким, для которого верификатор вернул `None`) — и запрос
остановят на входе:
Вызовите `/mcp` без токена (или с токеном, для которого верификатор вернул `None`) — и запрос
остановят на пороге:
```text
HTTP/1.1 401 Unauthorized
@ -78,26 +82,26 @@ SDK ничего не предполагает о том, как выгляди
{"error": "invalid_token", "error_description": "Authentication required"}
```
Ничего не разбиралось, ни один инструмент не запускался. А указатель `resource_metadata` в `WWW-Authenticate` —
это то, что делает обнаружение автоматическим: 401 -> документ метаданных -> сервер авторизации -> токен -> повтор.
Ничего не было разобрано, и ни один инструмент не выполнился. А указатель `resource_metadata` в `WWW-Authenticate` —
именно то, что делает обнаружение автоматическим: 401 -> документ метаданных -> сервер авторизации -> токен -> повтор запроса.
!!! warning
Ничто из этого не защищает `stdio`. У канала нет заголовка `Authorization`, поэтому к `token_verifier` там никогда
не обращаются. Граница безопасности `stdio`-сервера — это процесс, который его запустил. То же
относится к `Client(mcp)` в памяти, который используется в тестах: он подключается напрямую к объекту сервера
не обращаются. Граница безопасности `stdio`-сервера — процесс, который его запустил. То же
относится к `Client(mcp)` в памяти, который используется в тестах: он подключается прямо к объекту сервера
и минует HTTP-уровень вместе с авторизацией.
## Личность вызывающего {#the-callers-identity}
## Личность вызывающей стороны {#the-callers-identity}
Внутри любого обработчика **`get_access_token()`** — это `AccessToken`, который ваш верификатор вернул для текущего запроса:
```python title="server.py" hl_lines="4 32-35"
```python title="server.py" hl_lines="4 35-38"
--8<-- "docs_src/authorization/tutorial002.py"
```
* Это работает в инструментах, ресурсах и промптах, и ничего передавать не нужно: middleware авторизации сохраняет его в контекстной переменной для каждого запроса.
* Возвращается **тот самый объект, который собрал ваш верификатор**: `client_id`, `scopes`, `subject`, `expires_at` и любые дополнительные `claims`, которые вы прикрепили. Это и есть точка для правил на уровне отдельных инструментов: прочитайте scopes и откажите.
* Вне аутентифицированного HTTP-запроса функция возвращает `None`. В памяти и через `stdio` это всегда `None`.
* Работает в инструментах, ресурсах и промптах, и передавать ничего не нужно: middleware авторизации сохраняет его в контекстной переменной для каждого запроса.
* Возвращается **тот самый объект, который собрал ваш верификатор**: `client_id`, `scopes`, `subject`, `expires_at` и любые дополнительные `claims`, которые вы прикрепили. Это и есть точка для правил на уровне инструмента: прочитайте области действия и откажите.
* Вне аутентифицированного HTTP-запроса возвращается `None`. В памяти и по `stdio` это всегда `None`.
Вызовите `whoami` с `Authorization: Bearer alice-token` — и модель прочитает:
@ -105,26 +109,26 @@ SDK ничего не предполагает о том, как выгляди
alice (scopes: notes:read)
```
## Половина, которую SDK не делает {#the-half-the-sdk-doesnt-do}
## Половина, которой в SDK нет {#the-half-the-sdk-doesnt-do}
SDK даёт вам половину сервера ресурсов: проверить, объявить, отказать. Он не даёт страницу входа, экран согласия или токен.
SDK даёт вам половину сервера ресурсов: проверить, объявить, отказать. Он не даёт ни страницы входа, ни экрана согласия, ни токена.
Чтобы увидеть все три стороны в действии, запустите `examples/servers/simple-auth/` из репозитория SDK (небольшой сервер авторизации и сервер ресурсов, настроенный ровно так, как на этой странице), а затем направьте на него `examples/clients/simple-auth-client/` — и пройдите весь путь от обнаружения до токена.
Чтобы увидеть в движении все три стороны, запустите `examples/servers/simple-auth/` из репозитория SDK (небольшой сервер авторизации и сервер ресурсов, настроенный ровно как на этой странице), а затем направьте на него `examples/clients/simple-auth-client/` — получится полный цикл обнаружения и получения токена.
!!! info
Есть второй аргумент конструктора, `auth_server_provider=`, который встраивает полноценный сервер
авторизации внутрь MCP-сервера. Он появился раньше разделения AS/RS, вокруг которого построена спецификация
авторизации MCP. В новых серверах к нему прибегать не следует.
Есть и второй аргумент конструктора, `auth_server_provider=`, который встраивает полноценный сервер
авторизации внутрь MCP-сервера. Он появился раньше разделения на AS и RS, вокруг которого построена
спецификация авторизации MCP. В новых серверах обращаться к нему не следует.
Сервер авторизации также может принять подписанное утверждение от корпоративного провайдера идентификации вместо того, чтобы пользователь проходил через экран согласия, и SDK поддерживает обе стороны этого обмена. Сам грант и клиент, который его предъявляет, описаны на странице **[Утверждение личности](../client/identity-assertion.md)**.
Сервер авторизации может также принять подписанное утверждение корпоративного провайдера идентификации вместо того, чтобы пользователь проходил экран согласия, — и SDK поддерживает обе стороны этого обмена. Сам грант и клиент, который его предъявляет, описаны на странице **[Утверждение идентичности](../client/identity-assertion.md)**.
## Итоги {#recap}
* Через Streamable HTTP ваш сервер — это **сервер ресурсов** OAuth 2.1: он проверяет токены, но никогда их не выдаёт.
* `TokenVerifier` — вся поверхность интеграции: один асинхронный метод, токен на входе, `AccessToken | None` на выходе.
* По Streamable HTTP ваш сервер — **сервер ресурсов** OAuth 2.1: он проверяет токены и никогда их не выдаёт.
* `TokenVerifier` — вся поверхность интеграции: один асинхронный метод, на входе токен, на выходе `AccessToken | None`.
* `token_verifier=` и `auth=AuthSettings(issuer_url=..., resource_server_url=..., required_scopes=[...])` всегда идут в паре.
* SDK публикует Protected Resource Metadata по [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) по адресу `/.well-known/oauth-protected-resource/...` и отвечает на неаутентифицированные запросы кодом 401, заголовок `WWW-Authenticate` которого указывает на них. Это и есть вся история обнаружения.
* SDK публикует Protected Resource Metadata по [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) по адресу `/.well-known/oauth-protected-resource/...` и отвечает на неаутентифицированные запросы кодом 401, заголовок `WWW-Authenticate` которого указывает на этот документ. В этом и состоит всё обнаружение.
* `get_access_token()` в любом обработчике — это тот, кто вызывает.
* Авторизация — забота HTTP. `stdio` и клиент в памяти её никогда не видят.
* Авторизация — дело HTTP. `stdio` и тестовый клиент в памяти её никогда не видят.
Клиентская половина (обнаружение вашего сервера авторизации и получение токена за вас) — на странице **[OAuth-клиенты](../client/oauth-clients.md)**. А клиент, который *утверждает* личность вместо того, чтобы запрашивать её у пользователя, — на странице **[Утверждение личности](../client/identity-assertion.md)**.
Клиентская половина (найти ваш сервер авторизации и получить токен за вас) — на странице **[OAuth-клиенты](../client/oauth-clients.md)**. А клиент, который *утверждает* идентичность, вместо того чтобы спрашивать её у пользователя, — на странице **[Утверждение идентичности](../client/identity-assertion.md)**.