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

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

Связанные страницы

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.

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

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

Зарезервированные для администратора разрешения

Три разрешения зарезервированы для встроенных ролей и не могут быть назначены пользовательским ролям:

compliance:manage
webhooks:manage
security:manage

API ролей отклоняет любой запрос, включающий эти разрешения. Доступ к ним есть только у встроенной роли admin.

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

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

Режим	Поведение	Требование лицензии
`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"]
  }
}

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

При удалении пользовательской роли все назначенные ей пользователи автоматически переназначаются на роль 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 никогда не может выйти за пределы собственных разрешений пользователя.

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

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

Ключи принимают опциональную временную метку 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 не журналируются по умолчанию. Они включаются опционально через один из двух путей:

Установите значение админ-настройки auditToolOperations в true.
Держите активную лицензию с функцией 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. Это требует:

Установки DATA_ENCRYPTION_KEY в вашем окружении.
Включения админ-настройки tamperResistantAudit.
Корпоративной лицензии с функцией 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.

Essentials

Optimization

Adjustments

Watermark & Overlay

Utilities

Layout

Format

AI Tools

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