OIDC / Logowanie jednokrotne

SnapOtter obsługuje OpenID Connect (OIDC) do logowania jednokrotnego. Użytkownicy mogą logować się za pomocą zewnętrznego dostawcy tożsamości, takiego jak Keycloak, Authentik czy Google, zamiast (lub obok) lokalnego uwierzytelniania nazwą użytkownika i hasłem.

Zobacz też

SAML SSO | Provisioning SCIM | Użytkownicy, role i uprawnienia

Szybki start

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

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

URI przekierowania dla Twojego dostawcy zawsze wynosi:

${EXTERNAL_URL}/api/auth/oidc/callback

Na przykład, jeśli EXTERNAL_URL to https://photos.example.com, skonfiguruj URI przekierowania dostawcy jako https://photos.example.com/api/auth/oidc/callback.

Dokumentacja konfiguracji

Zmienna	Domyślnie	Opis
OIDC_ENABLED	false	Włącz logowanie OIDC. Na stronie logowania pojawia się przycisk „Zaloguj się przez SSO”.
OIDC_ISSUER_URL		URL wydawcy (issuer) dostawcy. Musi obsługiwać OIDC Discovery (/.well-known/openid-configuration).
OIDC_CLIENT_ID		Identyfikator klienta OAuth zarejestrowany u Twojego dostawcy.
OIDC_CLIENT_SECRET		Sekret klienta OAuth.
OIDC_SCOPES	openid profile email	Lista zakresów do zażądania, rozdzielona spacjami.
OIDC_AUTO_CREATE_USERS	true	Automatycznie utwórz lokalne konto użytkownika przy pierwszym logowaniu OIDC.
OIDC_DEFAULT_ROLE	user	Rola przypisana automatycznie tworzonym użytkownikom OIDC. Jedna z: admin, editor lub user.
OIDC_AUTO_LINK_USERS	false	Powiąż tożsamość OIDC z istniejącym lokalnym użytkownikiem, jeśli adres e-mail się zgadza.
OIDC_PROVIDER_NAME		Wyświetlana nazwa na przycisku logowania (np. „Keycloak”, „Google”). Jeśli puste, przycisk pokazuje „SSO”.
OIDC_CLOCK_TOLERANCE	30	Tolerancja odchylenia zegara w sekundach przy walidacji tokenu.
OIDC_USERNAME_CLAIM	preferred_username	Oświadczenie (claim) tokenu ID używane jako nazwa użytkownika dla nowych kont.
EXTERNAL_URL		Publiczny URL, pod którym SnapOtter jest osiągalny. Wymagany, aby OIDC zbudowało poprawne URI przekierowania.
COOKIE_SECRET	generowany automatycznie	Sekret do podpisywania ciasteczek sesji. Ustaw go jawnie, gdy uruchamiasz wiele replik.

Przewodniki dla dostawców

Keycloak

1. Utwórz nowy realm (lub użyj istniejącego).
2. Przejdź do Clients i utwórz nowego klienta:
   • Client ID: snapotter
   • Client authentication: On (poufny)
   • Authentication flow: Standard flow (Authorization Code)
3. W zakładce Settings klienta ustaw Valid redirect URIs na swój adres URL wywołania zwrotnego (np. https://photos.example.com/api/auth/oidc/callback).
4. Skopiuj Client secret z zakładki Credentials.
5. Ustaw OIDC_ISSUER_URL na https://keycloak.example.com/realms/your-realm.

Authentik

1. W interfejsie administracyjnym przejdź do Applications > Providers i utwórz nowego OAuth2/OpenID Provider.
   • Client type: Confidential
   • Redirect URIs: Twój adres URL wywołania zwrotnego
   • Signing key: Wybierz istniejący klucz lub utwórz nowy
2. Utwórz Application i powiąż ją z dostawcą.
3. Skopiuj Client ID oraz Client Secret z ustawień dostawcy.
4. Ustaw OIDC_ISSUER_URL na https://authentik.example.com/application/o/snapotter/ (końcowy ukośnik ma znaczenie).

Google

1. Przejdź do Google Cloud Console.
2. Utwórz projekt (lub wybierz istniejący).
3. Przejdź do APIs & Services > OAuth consent screen i skonfiguruj go.
4. Przejdź do APIs & Services > Credentials i utwórz OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: Twój adres URL wywołania zwrotnego
5. Skopiuj Client ID oraz Client secret.
6. Ustaw OIDC_ISSUER_URL na https://accounts.google.com.
7. Ustaw OIDC_USERNAME_CLAIM na email (Google nie udostępnia preferred_username).

Provisioning użytkowników

Automatyczne tworzenie

Gdy OIDC_AUTO_CREATE_USERS ma wartość true (domyślnie), lokalne konto użytkownika jest tworzone przy pierwszym logowaniu przez OIDC. Nazwa użytkownika pochodzi z oświadczenia (claim) określonego przez OIDC_USERNAME_CLAIM, a rola jest ustawiana na OIDC_DEFAULT_ROLE.

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

Automatyczne łączenie

Gdy OIDC_AUTO_LINK_USERS ma wartość true, SnapOtter łączy tożsamość OIDC 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 OIDC weryfikuje adresy e-mail. Niezweryfikowany e-mail mógłby pozwolić komuś na przejęcie konta innego użytkownika.

Wyłączanie logowania lokalnego

OIDC nie wyłącza lokalnego logowania nazwą użytkownika i hasłem. Obie metody pozostają dostępne. Administratorzy nadal mogą logować się przy użyciu danych lokalnych, jeśli dostawca OIDC jest nieosiągalny.

Certyfikaty samopodpisane

Jeśli Twój dostawca OIDC używa certyfikatu samopodpisanego lub z prywatnego CA, zamontuj pakiet CA w kontenerze i wskaż na niego NODE_EXTRA_CA_CERTS:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

Nie ustawiaj NODE_TLS_REJECT_UNAUTHORIZED=0. Wyłącza to całą weryfikację TLS i stanowi zagrożenie bezpieczeństwa.

Rozwiązywanie problemów

Niezgodność URI przekierowania

Najczęstszy błąd. Sprawdź te różnice między tym, czego oczekuje Twój dostawca, a tym, co wysyła SnapOtter:

• http kontra https - schemat musi się dokładnie zgadzać
• Końcowy ukośnik - niektórzy dostawcy są pod tym względem rygorystyczni
• Numer portu - dołącz port, jeśli jest niestandardowy
• Ścieżka - musi być /api/auth/oidc/callback

Sprawdź dokładnie EXTERNAL_URL. Musi zgadzać się z URL-em, który użytkownicy wpisują w przeglądarce.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

Dostawca OIDC używa certyfikatu, któremu Node.js nie ufa. Zobacz Certyfikaty samopodpisane powyżej.

Błędy odchylenia zegara

Jeśli zegar Twojego serwera i zegar dostawcy OIDC nie są zsynchronizowane, walidacja tokenu może się nie powieść. Zwiększ OIDC_CLOCK_TOLERANCE (domyślnie 30 sekund). Lepszym rozwiązaniem jest uruchomienie NTP na obu maszynach.

„Dostawca OIDC nieosiągalny”

SnapOtter pobiera dokument discovery dostawcy przy starcie oraz podczas logowania. Sprawdź:

• Rozwiązywanie DNS z wnętrza kontenera Docker (docker exec snapotter nslookup auth.example.com)
• Reguły zapory między kontenerem a dostawcą
• Wartość OIDC_ISSUER_URL - musi być osiągalna z serwera, a nie tylko z Twojej przeglądarki

Brakujące oświadczenia (claims)

Jeśli po zalogowaniu nazwy użytkowników lub adresy e-mail są puste, Twój dostawca może nie zwracać oczekiwanych oświadczeń. Zweryfikuj:

• Zakresy skonfigurowane w OIDC_SCOPES obejmują profile oraz email
• Dostawca jest skonfigurowany tak, aby dołączać oświadczenie określone w OIDC_USERNAME_CLAIM do tokenu ID
• Niektórzy dostawcy wymagają jawnej konfiguracji mappera/zakresu, aby udostępnić oświadczenia