--- description: "Управление пользователями, встроенными и пользовательскими ролями, разрешениями, ключами API, командами, сессиями и журналом аудита в SnapOtter." i18n_source_hash: 5e28af686c96 i18n_provenance: human i18n_output_hash: 140592d03c47 --- # Пользователи, роли и разрешения {#users-roles-permissions} SnapOtter поставляется с тремя встроенными ролями, 17 гранулярными разрешениями и поддержкой пользовательских ролей с опциональным контролем доступа на уровне отдельных инструментов. Эта страница охватывает полную модель авторизации, ограничение области действия ключей API, управление командами и журналирование аудита. ::: tip Связанные страницы [OIDC / SSO](/ru/guide/oidc) | [SAML SSO](/ru/guide/saml) | [Провижининг SCIM](/ru/guide/scim) | [Безопасность и усиление защиты](/ru/guide/security) ::: ## Пользователи {#users} ### Создание пользователей {#creating-users} Администраторы могут создавать пользователей через панель администратора или конечную точку `POST /api/auth/register`. У каждого пользователя есть имя пользователя, роль, назначение в команду и опциональный адрес электронной почты. ### Администратор по умолчанию {#default-admin} При первом запуске SnapOtter создаёт учётную запись администратора по умолчанию. Учётные данные берутся из переменных окружения: | Переменная | По умолчанию | Описание | |---|---|---| | `DEFAULT_USERNAME` | `admin` | Имя пользователя для начальной учётной записи администратора | | `DEFAULT_PASSWORD` | `admin` | Пароль для начальной учётной записи администратора | Администратор по умолчанию обязан сменить пароль при первом входе. ### Провайдеры аутентификации {#authentication-providers} Пользователи могут аутентифицироваться несколькими способами: - **Локально** — имя пользователя и пароль, хранящиеся в базе данных SnapOtter - **OIDC** — любой провайдер OpenID Connect (см. [OIDC / SSO](/ru/guide/oidc)) - **SAML** — провайдеры идентификации SAML 2.0 (см. [SAML SSO](/ru/guide/saml)) - **SCIM** — автоматизированный провижининг от провайдера идентификации (см. [Провижининг SCIM](/ru/guide/scim)) ### Отключение аутентификации {#disabling-authentication} Задайте `AUTH_ENABLED=false`, чтобы полностью отключить аутентификацию. В этом режиме для всех запросов используется синтетический анонимный пользователь с ролью `admin`. Вход не требуется. ::: warning Отключение аутентификации предоставляет полный доступ администратора любому, кто может достучаться до экземпляра. Используйте это только в доверенных средах. ::: ## Встроенные роли {#built-in-roles} SnapOtter включает три встроенные роли. Их нельзя изменить или удалить. ### Admin {#admin} Все 17 разрешений. Полный контроль над экземпляром. `tools:use` `files:own` `files:all` `apikeys:own` `apikeys:all` `pipelines:own` `pipelines:all` `settings:read` `settings:write` `users:manage` `teams:manage` `features:manage` `system:health` `audit:read` `compliance:manage` `webhooks:manage` `security:manage` ### Editor {#editor} 7 разрешений. Может использовать все инструменты и управлять всеми файлами и конвейерами, но не имеет доступа к административным функциям. `tools:use` `files:own` `files:all` `apikeys:own` `pipelines:own` `pipelines:all` `settings:read` ### User {#user} 5 разрешений. Может использовать инструменты и управлять собственными ресурсами. `tools:use` `files:own` `apikeys:own` `pipelines:own` `settings:read` ## Справочник по разрешениям {#permissions-reference} | Разрешение | Описание | |---|---| | `tools:use` | Использовать любой инструмент обработки | | `files:own` | Просматривать собственные файлы и управлять ими | | `files:all` | Просматривать файлы всех пользователей и управлять ими | | `apikeys:own` | Создавать собственные ключи API и управлять ими | | `apikeys:all` | Просматривать ключи API всех пользователей | | `pipelines:own` | Создавать собственные конвейеры и управлять ими | | `pipelines:all` | Просматривать конвейеры всех пользователей и управлять ими | | `settings:read` | Просматривать настройки экземпляра | | `settings:write` | Изменять настройки экземпляра | | `users:manage` | Создавать, обновлять и удалять учётные записи пользователей | | `teams:manage` | Создавать, обновлять и удалять команды | | `features:manage` | Устанавливать наборы функций ИИ и управлять ими | | `system:health` | Доступ к конечным точкам health и readiness | | `audit:read` | Просматривать журнал аудита и получать список ролей | | `compliance:manage` | Управлять жизненным циклом GDPR и функциями комплаенса | | `webhooks:manage` | Настраивать исходящие вебхуки | | `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", "permissions": ["tools:use", "files:own", "files:all", "settings:read"] }' ``` Имена ролей должны содержать от 2 до 30 символов, строчные буквенно-цифровые символы с дефисами и подчёркиваниями. ### Зарезервированные для администратора разрешения {#admin-reserved-permissions} Три разрешения зарезервированы для встроенных ролей и не могут быть назначены пользовательским ролям: - `compliance:manage` - `webhooks:manage` - `security:manage` API ролей отклоняет любой запрос, включающий эти разрешения. Доступ к ним есть только у встроенной роли `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` в вашем окружении. 2. Включения админ-настройки `tamperResistantAudit`. 3. Корпоративной лицензии с функцией `tamper_resistant_audit`. ### Хранение {#retention} Задайте `AUDIT_RETENTION_DAYS` для автоматической очистки старых записей. Значение по умолчанию — `0`, что означает, что записи хранятся бессрочно. ### Справочник по событиям {#event-reference} | Событие | Категория | |---|---| | `LOGIN_SUCCESS`, `LOGIN_FAILED` | Аутентификация | | `OIDC_LOGIN_SUCCESS`, `OIDC_LOGIN_FAILED` | Аутентификация | | `SAML_LOGIN_SUCCESS`, `SAML_LOGIN_FAILED` | Аутентификация | | `LOGOUT` | Аутентификация | | `USER_CREATED`, `USER_UPDATED`, `USER_DELETED` | Управление пользователями | | `PASSWORD_CHANGED`, `PASSWORD_RESET` | Управление пользователями | | `MFA_ENROLLED`, `MFA_DISABLED`, `MFA_VERIFIED`, `MFA_VERIFY_FAILED` | MFA | | `MFA_CHALLENGE_ISSUED`, `MFA_RECOVERY_USED`, `MFA_RESET` | MFA | | `ROLE_CREATED`, `ROLE_UPDATED`, `ROLE_DELETED` | Роли | | `API_KEY_CREATED`, `API_KEY_DELETED` | Ключи API | | `SETTINGS_UPDATED`, `IP_ALLOWLIST_UPDATED` | Настройки | | `FILE_UPLOADED`, `FILE_DELETED` | Файлы | | `TOOL_EXECUTED` | Инструменты (опционально) | | `SCIM_USER_PROVISIONED`, `SCIM_USER_UPDATED`, `SCIM_USER_DEPROVISIONED` | SCIM | | `SCIM_GROUP_SYNCED` | SCIM | | `LEGAL_HOLD_APPLIED`, `LEGAL_HOLD_RELEASED` | Комплаенс | | `GDPR_EXPORT_INITIATED`, `GDPR_USER_PURGED`, `GDPR_TEAM_PURGED` | Комплаенс | | `CONFIG_EXPORTED`, `CONFIG_IMPORTED` | Конфигурация | ## Управление сессиями {#session-management} Сессии основаны на cookie и контролируются `SESSION_DURATION_HOURS` (по умолчанию: 168 часов / 7 дней). ### Изменение роли аннулирует сессии {#role-changes-invalidate-sessions} Когда администратор меняет роль пользователя, все активные сессии этого пользователя удаляются. Пользователь должен войти снова, чтобы получить новые разрешения. ### Защитные ограничения {#safety-guards} - **Защита последнего администратора**: последнего оставшегося администратора нельзя понизить до более низкой роли. API возвращает ошибку при попытке. - **Предотвращение самоудаления**: администраторы не могут удалить собственную учётную запись через API.