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

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

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

### Границы делегированного администрирования {#delegated-administration-boundaries}

Все 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` в вашем окружении.
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.