SnapOtter/apps/docs/pl/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
Zarządzaj użytkownikami, wbudowanymi i niestandardowymi rolami, uprawnieniami, kluczami API, zespołami, sesjami i dziennikiem audytu w SnapOtter.	bea8955f3aff	human	0757cfbfa40d	2

Użytkownicy, role i uprawnienia

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 | SAML SSO | Provisioning SCIM | Bezpieczeństwo i hartowanie :::

Użytkownicy

Tworzenie użytkowników

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

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

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)
• SAML - dostawcy tożsamości SAML 2.0 (zobacz SAML SSO)
• SCIM - automatyczny provisioning od dostawcy tożsamości (zobacz Provisioning SCIM)

Wyłączanie uwierzytelniania

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

SnapOtter zawiera trzy wbudowane role. Nie można ich modyfikować ani usuwać.

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

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

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ń

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

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

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

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

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.

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

Usuwanie roli niestandardowej

Gdy rola niestandardowa zostanie usunięta, wszyscy przypisani do niej użytkownicy są automatycznie przenoszeni do roli user.

Zespoły

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

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

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.

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

Klucze akceptują opcjonalny znacznik czasu expiresAt. Wygasłe klucze są odrzucane w czasie uwierzytelniania.

Dziennik audytu

SnapOtter rejestruje zdarzenia istotne dla bezpieczeństwa w ustrukturyzowanym dzienniku audytu przechowywanym w tabeli bazy danych audit_log.

Przeglądanie dziennika audytu

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

::: 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

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

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

Ustaw AUDIT_RETENTION_DAYS, aby automatycznie usuwać stare wpisy. Wartość domyślna to 0, co oznacza, że wpisy są przechowywane bezterminowo.

Wykaz zdarzeń

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

Sesje są oparte na plikach cookie, kontrolowane przez SESSION_DURATION_HOURS (domyślnie: 168 godzin / 7 dni).

Zmiany ról unieważniają sesje

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

• 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.