mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
265 lines
18 KiB
Markdown
265 lines
18 KiB
Markdown
---
|
|
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.
|