SnapOtter/apps/docs/pl/guide/saml.md

---
description: "Skonfiguruj logowanie jednokrotne SAML 2.0 dla SnapOtter. Przewodniki krok po kroku dla Okta, Azure AD / Entra ID, Google Workspace i innych dostawców tożsamości SAML."
i18n_source_hash: 33dfb8b02a22
i18n_provenance: human
i18n_output_hash: 7da57fbad7c8
---

# SAML SSO {#saml-sso}

SnapOtter obsługuje SAML 2.0 do logowania jednokrotnego. Użytkownicy mogą logować się przez zewnętrznego dostawcę tożsamości (Okta, Azure AD / Entra ID, Google Workspace lub dowolny standardowy dostawca tożsamości SAML 2.0) zamiast lokalnego uwierzytelniania nazwą użytkownika i hasłem.

::: tip Funkcja Enterprise
SAML SSO wymaga licencji **team** lub **enterprise** z funkcją `saml_sso`. Jeśli `SAML_ENABLED=true` jest ustawione bez ważnej licencji, trasy SAML są po cichu pomijane, a w logach zapisywane jest ostrzeżenie.
:::

## Wymagania wstępne {#prerequisites}

- Działająca instancja SnapOtter osiągalna pod publicznym adresem URL
- `EXTERNAL_URL` ustawione na ten publiczny adres URL (np. `https://photos.example.com`)
- Klucz licencji team lub enterprise z funkcją `saml_sso`
- Dostęp administracyjny do Twojego dostawcy tożsamości SAML

## Szybki start {#quick-start}

Dodaj te zmienne środowiskowe do swojego `docker-compose.yml`:

```yaml
services:
  snapotter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      SNAPOTTER_LICENSE_KEY: "your-license-key"
      SAML_ENABLED: "true"
      SAML_IDP_SSO_URL: "https://idp.example.com/sso/saml"
      SAML_IDP_CERTIFICATE: |
        MIICpDCCAYwCCQDU+pQ4pHgSpDANBgkqhkiG9w0BAQsFADAUMRIw
        ...your IdP's signing certificate in PEM format...
        EAYHKoZIzj0CAQYFK4EEACIDYgAE
```

Uruchom ponownie kontener. Na stronie logowania pojawia się przycisk „Zaloguj się przez SAML” (lub etykieta ustawiona przez `SAML_PROVIDER_NAME`).

## Dokumentacja konfiguracji {#configuration-reference}

| Zmienna | Domyślnie | Opis |
|---|---|---|
| `SAML_ENABLED` | `false` | Włącz logowanie SAML. |
| `SAML_IDP_SSO_URL` | | Adres URL punktu końcowego SSO dostawcy tożsamości. **Wymagane**, gdy SAML jest włączone. |
| `SAML_IDP_CERTIFICATE` | | Certyfikat podpisujący X.509 dostawcy tożsamości w formacie PEM (sam tekst certyfikatu, a nie ścieżka do pliku). **Wymagane**, gdy SAML jest włączone. |
| `EXTERNAL_URL` | | Publiczny URL, pod którym SnapOtter jest osiągalny. **Wymagane**, gdy SAML jest włączone. |
| `SAML_ENTITY_ID` | `${EXTERNAL_URL}/api/auth/saml/metadata` | SP Entity ID / Audience URI wysyłane do dostawcy tożsamości. |
| `SAML_CALLBACK_URL` | `${EXTERNAL_URL}/api/auth/saml/callback` | Adres URL Assertion Consumer Service (ACS). |
| `SAML_AUTO_CREATE_USERS` | `true` | Automatycznie utwórz lokalne konto użytkownika przy pierwszym logowaniu SAML. |
| `SAML_AUTO_LINK_USERS` | `false` | Powiąż tożsamość SAML z istniejącym lokalnym użytkownikiem, jeśli adres e-mail się zgadza. |
| `SAML_DEFAULT_ROLE` | `user` | Rola przypisana automatycznie tworzonym użytkownikom SAML. Jedna z: `admin`, `editor` lub `user`. |
| `SAML_PROVIDER_NAME` | | Etykieta wyświetlana dla przycisku logowania SAML we frontendzie (np. „Okta”, „Azure AD”). Jeśli puste, przycisk pokazuje „SAML”. |
| `SAML_USERNAME_ATTRIBUTE` | | Atrybut asercji SAML używany jako nazwa użytkownika. Jeśli puste, wraca do lokalnej części e-maila, a następnie NameID. |
| `SAML_EMAIL_ATTRIBUTE` | `email` | Atrybut asercji SAML używany jako adres e-mail użytkownika. |

Serwer odmawia uruchomienia, jeśli `SAML_ENABLED=true` i brakuje którejkolwiek z trzech wymaganych zmiennych (`SAML_IDP_SSO_URL`, `SAML_IDP_CERTIFICATE`, `EXTERNAL_URL`).

::: details Uwagi dotyczące bezpieczeństwa
Zarówno `wantAuthnResponseSigned`, jak i `wantAssertionsSigned` są zakodowane na stałe na `true`. SnapOtter odrzuca niepodpisane lub nieprawidłowo podpisane odpowiedzi SAML. Asercje od zaufanego dostawcy tożsamości są traktowane jako e-mail zweryfikowany.

Obsługiwane jest tylko logowanie inicjowane przez SP. SnapOtter nie obsługuje logowania inicjowanego przez dostawcę tożsamości (niezamówionego) ani wylogowania jednokrotnego (SLO). Wylogowanie z SnapOtter nie wylogowuje użytkownika z dostawcy tożsamości.
:::

## Metadane SP i adresy URL {#sp-metadata-and-urls}

Twój dostawca tożsamości potrzebuje trzech wartości od SnapOtter:

| Pole | Wartość |
|---|---|
| **ACS URL** (Assertion Consumer Service) | `${EXTERNAL_URL}/api/auth/saml/callback` |
| **Entity ID** / **Audience URI** | `${EXTERNAL_URL}/api/auth/saml/metadata` |
| **Metadane SP** (XML) | `GET ${EXTERNAL_URL}/api/auth/saml/metadata` |

Na przykład, jeśli `EXTERNAL_URL` to `https://photos.example.com`:

- ACS URL: `https://photos.example.com/api/auth/saml/callback`
- Entity ID: `https://photos.example.com/api/auth/saml/metadata`
- Punkt końcowy metadanych: `https://photos.example.com/api/auth/saml/metadata` (zwraca XML)

Niektórzy dostawcy tożsamości mogą bezpośrednio zaimportować URL metadanych SP, co automatycznie uzupełnia ACS URL i Entity ID.

## Konfiguracja dostawcy {#provider-setup}

### Okta {#okta}

1. W konsoli administracyjnej Okta przejdź do **Applications > Create App Integration**.
2. Wybierz **SAML 2.0** i kliknij **Next**.
3. Ustaw nazwę (np. „SnapOtter”) i kliknij **Next**.
4. Skonfiguruj ustawienia SAML:
   - **Single sign-on URL**: Twój ACS URL (np. `https://photos.example.com/api/auth/saml/callback`)
   - **Audience URI (SP Entity ID)**: Twój Entity ID (np. `https://photos.example.com/api/auth/saml/metadata`)
   - **Name ID format**: EmailAddress
   - **Application username**: Email
5. W sekcji **Attribute Statements** dodaj `email` zmapowane na `user.email`.
6. Kliknij **Next**, a następnie **Finish**.
7. Przejdź do zakładki **Sign On**, kliknij **View SAML setup instructions** i skopiuj:
   - **Identity Provider Single Sign-On URL** do `SAML_IDP_SSO_URL`
   - **X.509 Certificate** do `SAML_IDP_CERTIFICATE`

### Azure AD / Entra ID {#azure-ad-entra-id}

1. W portalu Azure przejdź do **Microsoft Entra ID > Enterprise applications > New application**.
2. Kliknij **Create your own application**, nazwij ją „SnapOtter” i wybierz **Integrate any other application you don't find in the gallery**.
3. Przejdź do **Single sign-on > SAML** i kliknij **Edit** w sekcji **Basic SAML Configuration**:
   - **Identifier (Entity ID)**: Twój Entity ID (np. `https://photos.example.com/api/auth/saml/metadata`)
   - **Reply URL (ACS URL)**: Twój ACS URL (np. `https://photos.example.com/api/auth/saml/callback`)
4. W sekcji **SAML Certificates** pobierz **Certificate (Base64)**.
5. W sekcji **Set up SnapOtter** skopiuj **Login URL**.
6. Ustaw `SAML_IDP_SSO_URL` na Login URL, a `SAML_IDP_CERTIFICATE` na zawartość pobranego certyfikatu.
7. Przypisz użytkowników lub grupy do aplikacji w sekcji **Users and groups**.

### Google Workspace {#google-workspace}

1. W konsoli administracyjnej Google przejdź do **Apps > Web and mobile apps > Add app > Add custom SAML app**.
2. Nazwij aplikację „SnapOtter” i kliknij **Continue**.
3. Na stronie **Google Identity Provider details** skopiuj **SSO URL** i pobierz **Certificate**. Kliknij **Continue**.
4. Skonfiguruj szczegóły dostawcy usług (Service Provider):
   - **ACS URL**: Twój ACS URL (np. `https://photos.example.com/api/auth/saml/callback`)
   - **Entity ID**: Twój Entity ID (np. `https://photos.example.com/api/auth/saml/metadata`)
   - **Name ID format**: EMAIL
   - **Name ID**: Basic Information > Primary email
5. Kliknij **Continue**, a następnie **Finish**.
6. Włącz aplikację (**ON**) dla swoich jednostek organizacyjnych.
7. Ustaw `SAML_IDP_SSO_URL` na SSO URL z kroku 3, a `SAML_IDP_CERTIFICATE` na zawartość pobranego certyfikatu.

### Ogólny dostawca tożsamości SAML 2.0 {#generic-saml-2-0-idp}

Dla dowolnego dostawcy tożsamości zgodnego z SAML 2.0:

1. Utwórz nową aplikację SAML / dostawcę usług w swoim dostawcy tożsamości.
2. Ustaw **ACS URL** na `${EXTERNAL_URL}/api/auth/saml/callback`.
3. Ustaw **Entity ID** / **Audience** na `${EXTERNAL_URL}/api/auth/saml/metadata`.
4. Skonfiguruj dostawcę tożsamości tak, aby wysyłał adres e-mail użytkownika w atrybucie o nazwie `email` (lub ustaw `SAML_EMAIL_ATTRIBUTE`, aby dopasować do nazwy atrybutu Twojego dostawcy tożsamości).
5. Skopiuj **IdP SSO URL** oraz **certyfikat podpisujący** do `SAML_IDP_SSO_URL` i `SAML_IDP_CERTIFICATE`.

## Provisioning użytkowników {#user-provisioning}

### Automatyczne tworzenie {#auto-create}

Gdy `SAML_AUTO_CREATE_USERS` ma wartość `true` (domyślnie), lokalne konto użytkownika jest tworzone przy pierwszym logowaniu przez SAML. Rola jest ustawiana na `SAML_DEFAULT_ROLE`.

Nazwa użytkownika jest ustalana w tej kolejności:

1. Wartość atrybutu asercji określonego przez `SAML_USERNAME_ATTRIBUTE` (jeśli ustawiony i obecny)
2. Lokalna część adresu e-mail (wszystko przed `@`)
3. SAML NameID

Jeśli wystąpi konflikt nazw użytkowników, dodawany jest sufiks numeryczny (np. `jane` staje się `jane_2`).

### Automatyczne łączenie {#auto-link}

Gdy `SAML_AUTO_LINK_USERS` ma wartość `true`, SnapOtter łączy tożsamość SAML z istniejącym lokalnym kontem, jeśli adresy e-mail się zgadzają. Jest to przydatne, gdy masz wcześniej utworzone konta użytkowników i chcesz, aby zaczęli korzystać z SSO bez utraty swoich danych.

::: warning 
Włączaj automatyczne łączenie tylko wtedy, gdy ufasz, że Twój dostawca tożsamości SAML weryfikuje adresy e-mail. Niezweryfikowany e-mail od źle skonfigurowanego dostawcy tożsamości mógłby pozwolić komuś na przejęcie konta innego użytkownika.
:::

### Mapowanie atrybutów {#attribute-mapping}

| Pole SnapOtter | Źródło | Konfiguracja |
|---|---|---|
| Email | Atrybut asercji | `SAML_EMAIL_ATTRIBUTE` (domyślnie: `email`) |
| Nazwa użytkownika | Atrybut asercji, e-mail lub NameID | `SAML_USERNAME_ATTRIBUTE` (zobacz kolejność ustalania powyżej) |
| Identyfikator zewnętrzny | NameID | Zawsze SAML NameID, nie do skonfigurowania |

## Wymuszanie SSO {#sso-enforcement}

Jeśli chcesz wymagać, aby wszyscy użytkownicy logowali się przez SAML (lub OIDC) i zablokować lokalne logowanie hasłem, włącz wymuszanie SSO:

1. Upewnij się, że funkcja enterprise `sso_enforcement` jest objęta licencją (dostępna w planach team i enterprise).
2. W **Admin Settings > Security** przełącz **SSO Enforcement** na włączone.
3. Ustaw **break-glass username**: to jedno lokalne konto, które nadal może logować się hasłem, na wypadek awaryjnego dostępu, gdy dostawca tożsamości jest nieosiągalny.

Gdy wymuszanie SSO jest aktywne, każda próba lokalnego logowania (poza użytkownikiem break-glass) zwraca błąd 403 z komunikatem „Local password login is disabled. Please use SSO.”

::: tip 
Zawsze skonfiguruj break-glass username przed włączeniem wymuszania SSO. Bez niego możesz zostać zablokowany poza SnapOtter, jeśli Twój dostawca tożsamości ulegnie awarii.
:::

## Używanie SAML obok OIDC {#using-saml-alongside-oidc}

SAML i OIDC można włączyć jednocześnie. Gdy oba są aktywne, strona logowania pokazuje osobne przyciski dla każdego dostawcy (oznaczone przez `SAML_PROVIDER_NAME` i `OIDC_PROVIDER_NAME`). Użytkownicy mogą logować się dowolną metodą.

Obaj dostawcy niezależnie korzystają z tych samych ustawień automatycznego tworzenia, automatycznego łączenia i wymuszania SSO: każdy ma własne zmienne `*_AUTO_CREATE_USERS`, `*_AUTO_LINK_USERS` oraz `*_DEFAULT_ROLE`.

## Rozwiązywanie problemów {#troubleshooting}

### Walidacja asercji nie powiodła się {#assertion-validation-failed}

Nie udało się zweryfikować podpisu odpowiedzi SAML lub podpisu asercji. Sprawdź:

- Czy certyfikat w `SAML_IDP_CERTIFICATE` zgadza się z aktualnym certyfikatem podpisującym w Twoim dostawcy tożsamości (certyfikaty się rotują, więc sprawdź datę wygaśnięcia)
- Czy certyfikat jest w formacie PEM (zaczyna się od `-----BEGIN CERTIFICATE-----`)
- Czy certyfikat to pełny tekst, a nie ścieżka do pliku
- Czy ACS URL i Entity ID skonfigurowane w Twoim dostawcy tożsamości dokładnie zgadzają się z wartościami SnapOtter (schemat, host, port, ścieżka)

### Brakujące atrybuty {#missing-attributes}

Jeśli po zalogowaniu nazwy użytkowników lub adresy e-mail są puste, Twój dostawca tożsamości może nie wysyłać oczekiwanych atrybutów. Sprawdź:

- Czy Twój dostawca tożsamości jest skonfigurowany, aby udostępniać atrybut `email` (lub taki, na jaki ustawiono `SAML_EMAIL_ATTRIBUTE`)
- Jeśli używasz `SAML_USERNAME_ATTRIBUTE`, zweryfikuj, że ten atrybut jest zawarty w asercji
- Niektórzy dostawcy tożsamości wymagają jawnej konfiguracji mapowania atrybutów, zanim udostępnią oświadczenia

### Odchylenie zegara {#clock-skew}

Asercje SAML zawierają warunki znacznika czasu (`NotBefore`, `NotOnOrAfter`). Jeśli zegar Twojego serwera i zegar dostawcy tożsamości nie są zsynchronizowane, walidacja asercji się nie powiedzie. Uruchom NTP na obu maszynach, aby zegary były zsynchronizowane.

### „SAML is enabled via env but saml_sso enterprise feature is not licensed” {#saml-is-enabled-via-env-but-saml-sso-enterprise-feature-is-not-licensed}

To ostrzeżenie pojawia się w logach serwera, gdy `SAML_ENABLED=true`, ale licencja nie obejmuje funkcji `saml_sso`. Zweryfikuj swój klucz licencji i plan. Funkcja `saml_sso` jest dostępna w planach team i enterprise.

### Logowanie przekierowuje z powrotem z błędem {#login-redirects-back-with-error}

Jeśli kliknięcie przycisku logowania SAML przekierowuje z powrotem na stronę logowania z błędem, sprawdź szczegóły w logach serwera. Częste przyczyny:

- IdP SSO URL jest nieosiągalny z serwera
- Dostawca tożsamości odrzucił żądanie uwierzytelnienia (sprawdź logi audytu dostawcy tożsamości)
- Dostawca tożsamości zwrócił niepodpisaną odpowiedź (SnapOtter wymaga, aby zarówno odpowiedź, jak i asercja były podpisane)