docs: align agent auth model and fix session test
This commit is contained in:
a.tolmachev
@@ -0,0 +1,281 @@
|
||||
# Модель машинной аутентификации и уровней защиты операций
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует целевую модель машинного доступа к опубликованным инструментам платформы. Модель строится вокруг двух принципов:
|
||||
|
||||
- длинноживущий машинный доступ принадлежит конкретному AI-агенту, а не рабочей области в целом;
|
||||
- требуемый уровень защиты определяется характером данных конкретной операции.
|
||||
|
||||
Именно поэтому в системе должны быть одновременно:
|
||||
|
||||
- ключ AI-агента как базовый машинный credential;
|
||||
- режимы выдачи токенов разной строгости;
|
||||
- обязательная политика защиты на уровне операции.
|
||||
|
||||
## 2. Базовая идея
|
||||
|
||||
Внутри платформы нужно различать:
|
||||
|
||||
1. чем клиент подтверждает право подключиться к агенту;
|
||||
2. какой уровень защиты требует операция;
|
||||
3. достаточно ли текущего машинного доступа для вызова этой операции.
|
||||
|
||||
Следовательно, решение нельзя строить только вокруг одного универсального токена. Оно должно учитывать и тип credential, и чувствительность самой ручки.
|
||||
|
||||
## 3. Уровни защиты операции
|
||||
|
||||
Каждая операция получает обязательный уровень защиты.
|
||||
|
||||
### 3.1. `standard`
|
||||
|
||||
Используется для обычных данных и типовых интеграционных вызовов.
|
||||
|
||||
Разрешенный доступ:
|
||||
|
||||
- статический ключ AI-агента;
|
||||
- короткоживущий токен;
|
||||
- одноразовый токен.
|
||||
|
||||
### 3.2. `elevated`
|
||||
|
||||
Используется для чувствительных внутренних данных, для которых постоянного ключа уже недостаточно.
|
||||
|
||||
Разрешенный доступ:
|
||||
|
||||
- короткоживущий токен;
|
||||
- одноразовый токен.
|
||||
|
||||
Статический ключ AI-агента для такого уровня уже недостаточен.
|
||||
|
||||
### 3.3. `strict`
|
||||
|
||||
Используется для максимально чувствительных данных, например содержащих коммерческую тайну, персональные данные высокой категории риска или иные критичные сведения.
|
||||
|
||||
Разрешенный доступ:
|
||||
|
||||
- только одноразовый токен на вызов.
|
||||
|
||||
Ни статический ключ, ни обычный короткоживущий токен для такого вызова не должны считаться достаточными.
|
||||
|
||||
## 4. Виды машинного доступа
|
||||
|
||||
### 4.1. Статический ключ AI-агента
|
||||
|
||||
Это длинноживущий ключ, принадлежащий одному агенту.
|
||||
|
||||
Свойства:
|
||||
|
||||
- привязан к одному `workspace`;
|
||||
- привязан к одному `agent`;
|
||||
- не используется для административных действий;
|
||||
- может быть отозван и перевыпущен;
|
||||
- в открытой редакции является основным механизмом подключения.
|
||||
|
||||
### 4.2. Короткоживущий токен
|
||||
|
||||
Это временный токен, выдаваемый на ограниченный срок.
|
||||
|
||||
Свойства:
|
||||
|
||||
- небольшой срок жизни;
|
||||
- ограниченная область действия;
|
||||
- может обновляться через стандартный поток OAuth 2.0;
|
||||
- подходит для платформенного размещения, где важен баланс удобства и безопасности.
|
||||
|
||||
### 4.3. Одноразовый токен
|
||||
|
||||
Это токен, который разрешает один вызов конкретной операции или одной логической единицы доступа.
|
||||
|
||||
Свойства:
|
||||
|
||||
- очень короткий срок жизни;
|
||||
- один допустимый вызов;
|
||||
- после первого использования считается исчерпанным;
|
||||
- предназначен для максимально чувствительных операций.
|
||||
|
||||
## 5. Правило сопоставления
|
||||
|
||||
Для вызова операции сервер сравнивает:
|
||||
|
||||
- уровень машинного доступа клиента;
|
||||
- обязательный уровень защиты операции.
|
||||
|
||||
Правило простое:
|
||||
|
||||
- если уровень доступа ниже, чем требует операция, вызов запрещается;
|
||||
- если уровень доступа равен или выше, вызов разрешается.
|
||||
|
||||
Именно это правило делает политику защиты независимой от того, в каком агенте опубликована операция.
|
||||
|
||||
## 6. Роль AI-агента
|
||||
|
||||
AI-агент:
|
||||
|
||||
- группирует операции;
|
||||
- формирует MCP-поверхность;
|
||||
- имеет собственный ключ подключения.
|
||||
|
||||
AI-агент не должен:
|
||||
|
||||
- ослаблять уровень защиты операции;
|
||||
- переопределять критичность данных;
|
||||
- разрешать более слабый способ вызова, чем требует сама операция.
|
||||
|
||||
Если в одном агенте опубликованы и обычные, и критичные операции, правила доступа к ним все равно различаются по уровню защиты самих операций.
|
||||
|
||||
## 7. Поддержка по редакциям продукта
|
||||
|
||||
### 7.1. Community
|
||||
|
||||
Открытая редакция должна поддерживать только один режим:
|
||||
|
||||
- статический ключ AI-агента.
|
||||
|
||||
Соответственно, в Community допустимы только операции уровня:
|
||||
|
||||
- `standard`.
|
||||
|
||||
### 7.2. Cloud или управляемая платформа
|
||||
|
||||
Для платформенного размещения должны поддерживаться:
|
||||
|
||||
- статический ключ AI-агента как режим совместимости;
|
||||
- короткоживущие токены по OAuth 2.0 как рекомендуемый режим.
|
||||
|
||||
Соответственно, платформа может обслуживать операции уровня:
|
||||
|
||||
- `standard`;
|
||||
- `elevated`.
|
||||
|
||||
### 7.3. Enterprise
|
||||
|
||||
Для корпоративной редакции должны поддерживаться все три режима:
|
||||
|
||||
- статический ключ AI-агента;
|
||||
- короткоживущий токен;
|
||||
- одноразовый токен.
|
||||
|
||||
Соответственно, допускаются операции уровня:
|
||||
|
||||
- `standard`;
|
||||
- `elevated`;
|
||||
- `strict`.
|
||||
|
||||
## 8. Потоки аутентификации
|
||||
|
||||
### 8.1. Community
|
||||
|
||||
1. Пользователь создает AI-агента.
|
||||
2. Платформа выдает статический ключ AI-агента.
|
||||
3. Клиент `Codex`, `Claude Code` или другой MCP-клиент использует этот ключ как bearer token при подключении к MCP endpoint.
|
||||
|
||||
Это самый простой и совместимый вариант.
|
||||
|
||||
### 8.2. Cloud или управляемая платформа
|
||||
|
||||
1. Пользователь или клиент проходит машинную аутентификацию.
|
||||
2. Сервер авторизации выдает короткоживущий токен доступа.
|
||||
3. Клиент использует его при работе с MCP endpoint.
|
||||
4. По истечении срока действия токен обновляется через стандартный механизм обновления.
|
||||
|
||||
Этот вариант должен опираться на OAuth 2.0 и обычный механизм refresh.
|
||||
|
||||
### 8.3. Enterprise
|
||||
|
||||
1. Клиент получает разрешение на вызов чувствительной операции.
|
||||
2. Сервер выдает одноразовый токен.
|
||||
3. Клиент выполняет один вызов.
|
||||
4. Токен становится недействительным.
|
||||
|
||||
Этот режим должен использоваться только там, где характер данных действительно требует такого уровня защиты.
|
||||
|
||||
## 9. Опорные стандарты
|
||||
|
||||
Для реализации расширенных режимов разумно опираться на готовые стандарты.
|
||||
|
||||
### OAuth 2.0
|
||||
|
||||
Используется как основа для короткоживущих токенов и их обновления.
|
||||
|
||||
### RFC 8693
|
||||
|
||||
Может использоваться как ориентир для схемы обмена одного вида machine credential на другой токен доступа.
|
||||
|
||||
### RFC 9449
|
||||
|
||||
Может использоваться как ориентир для будущей привязки токена к ключевой паре клиента, если потребуется дополнительная защита от повторного использования перехваченного токена.
|
||||
|
||||
## 10. Модель данных
|
||||
|
||||
Для этой схемы достаточно следующих базовых сущностей.
|
||||
|
||||
### `AgentKey`
|
||||
|
||||
Поля:
|
||||
|
||||
- `id`
|
||||
- `workspace_id`
|
||||
- `agent_id`
|
||||
- `name`
|
||||
- `prefix`
|
||||
- `secret_hash`
|
||||
- `status`
|
||||
- `created_at`
|
||||
- `last_used_at`
|
||||
- `expires_at`
|
||||
|
||||
### `IssuedAgentToken`
|
||||
|
||||
Поля:
|
||||
|
||||
- `id`
|
||||
- `workspace_id`
|
||||
- `agent_id`
|
||||
- `token_kind`
|
||||
- `status`
|
||||
- `expires_at`
|
||||
- `used_at`
|
||||
- `max_uses`
|
||||
- `used_count`
|
||||
- `created_at`
|
||||
|
||||
### Поля операции
|
||||
|
||||
На уровне операции должна появиться обязательная политика:
|
||||
|
||||
- `security_level`
|
||||
|
||||
Допустимые значения:
|
||||
|
||||
- `standard`
|
||||
- `elevated`
|
||||
- `strict`
|
||||
|
||||
## 11. Административный интерфейс
|
||||
|
||||
Настройка должна быть максимально простой.
|
||||
|
||||
На этапе создания или редактирования операции пользователь выбирает:
|
||||
|
||||
- `Обычный`
|
||||
- `Повышенная защита`
|
||||
- `Максимальная защита`
|
||||
|
||||
Смысл вариантов:
|
||||
|
||||
- `Обычный` — стандартный уровень для обычных данных;
|
||||
- `Повышенная защита` — короткоживущий токен;
|
||||
- `Максимальная защита` — одноразовый токен.
|
||||
|
||||
Пользователь не должен вручную настраивать детали OAuth или внутреннюю механику выдачи токенов на уровне операции.
|
||||
|
||||
## 12. Практический итог
|
||||
|
||||
Целевая модель машинного доступа для Crank должна строиться так:
|
||||
|
||||
- в Community — статический ключ AI-агента;
|
||||
- в управляемой платформе — короткоживущие токены;
|
||||
- в Enterprise — при необходимости одноразовые токены;
|
||||
- уровень защиты определяется операцией, а не агентом;
|
||||
- агент никогда не ослабляет обязательную защиту опубликованной операции.
|
||||
Reference in New Issue
Block a user