mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
d10d0f544f
A release-readiness QA pass over the whole product. The commits split into defects a user would hit and gates that were reporting green while measuring nothing. ## Fixes that change behaviour Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so request.ip came from a client-set header and a forged X-Forwarded-For got past the login limiter. The default is now a private-network trust list. A transient Postgres outage stranded in-flight jobs, leaving finished output on disk with no row pointing at it. A reconciler now resolves those rows and adopts the bytes rather than dropping the work. A Redis connection that moved to a new address wedged every read-blocked consumer, so completions stopped signalling while health still answered 200. Socket timeouts plus subscriber pings recover it. Installing more than one AI bundle left the shared venv multi-versioned and silently broke three tools. The installer now reconciles distributions to one version each. Converting an image to JXL at quality 1 through 4 returned a 500, because libjxl 0.7 rejects the distance those values compute. The quality is floored at what the encoder honours. A missing ffmpeg was also reported to the user as a corrupt upload; it now says the engine is unavailable. RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at 0.22.2, and the release scan was split so it can fail on an unfixed critical instead of hiding it behind ignore-unfixed. ## Gates that could not fail Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs build; coverage discarded its whole report on any failing test; the lint gate skipped root tests, scripts, and two workspaces; and several generated matrices counted a host missing ffmpeg as a passing tool. Each now measures what it claims. Full evidence and the outstanding release items are tracked locally and are not part of this branch.
268 lines
13 KiB
Markdown
268 lines
13 KiB
Markdown
---
|
|
description: "Zarządzaj użytkownikami, wbudowanymi i niestandardowymi rolami, uprawnieniami, kluczami API, zespołami, sesjami i dziennikiem audytu w SnapOtter."
|
|
i18n_source_hash: bea8955f3aff
|
|
i18n_provenance: human
|
|
i18n_output_hash: 0757cfbfa40d
|
|
i18n_hash_version: 2
|
|
---
|
|
|
|
# Użytkownicy, role i uprawnienia {#users-roles-permissions}
|
|
|
|
SnapOtter dostarcza trzy wbudowane role, 17 szczegółowych uprawnień oraz obsługę ról niestandardowych z opcjonalną kontrolą dostępu per narzędzie. Ta strona omawia pełny model autoryzacji, zakresowanie kluczy API, zarządzanie zespołami i rejestrowanie audytu.
|
|
|
|
::: tip Powiązane strony
|
|
[OIDC / SSO](/pl/guide/oidc) | [SAML SSO](/pl/guide/saml) | [Provisioning SCIM](/pl/guide/scim) | [Bezpieczeństwo i hartowanie](/pl/guide/security)
|
|
:::
|
|
|
|
## Użytkownicy {#users}
|
|
|
|
### Tworzenie użytkowników {#creating-users}
|
|
|
|
Administratorzy mogą tworzyć użytkowników za pośrednictwem panelu administracyjnego lub punktu końcowego `POST /api/auth/register`. Każdy użytkownik ma nazwę użytkownika, rolę, przypisanie do zespołu oraz opcjonalny adres e-mail.
|
|
|
|
### Domyślny administrator {#default-admin}
|
|
|
|
Przy pierwszym uruchomieniu SnapOtter tworzy domyślne konto administratora. Dane uwierzytelniające pochodzą ze zmiennych środowiskowych:
|
|
|
|
| Zmienna | Domyślnie | Opis |
|
|
|---|---|---|
|
|
| `DEFAULT_USERNAME` | `admin` | Nazwa użytkownika dla początkowego konta administratora |
|
|
| `DEFAULT_PASSWORD` | `admin` | Hasło dla początkowego konta administratora |
|
|
|
|
Domyślny administrator jest zobowiązany do zmiany hasła przy pierwszym logowaniu.
|
|
|
|
### Dostawcy uwierzytelniania {#authentication-providers}
|
|
|
|
Użytkownicy mogą uwierzytelniać się kilkoma metodami:
|
|
|
|
- **Lokalna** - nazwa użytkownika i hasło przechowywane w bazie danych SnapOtter
|
|
- **OIDC** - dowolny dostawca OpenID Connect (zobacz [OIDC / SSO](/pl/guide/oidc))
|
|
- **SAML** - dostawcy tożsamości SAML 2.0 (zobacz [SAML SSO](/pl/guide/saml))
|
|
- **SCIM** - automatyczny provisioning od dostawcy tożsamości (zobacz [Provisioning SCIM](/pl/guide/scim))
|
|
|
|
### Wyłączanie uwierzytelniania {#disabling-authentication}
|
|
|
|
Ustaw `AUTH_ENABLED=false`, aby całkowicie wyłączyć uwierzytelnianie. W tym trybie dla wszystkich żądań używany jest syntetyczny anonimowy użytkownik z rolą `admin`. Logowanie nie jest wymagane.
|
|
|
|
::: warning
|
|
Wyłączenie uwierzytelniania przyznaje pełny dostęp administratora każdemu, kto może dotrzeć do instancji. Używaj tego wyłącznie w zaufanych środowiskach.
|
|
:::
|
|
|
|
## Wbudowane role {#built-in-roles}
|
|
|
|
SnapOtter zawiera trzy wbudowane role. Nie można ich modyfikować ani usuwać.
|
|
|
|
### Admin {#admin}
|
|
|
|
Wszystkie 17 uprawnień. Pełna kontrola nad instancją.
|
|
|
|
`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 uprawnień. Może używać wszystkich narzędzi oraz zarządzać wszystkimi plikami i potokami, ale nie ma dostępu do funkcji administracyjnych.
|
|
|
|
`tools:use` `files:own` `files:all` `apikeys:own` `pipelines:own` `pipelines:all` `settings:read`
|
|
|
|
### User {#user}
|
|
|
|
5 uprawnień. Może używać narzędzi i zarządzać własnymi zasobami.
|
|
|
|
`tools:use` `files:own` `apikeys:own` `pipelines:own` `settings:read`
|
|
|
|
## Wykaz uprawnień {#permissions-reference}
|
|
|
|
| Uprawnienie | Opis |
|
|
|---|---|
|
|
| `tools:use` | Użycie dowolnego narzędzia przetwarzania |
|
|
| `files:own` | Przeglądanie i zarządzanie własnymi plikami |
|
|
| `files:all` | Przeglądanie i zarządzanie plikami wszystkich użytkowników |
|
|
| `apikeys:own` | Tworzenie i zarządzanie własnymi kluczami API |
|
|
| `apikeys:all` | Przeglądanie kluczy API wszystkich użytkowników |
|
|
| `pipelines:own` | Tworzenie i zarządzanie własnymi potokami |
|
|
| `pipelines:all` | Przeglądanie i zarządzanie potokami wszystkich użytkowników |
|
|
| `settings:read` | Przeglądanie ustawień instancji |
|
|
| `settings:write` | Modyfikowanie ustawień instancji |
|
|
| `users:manage` | Twórz konta użytkowników i zarządzaj nimi w granicach uprawnień aktora |
|
|
| `teams:manage` | Tworzenie, aktualizowanie i usuwanie zespołów |
|
|
| `features:manage` | Instalowanie i zarządzanie pakietami funkcji AI |
|
|
| `system:health` | Dostęp do punktów końcowych kondycji i gotowości |
|
|
| `audit:read` | Przeglądanie dziennika audytu i listowanie ról |
|
|
| `compliance:manage` | Zarządzaj cyklem życia RODO i funkcjami zgodności; destrukcyjne działania użytkownika pozostają ograniczone uprawnieniami |
|
|
| `webhooks:manage` | Konfigurowanie wychodzących webhooków |
|
|
| `security:manage` | Zarządzanie ustawieniami bezpieczeństwa (lista dozwolonych adresów IP, wymuszanie SSO) |
|
|
|
|
## Role niestandardowe {#custom-roles}
|
|
|
|
Administratorzy z uprawnieniem `security:manage` mogą tworzyć role niestandardowe za pośrednictwem panelu administracyjnego lub API ról. Listowanie ról wymaga `audit:read`.
|
|
|
|
### Tworzenie roli niestandardowej {#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"]
|
|
}'
|
|
```
|
|
|
|
Nazwy ról muszą mieć 2-30 znaków, składać się z małych liter i cyfr z myślnikami i podkreśleniami.
|
|
|
|
### Delegowane granice administracyjne {#delegated-administration-boundaries}
|
|
|
|
Wszystkie 17 uprawnień można delegować za pośrednictwem ról niestandardowych, ale uprawnienie administracyjne nie czyni tej roli równoważną wbudowanej roli `admin`. Mutacje użytkowników autoryzowane przez `users:manage`, destrukcyjne operacje autoryzowane przez `compliance:manage` i niestandardowe zarządzanie rolami autoryzowane przez `security:manage` są ograniczone bieżącymi uprawnieniami aktora:
|
|
|
|
- Wbudowane role podążają za `admin` > `editor` > `user`; role niestandardowe znajdują się poniżej ról wbudowanych.
|
|
- Uprawnienia celu muszą być zawarte w **efektywnych** uprawnieniach aktora. Dlatego klucz API o ograniczonym zakresie nie może wykonywać uprawnień pominiętych w jego zakresie.
|
|
- Dostęp do narzędzi roli docelowej musi być ograniczony dostępem do narzędzi aktora.
|
|
- Wyłączone konto jest sprawdzane pod kątem jego pierwotnej roli, gdy ta rola jest rejestrowana jako `disabled:<original-role>`.
|
|
- Usunięcie roli niestandardowej wymaga również uprawnień do przypisania wbudowanej funkcji zastępczej `user`; niepełnosprawni członkowie pozostają wyłączeni jako `disabled:user`.
|
|
|
|
Globalne dane uwierzytelniające i konfiguracja są bardziej rygorystyczne: wydawanie lub unieważnianie tokena SCIM oraz importowanie konfiguracji instancji wymagają wbudowanej roli `admin` z pełnymi skutecznymi uprawnieniami administratora.
|
|
|
|
### Uprawnienia na poziomie narzędzi {#tool-level-permissions}
|
|
|
|
Role niestandardowe mogą opcjonalnie ograniczać, do których narzędzi użytkownicy mają dostęp. Dostępne są dwa tryby:
|
|
|
|
| Tryb | Zachowanie | Wymóg licencji |
|
|
|---|---|---|
|
|
| `category` | Ograniczenie według modalności (obraz, wideo, audio, dokument, plik) | Brak (za darmo) |
|
|
| `tool` | Ograniczenie według identyfikatora poszczególnego narzędzia | Wymaga funkcji enterprise `per_tool_permissions` |
|
|
|
|
Gdy ustawiony jest tryb `tool`, ale funkcja enterprise nie jest dostępna, SnapOtter degraduje się łagodnie i zezwala na dostęp do wszystkich narzędzi.
|
|
|
|
```json
|
|
{
|
|
"name": "image-only",
|
|
"permissions": ["tools:use", "files:own"],
|
|
"toolPermissions": {
|
|
"mode": "category",
|
|
"allowed": ["image"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Usuwanie roli niestandardowej {#deleting-a-custom-role}
|
|
|
|
Gdy rola niestandardowa zostanie usunięta, wszyscy przypisani do niej użytkownicy są automatycznie przenoszeni do roli `user`.
|
|
|
|
## Zespoły {#teams}
|
|
|
|
Zespoły grupują użytkowników na potrzeby zarządzania przechowywaniem i retencją. Przy pierwszym uruchomieniu tworzony jest zespół `Default`.
|
|
|
|
| Pole | Typ | Opis |
|
|
|---|---|---|
|
|
| `name` | string | Unikatowa nazwa zespołu (1-50 znaków) |
|
|
| `storageQuota` | number | Limit przechowywania per zespół w bajtach (działa bez enterprise) |
|
|
| `retentionHours` | number | Automatyczne usuwanie danych wyjściowych po tylu godzinach (wymaga `team_retention_overrides`, enterprise) |
|
|
| `legalHold` | boolean | Zapobiega automatycznemu usuwaniu plików członków zespołu (wymaga `legal_hold`, enterprise) |
|
|
|
|
::: info
|
|
Zespołu `Default` nie można usunąć. Zespołów, które nadal mają członków, nie można usunąć. Najpierw przenieś członków.
|
|
:::
|
|
|
|
## Klucze API {#api-keys}
|
|
|
|
Użytkownicy mogą generować klucze API do dostępu programowego. Każdy klucz używa prefiksu `si_` i jest wyświetlany tylko raz, w momencie utworzenia.
|
|
|
|
### Uprawnienia zakresowe {#scoped-permissions}
|
|
|
|
Klucze API mogą opcjonalnie nieść tablicę `permissions`. Gdy jest ustawiona, efektywne uprawnienia dla żądania stanowią **część wspólną** uprawnień roli użytkownika i uprawnień zakresowych klucza. Oznacza to, że klucz API nigdy nie może eskalować poza własne uprawnienia użytkownika.
|
|
|
|
```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"
|
|
}'
|
|
```
|
|
|
|
### Wygasanie {#expiration}
|
|
|
|
Klucze akceptują opcjonalny znacznik czasu `expiresAt`. Wygasłe klucze są odrzucane w czasie uwierzytelniania.
|
|
|
|
## Dziennik audytu {#audit-log}
|
|
|
|
SnapOtter rejestruje zdarzenia istotne dla bezpieczeństwa w ustrukturyzowanym dzienniku audytu przechowywanym w tabeli bazy danych `audit_log`.
|
|
|
|
### Przeglądanie dziennika audytu {#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
|
|
```
|
|
|
|
Wymaga uprawnienia `audit:read`. Obsługuje stronicowanie (`page`, `limit`) oraz filtry (`action`, `ip`, `from`, `to`).
|
|
|
|
### Audytowanie operacji narzędzi {#tool-operation-auditing}
|
|
|
|
::: warning
|
|
Zdarzenia `TOOL_EXECUTED` **nie** są rejestrowane domyślnie. Są opcjonalne poprzez jedną z dwóch ścieżek:
|
|
|
|
1. Ustaw ustawienie administratora `auditToolOperations` na `true`.
|
|
2. Posiadaj aktywną licencję z funkcją `audit_export` (dostępną zarówno w planie team, jak i enterprise).
|
|
|
|
Bez jednego z tych warunków poszczególne wykonania narzędzi nie są zapisywane w dzienniku audytu.
|
|
:::
|
|
|
|
### Eksportowanie {#exporting}
|
|
|
|
```
|
|
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
|
|
```
|
|
|
|
Wymaga uprawnienia `audit:read` oraz funkcji enterprise `audit_export` (dostępnej zarówno w planie team, jak i enterprise). Obsługuje formaty CSV i JSON, filtrowane według `action`, `actorId`, `targetType`, `targetId`, `from` oraz `to`.
|
|
|
|
### Podpisywanie odporne na manipulacje {#tamper-resistant-signing}
|
|
|
|
Gdy jest włączone, każdy wpis dziennika audytu jest podpisywany kodem HMAC pochodzącym z `DATA_ENCRYPTION_KEY`. Wymaga to:
|
|
|
|
1. Ustawienia `DATA_ENCRYPTION_KEY` w Twoim środowisku.
|
|
2. Włączenia ustawienia administratora `tamperResistantAudit`.
|
|
3. Licencji enterprise z funkcją `tamper_resistant_audit`.
|
|
|
|
### Retencja {#retention}
|
|
|
|
Ustaw `AUDIT_RETENTION_DAYS`, aby automatycznie usuwać stare wpisy. Wartość domyślna to `0`, co oznacza, że wpisy są przechowywane bezterminowo.
|
|
|
|
### Wykaz zdarzeń {#event-reference}
|
|
|
|
| Zdarzenie | Kategoria |
|
|
|---|---|
|
|
| `LOGIN_SUCCESS`, `LOGIN_FAILED` | Uwierzytelnianie |
|
|
| `OIDC_LOGIN_SUCCESS`, `OIDC_LOGIN_FAILED` | Uwierzytelnianie |
|
|
| `SAML_LOGIN_SUCCESS`, `SAML_LOGIN_FAILED` | Uwierzytelnianie |
|
|
| `LOGOUT` | Uwierzytelnianie |
|
|
| `USER_CREATED`, `USER_UPDATED`, `USER_DELETED` | Zarządzanie użytkownikami |
|
|
| `PASSWORD_CHANGED`, `PASSWORD_RESET` | Zarządzanie użytkownikami |
|
|
| `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` | Role |
|
|
| `API_KEY_CREATED`, `API_KEY_DELETED` | Klucze API |
|
|
| `SETTINGS_UPDATED`, `IP_ALLOWLIST_UPDATED` | Ustawienia |
|
|
| `FILE_UPLOADED`, `FILE_DELETED` | Pliki |
|
|
| `TOOL_EXECUTED` | Narzędzia (opcjonalne) |
|
|
| `SCIM_USER_PROVISIONED`, `SCIM_USER_UPDATED`, `SCIM_USER_DEPROVISIONED` | SCIM |
|
|
| `SCIM_GROUP_SYNCED` | SCIM |
|
|
| `LEGAL_HOLD_APPLIED`, `LEGAL_HOLD_RELEASED` | Zgodność |
|
|
| `GDPR_EXPORT_INITIATED`, `GDPR_USER_PURGED`, `GDPR_TEAM_PURGED` | Zgodność |
|
|
| `CONFIG_EXPORTED`, `CONFIG_IMPORTED` | Konfiguracja |
|
|
|
|
## Zarządzanie sesjami {#session-management}
|
|
|
|
Sesje są oparte na plikach cookie, kontrolowane przez `SESSION_DURATION_HOURS` (domyślnie: 168 godzin / 7 dni).
|
|
|
|
### Zmiany ról unieważniają sesje {#role-changes-invalidate-sessions}
|
|
|
|
Gdy administrator zmienia rolę użytkownika, wszystkie aktywne sesje tego użytkownika są usuwane. Użytkownik musi zalogować się ponownie, aby przejąć swoje nowe uprawnienia.
|
|
|
|
### Zabezpieczenia {#safety-guards}
|
|
|
|
- **Ochrona ostatniego administratora**: ostatniego pozostałego administratora nie można zdegradować do niższej roli. API zwraca błąd, jeśli spróbujesz.
|
|
- **Zapobieganie samousunięciu**: administratorzy nie mogą usunąć własnego konta za pośrednictwem API.
|