mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
562
docs/tech-specs/mcp-tool-bearer-token.ru.md
Normal file
562
docs/tech-specs/mcp-tool-bearer-token.ru.md
Normal file
|
|
@ -0,0 +1,562 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Спецификация аутентификации токенов Bearer для инструментов MCP"
|
||||
parent: "Russian (Beta)"
|
||||
---
|
||||
|
||||
# Спецификация аутентификации токенов Bearer для инструментов MCP
|
||||
|
||||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||||
|
||||
> **⚠️ ВАЖНО: ТОЛЬКО ДЛЯ ОДНОГО АРЕНДАТОРА**
|
||||
>
|
||||
> Эта спецификация описывает **базовый механизм аутентификации на уровне сервиса** для инструментов MCP. Это **НЕ** полное решение для аутентификации и **НЕ подходит** для:
|
||||
> - Многопользовательских сред
|
||||
> - Многоарендных развертываний
|
||||
> - Федеративной аутентификации
|
||||
> - Распространения контекста пользователя
|
||||
> - Авторизации на уровне пользователя
|
||||
>
|
||||
> Эта функция предоставляет **один статический токен для каждого инструмента MCP**, который используется всеми пользователями и сеансами. Если вам требуется аутентификация на уровне пользователя или арендатора, это не подходящее решение.
|
||||
|
||||
## Обзор
|
||||
**Название функции**: Поддержка аутентификации токенов Bearer для инструментов MCP
|
||||
**Автор**: Claude Code Assistant
|
||||
**Дата**: 2025-11-11
|
||||
**Статус**: В разработке
|
||||
|
||||
### Краткое описание
|
||||
|
||||
Позволяет конфигурациям инструментов MCP указывать необязательные токены Bearer для аутентификации с защищенными серверами MCP. Это позволяет TrustGraph безопасно вызывать инструменты MCP, размещенные на серверах, требующих аутентификации, без изменения интерфейсов агента или вызова инструментов.
|
||||
|
||||
**ВАЖНО**: Это базовый механизм аутентификации, предназначенный для сценариев аутентификации от сервиса к сервису в одноарендной среде. Он **НЕ подходит** для:
|
||||
Многопользовательских сред, где разные пользователи нуждаются в разных учетных данных
|
||||
Многоарендных развертываний, требующих изоляции на уровне арендатора
|
||||
Сценариев федеративной аутентификации
|
||||
Аутентификации или авторизации на уровне пользователя
|
||||
Динамического управления учетными данными или обновления токенов
|
||||
|
||||
Эта функция предоставляет статический, системный токен Bearer для каждой конфигурации инструмента MCP, который используется всеми пользователями и вызовами этого инструмента.
|
||||
|
||||
### Описание проблемы
|
||||
|
||||
В настоящее время инструменты MCP могут подключаться только к общедоступным серверам MCP. Многие производственные развертывания MCP требуют аутентификации с помощью токенов Bearer для обеспечения безопасности. Без поддержки аутентификации:
|
||||
Инструменты MCP не могут подключаться к защищенным серверам MCP
|
||||
Пользователям приходится либо предоставлять доступ к серверам MCP в общедоступном режиме, либо использовать обратные прокси
|
||||
Нет стандартизированного способа передачи учетных данных для подключений MCP
|
||||
Невозможно применять лучшие практики безопасности к конечным точкам MCP
|
||||
|
||||
### Цели
|
||||
|
||||
[ ] Разрешить конфигурациям инструментов MCP указывать необязательный параметр `auth-token`
|
||||
[ ] Обновить сервис инструмента MCP для использования токенов Bearer при подключении к серверам MCP
|
||||
[ ] Обновить инструменты командной строки для поддержки установки/отображения токенов аутентификации
|
||||
[ ] Сохранить обратную совместимость с конфигурациями MCP без аутентификации
|
||||
[ ] Задокументировать соображения безопасности для хранения токенов
|
||||
|
||||
### Не включено
|
||||
Динамическое обновление токенов или потоки OAuth (только статические токены)
|
||||
Шифрование хранимых токенов (безопасность системы конфигураций не входит в область)
|
||||
Альтернативные методы аутентификации (базовая аутентификация, ключи API и т. д.)
|
||||
Проверка срока действия или истечения срока действия токенов
|
||||
**Аутентификация на уровне пользователя**: Эта функция **НЕ поддерживает** учетные данные, специфичные для пользователя
|
||||
**Изоляция на уровне арендатора**: Эта функция **НЕ предоставляет** управление токенами на уровне арендатора
|
||||
**Федеративная аутентификация**: Эта функция **НЕ интегрируется** с поставщиками идентификации (SSO, OAuth, SAML и т. д.)
|
||||
**Аутентификация, зависящая от контекста**: Токены не передаются на основе контекста пользователя или сеанса
|
||||
|
||||
## Предыстория и контекст
|
||||
|
||||
### Текущее состояние
|
||||
Конфигурации инструментов MCP хранятся в группе конфигураций `mcp` со следующей структурой:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
Сервис инструмента MCP подключается к серверам, используя `streamablehttp_client(url)`, без каких-либо заголовков аутентификации.
|
||||
|
||||
### Ограничения
|
||||
|
||||
**Текущие ограничения системы:**
|
||||
1. **Отсутствие поддержки аутентификации:** Невозможно подключиться к защищенным серверам MCP.
|
||||
2. **Риски безопасности:** Серверы MCP должны быть общедоступными или использовать только сетевую безопасность.
|
||||
3. **Проблемы при развертывании в производственной среде:** Невозможно соблюдать лучшие практики безопасности для API-интерфейсов.
|
||||
|
||||
**Ограничения данного решения:**
|
||||
1. **Только для однопользовательской системы:** Один статический токен для каждого инструмента MCP, общий для всех пользователей.
|
||||
2. **Отсутствие учетных данных для каждого пользователя:** Невозможно аутентифицироваться как разные пользователи или передавать контекст пользователя.
|
||||
3. **Отсутствие поддержки многопользовательской системы:** Невозможно изолировать учетные данные по арендатору или организации.
|
||||
4. **Только статические токены:** Нет поддержки обновления, ротации или обработки истечения срока действия токенов.
|
||||
5. **Аутентификация на уровне сервиса:** Аутентифицируется сервис TrustGraph, а не отдельные пользователи.
|
||||
6. **Общий контекст безопасности:** Все вызовы инструмента MCP используют одни и те же учетные данные.
|
||||
|
||||
### Область применения
|
||||
|
||||
**✅ Подходящие сценарии использования:**
|
||||
Развертывания TrustGraph для одного арендатора.
|
||||
Аутентификация от сервиса к сервису (TrustGraph → MCP Server).
|
||||
Среды разработки и тестирования.
|
||||
Внутренние инструменты MCP, доступные системе TrustGraph.
|
||||
Сценарии, в которых все пользователи имеют одинаковый уровень доступа к инструменту MCP.
|
||||
Статические, долгоживущие учетные данные сервиса.
|
||||
|
||||
**❌ Неподходящие сценарии использования:**
|
||||
Системы с несколькими пользователями, требующие аутентификацию для каждого пользователя.
|
||||
Многопользовательские SaaS-платформы с требованиями к изоляции арендаторов.
|
||||
Сценарии федеративной аутентификации (SSO, OAuth, SAML).
|
||||
Системы, требующие передачу контекста пользователя на серверы MCP.
|
||||
Среды, требующие динамическое обновление токенов или короткоживущие токены.
|
||||
Приложения, в которых разные пользователи должны иметь разные уровни разрешений.
|
||||
Требования соответствия для аудиторских журналов на уровне пользователя.
|
||||
|
||||
**Пример подходящего сценария:**
|
||||
Развертывание TrustGraph для одной организации, в котором все сотрудники используют один и тот же внутренний инструмент MCP (например, поиск информации в корпоративной базе данных). Сервер MCP требует аутентификации для предотвращения внешнего доступа, но все внутренние пользователи имеют одинаковый уровень доступа.
|
||||
|
||||
**Пример неподходящего сценария:**
|
||||
Многопользовательская SaaS-платформа TrustGraph, в которой арендатор A и арендатор B должны получать доступ к своим собственным изолированным серверам MCP с отдельными учетными данными. Эта функция НЕ поддерживает управление токенами на уровне арендатора.
|
||||
|
||||
### Связанные компоненты
|
||||
**trustgraph-flow/trustgraph/agent/mcp_tool/service.py**: Сервис вызова инструмента MCP.
|
||||
**trustgraph-cli/trustgraph/cli/set_mcp_tool.py**: Инструмент командной строки для создания/обновления конфигураций MCP.
|
||||
**trustgraph-cli/trustgraph/cli/show_mcp_tools.py**: Инструмент командной строки для отображения конфигураций MCP.
|
||||
**MCP Python SDK**: `streamablehttp_client` из `mcp.client.streamable_http`.
|
||||
|
||||
## Требования
|
||||
|
||||
### Функциональные требования
|
||||
|
||||
1. **Токен аутентификации для конфигурации MCP:** Конфигурации инструмента MCP ДОЛЖНЫ поддерживать необязательное поле `auth-token`.
|
||||
2. **Использование токена Bearer:** Сервис инструмента MCP ДОЛЖЕН отправлять заголовок `Authorization: Bearer {token}` при настройке аутентификации.
|
||||
3. **Поддержка CLI:** `tg-set-mcp-tool` ДОЛЖЕН принимать необязательный параметр `--auth-token`.
|
||||
4. **Отображение токена:** `tg-show-mcp-tools` ДОЛЖЕН указывать, когда настроена аутентификация (маскируется для безопасности).
|
||||
5. **Обратная совместимость:** Существующие конфигурации инструмента MCP без аутентификации ДОЛЖНЫ продолжать работать.
|
||||
|
||||
### Нефункциональные требования
|
||||
1. **Обратная совместимость:** Отсутствие изменений, нарушающих работу существующих конфигураций инструмента MCP.
|
||||
2. **Производительность:** Отсутствие значительного влияния на производительность вызова инструмента MCP.
|
||||
3. **Безопасность:** Токены хранятся в конфигурации (учитывайте последствия для безопасности).
|
||||
|
||||
### Пользовательские истории
|
||||
|
||||
1. Как **инженеру DevOps**, я хочу настроить токены Bearer для инструментов MCP, чтобы я мог защитить конечные точки серверов MCP.
|
||||
2. Как **пользователю CLI**, я хочу устанавливать токены аутентификации при создании инструментов MCP, чтобы я мог подключаться к защищенным серверам.
|
||||
3. Как **системному администратору**, я хочу видеть, какие инструменты MCP имеют настроенную аутентификацию, чтобы я мог проверять настройки безопасности.
|
||||
|
||||
## Проектирование
|
||||
|
||||
### Архитектура высокого уровня
|
||||
Расширение конфигурации и сервиса инструмента MCP для поддержки аутентификации с помощью токена Bearer:
|
||||
1. Добавление необязательного поля `auth-token` в схему конфигурации инструмента MCP.
|
||||
2. Изменение сервиса инструмента MCP для чтения токена аутентификации и передачи его в HTTP-клиент.
|
||||
3. Обновление инструментов командной строки для поддержки установки и отображения токенов аутентификации.
|
||||
4. Документирование соображений безопасности и лучших практик.
|
||||
|
||||
### Схема конфигурации
|
||||
|
||||
**Текущая схема:**
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
**Новая схема** (с необязательным токеном авторизации):
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api",
|
||||
"auth-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
**Описание полей**:
|
||||
`remote-name` (необязательно): Имя, используемое сервером MCP (по умолчанию - ключ конфигурации).
|
||||
`url` (обязательно): URL-адрес конечной точки сервера MCP.
|
||||
`auth-token` (необязательно): Токен для аутентификации.
|
||||
|
||||
### Поток данных
|
||||
|
||||
1. **Хранение конфигурации**: Пользователь запускает `tg-set-mcp-tool --id my-tool --tool-url http://server/api --auth-token xyz123`.
|
||||
2. **Загрузка конфигурации**: Сервис инструмента MCP получает обновление конфигурации через обратный вызов `on_mcp_config()`.
|
||||
3. **Вызов инструмента**: Когда инструмент вызывается:
|
||||
Сервис считывает `auth-token` из конфигурации (если он присутствует).
|
||||
Создает словарь заголовков: `{"Authorization": "Bearer {token}"}`.
|
||||
Передает заголовки в `streamablehttp_client(url, headers=headers)`.
|
||||
Сервер MCP проверяет токен и обрабатывает запрос.
|
||||
|
||||
### Изменения API
|
||||
Отсутствуют внешние изменения API - только расширение схемы конфигурации.
|
||||
|
||||
### Детали компонента
|
||||
|
||||
#### Компонент 1: service.py (Сервис инструмента MCP)
|
||||
**Файл**: `trustgraph-flow/trustgraph/agent/mcp_tool/service.py`.
|
||||
|
||||
**Назначение**: Вызов инструментов MCP на удаленных серверах.
|
||||
|
||||
**Необходимые изменения** (в методе `invoke_tool()`):
|
||||
1. Проверить наличие `auth-token` в конфигурации `self.mcp_services[name]`.
|
||||
2. Создать словарь заголовков с заголовком Authorization, если токен существует.
|
||||
3. Передать заголовки в `streamablehttp_client(url, headers=headers)`.
|
||||
|
||||
**Текущий код** (строки 42-89):
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server
|
||||
async with streamablehttp_client(url) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method
|
||||
```
|
||||
|
||||
**Измененный код**:
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
# Build headers with optional bearer token
|
||||
headers = {}
|
||||
if "auth-token" in self.mcp_services[name]:
|
||||
token = self.mcp_services[name]["auth-token"]
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server with headers
|
||||
async with streamablehttp_client(url, headers=headers) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method (unchanged)
|
||||
```
|
||||
|
||||
#### Компонент 2: set_mcp_tool.py (Инструмент конфигурации командной строки)
|
||||
**Файл**: `trustgraph-cli/trustgraph/cli/set_mcp_tool.py`
|
||||
|
||||
**Назначение**: Создание/обновление конфигураций инструмента MCP.
|
||||
|
||||
**Необходимые изменения**:
|
||||
1. Добавить необязательный аргумент `--auth-token` в argparse.
|
||||
2. Включить `auth-token` в конфигурационный JSON, если он предоставлен.
|
||||
|
||||
**Текущие аргументы**:
|
||||
`--id` (обязательный): Идентификатор инструмента MCP.
|
||||
`--remote-name` (необязательный): Удаленное имя инструмента MCP.
|
||||
`--tool-url` (обязательный): URL-адрес конечной точки инструмента MCP.
|
||||
`-u, --api-url` (необязательный): URL-адрес API TrustGraph.
|
||||
|
||||
**Новый аргумент**:
|
||||
`--auth-token` (необязательный): Токен Bearer для аутентификации.
|
||||
|
||||
**Измененное построение конфигурации**:
|
||||
```python
|
||||
# Build configuration object
|
||||
config = {
|
||||
"url": args.tool_url,
|
||||
}
|
||||
|
||||
if args.remote_name:
|
||||
config["remote-name"] = args.remote_name
|
||||
|
||||
if args.auth_token:
|
||||
config["auth-token"] = args.auth_token
|
||||
|
||||
# Store configuration
|
||||
api.config().put([
|
||||
ConfigValue(type="mcp", key=args.id, value=json.dumps(config))
|
||||
])
|
||||
```
|
||||
|
||||
#### Компонент 3: show_mcp_tools.py (Инструмент отображения командной строки)
|
||||
**Файл**: `trustgraph-cli/trustgraph/cli/show_mcp_tools.py`
|
||||
|
||||
**Назначение**: Отображение конфигураций инструмента MCP.
|
||||
|
||||
**Необходимые изменения**:
|
||||
1. Добавить столбец "Auth" в таблицу вывода.
|
||||
2. Отображать "Да" или "Нет" в зависимости от наличия auth-токена.
|
||||
3. Не отображать фактическое значение токена (безопасность).
|
||||
|
||||
**Текущий вывод**:
|
||||
```
|
||||
ID Remote Name URL
|
||||
---------- ------------- ------------------------
|
||||
my-tool my-tool http://server:3000/api
|
||||
```
|
||||
|
||||
**Новый вывод**:
|
||||
```
|
||||
ID Remote Name URL Auth
|
||||
---------- ------------- ------------------------ ------
|
||||
my-tool my-tool http://server:3000/api Yes
|
||||
other-tool other-tool http://other:3000/api No
|
||||
```
|
||||
|
||||
#### Компонент 4: Документация
|
||||
**Файл**: `docs/cli/tg-set-mcp-tool.md`
|
||||
|
||||
**Необходимые изменения**:
|
||||
1. Документировать новый параметр `--auth-token`
|
||||
2. Предоставить пример использования с аутентификацией
|
||||
3. Документировать соображения безопасности
|
||||
|
||||
## План реализации
|
||||
|
||||
### Фаза 1: Создание технической спецификации
|
||||
[x] Написать подробную техническую спецификацию, документирующую все изменения
|
||||
|
||||
### Фаза 2: Обновление сервиса MCP Tool
|
||||
[ ] Изменить `invoke_tool()` в `service.py` для чтения auth-token из конфигурации
|
||||
[ ] Создать словарь заголовков и передать его в `streamablehttp_client`
|
||||
[ ] Протестировать с аутентифицированным сервером MCP
|
||||
|
||||
### Фаза 3: Обновление инструментов командной строки
|
||||
[ ] Добавить аргумент `--auth-token` в `set_mcp_tool.py`
|
||||
[ ] Включить auth-token в конфигурационный JSON
|
||||
[ ] Добавить столбец "Auth" в вывод `show_mcp_tools.py`
|
||||
[ ] Протестировать изменения в инструментах командной строки
|
||||
|
||||
### Фаза 4: Обновление документации
|
||||
[ ] Документировать параметр `--auth-token` в `tg-set-mcp-tool.md`
|
||||
[ ] Добавить раздел "Соображения безопасности"
|
||||
[ ] Предоставить пример использования
|
||||
|
||||
### Фаза 5: Тестирование
|
||||
[ ] Проверить, что сервис MCP tool успешно подключается с использованием auth-token
|
||||
[ ] Проверить обратную совместимость (инструменты без auth-token по-прежнему работают)
|
||||
[ ] Проверить, что инструменты командной строки правильно принимают и сохраняют auth-token
|
||||
[ ] Проверить, что команда "show" правильно отображает статус аутентификации
|
||||
|
||||
### Краткое описание изменений в коде
|
||||
| Файл | Тип изменения | Строки | Описание |
|
||||
|------|------------|-------|-------------|
|
||||
| `service.py` | Изменено | ~52-66 | Добавлено чтение auth-token и построение заголовков |
|
||||
| `set_mcp_tool.py` | Изменено | ~30-60 | Добавлен аргумент --auth-token и хранение в конфигурации |
|
||||
| `show_mcp_tools.py` | Изменено | ~40-70 | Добавлен столбец Auth в отображение |
|
||||
| `tg-set-mcp-tool.md` | Изменено | Различные | Документирован новый параметр |
|
||||
|
||||
## Стратегия тестирования
|
||||
|
||||
### Юнит-тесты
|
||||
**Чтение токена аутентификации**: Проверить, что `invoke_tool()` правильно считывает auth-token из конфигурации
|
||||
**Построение заголовков**: Проверить, что заголовок Authorization строится правильно с префиксом Bearer
|
||||
**Обратная совместимость**: Проверить, что инструменты без auth-token работают без изменений
|
||||
**Разбор аргументов командной строки**: Проверить, что аргумент `--auth-token` разбирается правильно
|
||||
|
||||
### Интеграционные тесты
|
||||
**Аутентифицированное подключение**: Проверить, что сервис MCP tool подключается к аутентифицированному серверу
|
||||
**Комплексное тестирование**: Проверить взаимодействие командной строки → хранилище конфигурации → вызов сервиса с auth token
|
||||
**Подключение без токена**: Проверить, что подключение к неаутентифицированному серверу по-прежнему работает
|
||||
|
||||
### Ручное тестирование
|
||||
**Реальный сервер MCP**: Проверить с фактическим сервером MCP, требующим аутентификацию с использованием токена bearer
|
||||
**Рабочий процесс командной строки**: Проверить полный рабочий процесс: настройка инструмента с auth → вызов инструмента → проверка успешного выполнения
|
||||
**Маскировка отображения**: Убедиться, что статус аутентификации отображается, но значение токена не отображается
|
||||
|
||||
## Миграция и развертывание
|
||||
|
||||
### Стратегия миграции
|
||||
Миграция не требуется - это чисто дополнительная функциональность:
|
||||
Существующие конфигурации MCP tool без `auth-token` продолжают работать без изменений
|
||||
Новые конфигурации могут опционально включать поле `auth-token`
|
||||
Инструменты командной строки принимают, но не требуют параметр `--auth-token`
|
||||
|
||||
### План развертывания
|
||||
1. **Фаза 1**: Развернуть основные изменения сервиса в среде разработки/тестирования
|
||||
2. **Фаза 2**: Развернуть обновления инструментов командной строки
|
||||
3. **Фаза 3**: Обновить документацию
|
||||
4. **Фаза 4**: Развертывание в производственной среде с мониторингом
|
||||
|
||||
### План отката
|
||||
Основные изменения обратно совместимы - существующие инструменты не затронуты
|
||||
В случае возникновения проблем обработку auth-token можно отключить, удалив логику построения заголовков
|
||||
Изменения в инструментах командной строки являются независимыми и могут быть отменены отдельно
|
||||
|
||||
## Соображения безопасности
|
||||
|
||||
### ⚠️ Критическое ограничение: Поддержка только однопользовательской аутентификации
|
||||
|
||||
**Этот механизм аутентификации НЕ подходит для многопользовательских или многопользовательских сред.**
|
||||
|
||||
**Общие учетные данные**: Все пользователи и вызовы используют один и тот же токен для каждого инструмента MCP
|
||||
**Отсутствие контекста пользователя**: Сервер MCP не может различать разных пользователей TrustGraph
|
||||
**Отсутствие изоляции арендаторов**: Все арендаторы используют одни и те же учетные данные для каждого инструмента MCP
|
||||
**Ограничение журнала аудита**: Сервер MCP отображает все запросы от одних и тех же учетных данных
|
||||
**Область разрешений**: Невозможно применять разные уровни разрешений для разных пользователей
|
||||
|
||||
**Не используйте эту функцию, если:**
|
||||
Ваша развертка TrustGraph обслуживает несколько организаций (многопользовательская среда)
|
||||
Вам необходимо отслеживать, какой пользователь получил доступ к какому инструменту MCP
|
||||
Разным пользователям требуются разные уровни разрешений
|
||||
Вам необходимо соблюдать требования аудита на уровне пользователей
|
||||
Ваш сервер MCP применяет ограничения скорости или квоты на уровне пользователя
|
||||
|
||||
**Альтернативные решения для сценариев с несколькими пользователями/многопользовательской средой:**
|
||||
Реализовать распространение контекста пользователя через пользовательские заголовки
|
||||
Развернуть отдельные экземпляры TrustGraph для каждого арендатора
|
||||
Использовать сетевую изоляцию (VPCs, service meshes)
|
||||
Реализовать прокси-слой, который обрабатывает аутентификацию для каждого пользователя
|
||||
|
||||
### Хранение токенов
|
||||
**Риск**: Токены аутентификации хранятся в открытом виде в системе конфигурации
|
||||
|
||||
**Меры по снижению риска**:
|
||||
Задокументировать, что токены хранятся без шифрования
|
||||
Рекомендовать использовать токены с коротким сроком действия, когда это возможно
|
||||
Рекомендовать надлежащий контроль доступа к хранилищу конфигурации
|
||||
Рассмотреть возможность будущей реализации для зашифрованного хранения токенов
|
||||
|
||||
### Раскрытие токенов
|
||||
**Риск**: Токены могут быть раскрыты в журналах или в выходных данных командной строки
|
||||
|
||||
**Меры по снижению риска**:
|
||||
Не записывать значения токенов в журналы (записывать только "аутентификация настроена: да/нет")
|
||||
Команда `show` в командной строке отображает только маскированный статус, а не фактический токен
|
||||
Не включать токены в сообщения об ошибках
|
||||
|
||||
### Сетевая безопасность
|
||||
**Риск**: Токены передаются по незашифрованным соединениям
|
||||
|
||||
**Меры по снижению риска**:
|
||||
Рекомендовать использовать HTTPS-URL-адреса для серверов MCP
|
||||
Предупреждать пользователей о риске передачи данных в открытом виде по протоколу HTTP
|
||||
|
||||
### Доступ к конфигурации
|
||||
**Риск**: Несанкционированный доступ к системе конфигурации раскрывает токены
|
||||
|
||||
**Меры по снижению риска**:
|
||||
Подчеркнуть важность защиты доступа к системе конфигурации
|
||||
Рекомендовать принцип наименьших привилегий для доступа к конфигурации
|
||||
Рассмотреть возможность ведения журналов аудита для изменений конфигурации (будущая реализация)
|
||||
|
||||
### Многопользовательские среды
|
||||
**Риск**: В многопользовательских развертываниях все пользователи используют одни и те же учетные данные MCP
|
||||
|
||||
**Понимание риска**:
|
||||
Пользователь A и пользователь B используют один и тот же токен при доступе к инструменту MCP
|
||||
Сервер MCP не может различать разных пользователей TrustGraph
|
||||
Нет возможности применить права доступа или ограничения скорости для каждого пользователя
|
||||
Журналы аудита на сервере MCP показывают все запросы от одних и тех же учетных данных
|
||||
Если сессия одного пользователя скомпрометирована, злоумышленник получает тот же доступ к MCP, что и все пользователи
|
||||
|
||||
**Это НЕ ошибка - это фундаментальное ограничение этой архитектуры.**
|
||||
|
||||
## Влияние на производительность
|
||||
**Минимальные накладные расходы**: Создание заголовка добавляет незначительное время обработки
|
||||
**Влияние на сеть**: Дополнительный HTTP-заголовок добавляет ~50-200 байт на запрос
|
||||
**Использование памяти**: Незначительное увеличение объема памяти для хранения строки токена в конфигурации
|
||||
|
||||
## Документация
|
||||
|
||||
### Пользовательская документация
|
||||
[ ] Обновить `tg-set-mcp-tool.md` с параметром `--auth-token`
|
||||
[ ] Добавить раздел о соображениях безопасности
|
||||
[ ] Предоставить пример использования с токеном типа bearer
|
||||
[ ] Задокументировать последствия хранения токенов
|
||||
|
||||
### Документация для разработчиков
|
||||
[ ] Добавить встроенные комментарии для обработки токенов аутентификации в `service.py`
|
||||
[ ] Задокументировать логику создания заголовков
|
||||
[ ] Обновить документацию схемы конфигурации инструмента MCP
|
||||
|
||||
## Открытые вопросы
|
||||
1. **Шифрование токенов**: Следует ли нам реализовать зашифрованное хранение токенов в системе конфигурации?
|
||||
2. **Обновление токенов**: Будущая поддержка потоков OAuth для обновления токенов или ротации токенов?
|
||||
3. **Альтернативные методы аутентификации**: Следует ли нам поддерживать Basic auth, API-ключи или другие методы?
|
||||
|
||||
## Рассмотренные альтернативы
|
||||
|
||||
1. **Переменные среды для токенов**: Хранить токены в переменных среды вместо конфигурации
|
||||
**Отклонено**: Усложняет развертывание и управление конфигурацией
|
||||
|
||||
2. **Отдельное хранилище секретов**: Использовать специализированную систему управления секретами
|
||||
**Отложено**: Выходит за рамки первоначальной реализации, рассмотреть возможность будущей реализации
|
||||
|
||||
3. **Несколько методов аутентификации**: Поддержка Basic, API-ключей, OAuth и т.д.
|
||||
**Отклонено**: Токены типа bearer охватывают большинство сценариев использования, сохраняем простоту первоначальной реализации
|
||||
|
||||
4. **Зашифрованное хранение токенов**: Шифровать токены в системе конфигурации
|
||||
**Отложено**: Безопасность системы конфигурации является более широкой проблемой, отложить до будущей работы
|
||||
|
||||
5. **Токены для каждого вызова**: Разрешить передачу токенов во время вызова
|
||||
**Отклонено**: Нарушает разделение ответственности, агент не должен обрабатывать учетные данные
|
||||
|
||||
## Ссылки
|
||||
[Спецификация протокола MCP](https://github.com/modelcontextprotocol/spec)
|
||||
[HTTP Bearer Authentication (RFC 6750)](https://tools.ietf.org/html/rfc6750)
|
||||
[Текущий сервис инструмента MCP](../trustgraph-flow/trustgraph/agent/mcp_tool/service.py)
|
||||
[Спецификация аргументов инструмента MCP](./mcp-tool-arguments.md)
|
||||
|
||||
## Приложение
|
||||
|
||||
### Пример использования
|
||||
|
||||
**Настройка инструмента MCP с аутентификацией**:
|
||||
```bash
|
||||
tg-set-mcp-tool \
|
||||
--id secure-tool \
|
||||
--tool-url https://secure-server.example.com/mcp \
|
||||
--auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**Отображение инструментов MCP:**
|
||||
```bash
|
||||
tg-show-mcp-tools
|
||||
|
||||
ID Remote Name URL Auth
|
||||
----------- ----------- ------------------------------------ ------
|
||||
secure-tool secure-tool https://secure-server.example.com/mcp Yes
|
||||
public-tool public-tool http://localhost:3000/mcp No
|
||||
```
|
||||
|
||||
### Пример конфигурации
|
||||
|
||||
**Хранится в системе конфигурации**:
|
||||
```json
|
||||
{
|
||||
"type": "mcp",
|
||||
"key": "secure-tool",
|
||||
"value": "{\"url\": \"https://secure-server.example.com/mcp\", \"auth-token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### Лучшие практики безопасности
|
||||
|
||||
1. **Использование HTTPS**: Всегда используйте HTTPS-адреса для серверов MCP с аутентификацией.
|
||||
2. **Кратковременные токены**: Используйте токены с истечением срока действия, когда это возможно.
|
||||
3. **Принцип наименьших привилегий**: Предоставляйте токенам минимально необходимые разрешения.
|
||||
4. **Контроль доступа**: Ограничьте доступ к системе конфигурации.
|
||||
5. **Ротация токенов**: Регулярно обновляйте токены.
|
||||
6. **Журналирование аудита**: Отслеживайте изменения конфигурации для выявления событий безопасности.
|
||||
Loading…
Add table
Add a link
Reference in a new issue