SnapOtter/apps/docs/ru/guide/users-roles.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version

description	i18n_source_hash	i18n_provenance	i18n_output_hash	i18n_hash_version
Управление пользователями, встроенными и пользовательскими ролями, разрешениями, ключами API, командами, сессиями и журналом аудита в SnapOtter.	bea8955f3aff	human	7e3c6824072e	2

Пользователи, роли и разрешения

SnapOtter поставляется с тремя встроенными ролями, 17 гранулярными разрешениями и поддержкой пользовательских ролей с опциональным контролем доступа на уровне отдельных инструментов. Эта страница охватывает полную модель авторизации, ограничение области действия ключей API, управление командами и журналирование аудита.

::: tip Связанные страницы OIDC / SSO | SAML SSO | Провижининг SCIM | Безопасность и усиление защиты :::

Пользователи

Создание пользователей

Администраторы могут создавать пользователей через панель администратора или конечную точку POST /api/auth/register. У каждого пользователя есть имя пользователя, роль, назначение в команду и опциональный адрес электронной почты.

Администратор по умолчанию

При первом запуске SnapOtter создаёт учётную запись администратора по умолчанию. Учётные данные берутся из переменных окружения:

Переменная	По умолчанию	Описание
DEFAULT_USERNAME	admin	Имя пользователя для начальной учётной записи администратора
DEFAULT_PASSWORD	admin	Пароль для начальной учётной записи администратора

Администратор по умолчанию обязан сменить пароль при первом входе.

Провайдеры аутентификации

Пользователи могут аутентифицироваться несколькими способами:

• Локально — имя пользователя и пароль, хранящиеся в базе данных SnapOtter
• OIDC — любой провайдер OpenID Connect (см. OIDC / SSO)
• SAML — провайдеры идентификации SAML 2.0 (см. SAML SSO)
• SCIM — автоматизированный провижининг от провайдера идентификации (см. Провижининг SCIM)

Отключение аутентификации

Задайте AUTH_ENABLED=false, чтобы полностью отключить аутентификацию. В этом режиме для всех запросов используется синтетический анонимный пользователь с ролью admin. Вход не требуется.

::: warning Отключение аутентификации предоставляет полный доступ администратора любому, кто может достучаться до экземпляра. Используйте это только в доверенных средах. :::

Встроенные роли

SnapOtter включает три встроенные роли. Их нельзя изменить или удалить.

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

7 разрешений. Может использовать все инструменты и управлять всеми файлами и конвейерами, но не имеет доступа к административным функциям.

tools:use files:own files:all apikeys:own pipelines:own pipelines:all settings:read

User

5 разрешений. Может использовать инструменты и управлять собственными ресурсами.

tools:use files:own apikeys:own pipelines:own settings:read

Справочник по разрешениям

Разрешение	Описание
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)

Пользовательские роли

Администраторы с разрешением security:manage могут создавать пользовательские роли через панель администратора или API ролей. Для получения списка ролей требуется audit:read.

Создание пользовательской роли

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 символов, строчные буквенно-цифровые символы с дефисами и подчёркиваниями.

Границы делегированного администрирования

Все 17 разрешений можно делегировать с помощью настраиваемых ролей, но административное разрешение не делает эту роль эквивалентной встроенной роли admin. Пользовательские мутации, разрешенные users:manage, разрушительные операции, разрешенные compliance:manage, и управление пользовательскими ролями, разрешенные security:manage, ограничены текущими полномочиями актера:

• Встроенные роли следуют admin > editor > user; пользовательские роли находятся ниже встроенных ролей.
• Разрешения цели должны содержаться в действующих разрешениях субъекта. Таким образом, ключ API с ограниченной областью действия не может использовать разрешения, не включенные в его область действия.
• Доступ к инструменту целевой роли должен ограничиваться доступом к собственному инструменту актера.
• Отключенная учетная запись проверяется на соответствие ее исходной роли, если эта роль записана как disabled:<original-role>.
• Для удаления пользовательской роли также требуются полномочия для назначения встроенного резервного варианта user; отключенные участники остаются отключенными как disabled:user.

Глобальные учетные данные и конфигурация более строгие: для выдачи или отзыва токена SCIM и импорта конфигурации экземпляра требуется встроенная роль admin с полными эффективными полномочиями администратора.

Разрешения на уровне инструментов

Пользовательские роли могут опционально ограничивать, к каким инструментам может обращаться пользователь. Доступны два режима:

Режим	Поведение	Требование лицензии
category	Ограничение по модальности (image, video, audio, document, file)	Нет (бесплатно)
tool	Ограничение по идентификатору отдельного инструмента	Требуется корпоративная функция per_tool_permissions

Когда установлен режим tool, но корпоративная функция недоступна, SnapOtter деградирует корректно и разрешает доступ ко всем инструментам.

{
  "name": "image-only",
  "permissions": ["tools:use", "files:own"],
  "toolPermissions": {
    "mode": "category",
    "allowed": ["image"]
  }
}

Удаление пользовательской роли

При удалении пользовательской роли все назначенные ей пользователи автоматически переназначаются на роль user.

Команды

Команды группируют пользователей для управления хранилищем и хранением. Команда Default создаётся при первом запуске.

Поле	Тип	Описание
name	string	Уникальное имя команды (1–50 символов)
storageQuota	number	Лимит хранилища на команду в байтах (работает без enterprise)
retentionHours	number	Автоудаление результатов через указанное число часов (требует team_retention_overrides, enterprise)
legalHold	boolean	Предотвращать автоматическое удаление файлов участников команды (требует legal_hold, enterprise)

::: info Команду Default нельзя удалить. Команды, в которых всё ещё есть участники, удалить нельзя. Сначала переназначьте участников. :::

Ключи API

Пользователи могут генерировать ключи API для программного доступа. Каждый ключ использует префикс si_ и показывается только один раз при создании.

Ограниченные по области разрешения

Ключи API могут опционально нести массив permissions. Когда он задан, эффективные разрешения для запроса — это пересечение разрешений роли пользователя и ограниченных по области разрешений ключа. Это означает, что ключ API никогда не может выйти за пределы собственных разрешений пользователя.

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"
  }'

Истечение срока действия

Ключи принимают опциональную временную метку expiresAt. Ключи с истёкшим сроком действия отклоняются во время аутентификации.

Журнал аудита

SnapOtter записывает значимые для безопасности события в структурированный журнал аудита, хранящийся в таблице базы данных 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).

Аудит операций с инструментами

::: warning События TOOL_EXECUTED не журналируются по умолчанию. Они включаются опционально через один из двух путей:

1. Установите значение админ-настройки auditToolOperations в true.
2. Держите активную лицензию с функцией audit_export (доступна как в плане team, так и в плане enterprise).

Без одного из этих условий отдельные выполнения инструментов не записываются в журнал аудита. :::

Экспорт

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.

Защищённая от подделки подпись

Когда включено, каждая запись журнала аудита подписывается HMAC, производным от DATA_ENCRYPTION_KEY. Это требует:

1. Установки DATA_ENCRYPTION_KEY в вашем окружении.
2. Включения админ-настройки tamperResistantAudit.
3. Корпоративной лицензии с функцией tamper_resistant_audit.

Хранение

Задайте AUDIT_RETENTION_DAYS для автоматической очистки старых записей. Значение по умолчанию — 0, что означает, что записи хранятся бессрочно.

Справочник по событиям

Событие	Категория
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	Конфигурация

Управление сессиями

Сессии основаны на cookie и контролируются SESSION_DURATION_HOURS (по умолчанию: 168 часов / 7 дней).

Изменение роли аннулирует сессии

Когда администратор меняет роль пользователя, все активные сессии этого пользователя удаляются. Пользователь должен войти снова, чтобы получить новые разрешения.

Защитные ограничения

• Защита последнего администратора: последнего оставшегося администратора нельзя понизить до более низкой роли. API возвращает ошибку при попытке.
• Предотвращение самоудаления: администраторы не могут удалить собственную учётную запись через API.