# Пользователи, роли и разрешения {#users-roles-permissions}
SnapOtter поставляется с тремя встроенными ролями, 17 гранулярными разрешениями и поддержкой пользовательских ролей с опциональным контролем доступа на уровне отдельных инструментов. Эта страница охватывает полную модель авторизации, ограничение области действия ключей API, управление командами и журналирование аудита.
Администраторы могут создавать пользователей через панель администратора или конечную точку `POST /api/auth/register`. У каждого пользователя есть имя пользователя, роль, назначение в команду и опциональный адрес электронной почты.
### Администратор по умолчанию {#default-admin}
При первом запуске SnapOtter создаёт учётную запись администратора по умолчанию. Учётные данные берутся из переменных окружения:
| Переменная | По умолчанию | Описание |
|---|---|---|
| `DEFAULT_USERNAME` | `admin` | Имя пользователя для начальной учётной записи администратора |
| `DEFAULT_PASSWORD` | `admin` | Пароль для начальной учётной записи администратора |
Администратор по умолчанию обязан сменить пароль при первом входе.
Задайте `AUTH_ENABLED=false`, чтобы полностью отключить аутентификацию. В этом режиме для всех запросов используется синтетический анонимный пользователь с ролью `admin`. Вход не требуется.
::: warning
Отключение аутентификации предоставляет полный доступ администратора любому, кто может достучаться до экземпляра. Используйте это только в доверенных средах.
:::
## Встроенные роли {#built-in-roles}
SnapOtter включает три встроенные роли. Их нельзя изменить или удалить.
### Admin {#admin}
Все 17 разрешений. Полный контроль над экземпляром.
| `compliance:manage` | Управление жизненным циклом GDPR и функциями соответствия требованиям; деструктивные пользовательские операции остаются ограниченными полномочиями |
| `security:manage` | Управлять настройками безопасности (список разрешённых IP, принудительное SSO) |
## Пользовательские роли {#custom-roles}
Администраторы с разрешением `security:manage` могут создавать пользовательские роли через панель администратора или API ролей. Для получения списка ролей требуется `audit:read`.
### Создание пользовательской роли {#creating-a-custom-role}
```bash
curl -X POST http://localhost:1349/api/v1/roles \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "reviewer",
"description": "Can use tools and view all files",
Все 17 разрешений можно делегировать с помощью настраиваемых ролей, но административное разрешение не делает эту роль эквивалентной встроенной роли `admin`. Пользовательские мутации, разрешенные `users:manage`, разрушительные операции, разрешенные `compliance:manage`, и управление пользовательскими ролями, разрешенные `security:manage`, ограничены текущими полномочиями актера:
- Встроенные роли следуют `admin` > `editor` > `user`; пользовательские роли находятся ниже встроенных ролей.
- Разрешения цели должны содержаться в **действующих** разрешениях субъекта. Таким образом, ключ API с ограниченной областью действия не может использовать разрешения, не включенные в его область действия.
- Доступ к инструменту целевой роли должен ограничиваться доступом к собственному инструменту актера.
- Отключенная учетная запись проверяется на соответствие ее исходной роли, если эта роль записана как `disabled:<original-role>`.
- Для удаления пользовательской роли также требуются полномочия для назначения встроенного резервного варианта `user`; отключенные участники остаются отключенными как `disabled:user`.
Глобальные учетные данные и конфигурация более строгие: для выдачи или отзыва токена SCIM и импорта конфигурации экземпляра требуется встроенная роль `admin` с полными эффективными полномочиями администратора.
### Разрешения на уровне инструментов {#tool-level-permissions}
Пользовательские роли могут опционально ограничивать, к каким инструментам может обращаться пользователь. Доступны два режима:
| Режим | Поведение | Требование лицензии |
|---|---|---|
| `category` | Ограничение по модальности (image, video, audio, document, file) | Нет (бесплатно) |
| `tool` | Ограничение по идентификатору отдельного инструмента | Требуется корпоративная функция `per_tool_permissions` |
Когда установлен режим `tool`, но корпоративная функция недоступна, SnapOtter деградирует корректно и разрешает доступ ко всем инструментам.
```json
{
"name":"image-only",
"permissions":["tools:use","files:own"],
"toolPermissions":{
"mode":"category",
"allowed":["image"]
}
}
```
### Удаление пользовательской роли {#deleting-a-custom-role}
При удалении пользовательской роли все назначенные ей пользователи автоматически переназначаются на роль `user`.
## Команды {#teams}
Команды группируют пользователей для управления хранилищем и хранением. Команда `Default` создаётся при первом запуске.
| Поле | Тип | Описание |
|---|---|---|
| `name` | string | Уникальное имя команды (1–50 символов) |
| `storageQuota` | number | Лимит хранилища на команду в байтах (работает без enterprise) |
| `retentionHours` | number | Автоудаление результатов через указанное число часов (требует `team_retention_overrides`, enterprise) |
| `legalHold` | boolean | Предотвращать автоматическое удаление файлов участников команды (требует `legal_hold`, enterprise) |
::: info
Команду `Default` нельзя удалить. Команды, в которых всё ещё есть участники, удалить нельзя. Сначала переназначьте участников.
:::
## Ключи API {#api-keys}
Пользователи могут генерировать ключи API для программного доступа. Каждый ключ использует префикс `si_` и показывается только один раз при создании.
### Ограниченные по области разрешения {#scoped-permissions}
Ключи API могут опционально нести массив `permissions`. Когда он задан, эффективные разрешения для запроса — это **пересечение** разрешений роли пользователя и ограниченных по области разрешений ключа. Это означает, что ключ API никогда не может выйти за пределы собственных разрешений пользователя.
```bash
curl -X POST http://localhost:1349/api/v1/api-keys \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "CI pipeline key",
"permissions": ["tools:use", "files:own"],
"expiresAt": "2027-01-01T00:00:00Z"
}'
```
### Истечение срока действия {#expiration}
Ключи принимают опциональную временную метку `expiresAt`. Ключи с истёкшим сроком действия отклоняются во время аутентификации.
## Журнал аудита {#audit-log}
SnapOtter записывает значимые для безопасности события в структурированный журнал аудита, хранящийся в таблице базы данных `audit_log`.
### Просмотр журнала аудита {#viewing-the-audit-log}
```
GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
```
Требует разрешение `audit:read`. Поддерживает пагинацию (`page`, `limit`) и фильтры (`action`, `ip`, `from`, `to`).
### Аудит операций с инструментами {#tool-operation-auditing}
::: warning
События `TOOL_EXECUTED`**не** журналируются по умолчанию. Они включаются опционально через один из двух путей:
1. Установите значение админ-настройки `auditToolOperations` в `true`.
2. Держите активную лицензию с функцией `audit_export` (доступна как в плане team, так и в плане enterprise).
Без одного из этих условий отдельные выполнения инструментов не записываются в журнал аудита.
:::
### Экспорт {#exporting}
```
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
```
Требует разрешение `audit:read` и корпоративную функцию `audit_export` (доступна как в плане team, так и в плане enterprise). Поддерживает форматы CSV и JSON, с фильтрацией по `action`, `actorId`, `targetType`, `targetId`, `from` и `to`.
### Защищённая от подделки подпись {#tamper-resistant-signing}
Когда включено, каждая запись журнала аудита подписывается HMAC, производным от `DATA_ENCRYPTION_KEY`. Это требует:
1. Установки `DATA_ENCRYPTION_KEY` в вашем окружении.
Сессии основаны на cookie и контролируются `SESSION_DURATION_HOURS` (по умолчанию: 168 часов / 7 дней).
### Изменение роли аннулирует сессии {#role-changes-invalidate-sessions}
Когда администратор меняет роль пользователя, все активные сессии этого пользователя удаляются. Пользователь должен войти снова, чтобы получить новые разрешения.
### Защитные ограничения {#safety-guards}
- **Защита последнего администратора**: последнего оставшегося администратора нельзя понизить до более низкой роли. API возвращает ошибку при попытке.
- **Предотвращение самоудаления**: администраторы не могут удалить собственную учётную запись через API.
