Spis treści
Cześć!
Dzisiaj przedstawię Ci kroki konfiguracji usługi jednokrotnego logowania (SSO) pomiędzy serwerem Paperless-ngx, a Authentik.
Wstęp
Czym jest Paperless-ngx?
Paperless-ngx jest nowoczesnym rozwiązaniem open source, przeznaczonym do bezpapierowego zarządzania dokumentami. Jest to fork projektu Paperless, który został stworzony z myślą o skanowaniu, tagowaniu, przeszukiwaniu i zarządzaniu cyfrowymi kopiami dokumentów papierowych w celu zminimalizowania potrzeby przechowywania fizycznych kopii. Paperless-ngx oferuje szereg ulepszeń w stosunku do oryginalnego projektu, w tym lepsze wsparcie dla interfejsu użytkownika, bardziej zaawansowane opcje przeszukiwania, automatyczne tagowanie dokumentów na podstawie ich zawartości oraz wsparcie dla OCR (rozpoznawanie znaków optyczne) w wielu językach, co pozwala na łatwiejsze zarządzanie i wyszukiwanie dokumentów w bazie danych.
Projekt ten jest szczególnie przydatny dla osób i firm dążących do zredukowania ilości papieru w swojej pracy i życiu codziennym. Oferuje prosty i wydajny sposób na organizację cyfrowych dokumentów.
Czym jest Authentik?
Authentik to otwarte oprogramowanie służące jako dostawca tożsamości (Identity Provider), umożliwiające zarządzanie uwierzytelnianiem i autoryzacją użytkowników. Jako alternatywa dla komercyjnych usług takich jak Okta czy One Login, Authentik oferuje podobne funkcjonalności w modelu open-source. Wśród innych narzędzi open-source o podobnym przeznaczeniu znajdują się Keycloak oraz Authelia, które również pozwalają na centralne zarządzanie tożsamością użytkowników w aplikacjach i usługach webowych.
Wyróżnia się elastycznością konfiguracji i szerokim wsparciem dla różnych protokołów uwierzytelniania, co czyni go doskonałym wyborem dla organizacji poszukujących zaawansowanego, ale dostępnego rozwiązania open-source do zarządzania tożsamością.
Wdrożenie OpenID Connect do najnowszej aktualizacji
W najnowszej aktualizacji Paperless-ngx, wersja 2.5.0, wprowadzono istotne zmiany i ulepszenia, w tym wsparcie dla OpenID Connect, co jest znaczącym krokiem w kierunku ułatwienia integracji z zewnętrznymi dostawcami tożsamości.
Wcześniejsze konfiguracje logowania jednokrotnego (Single Sign-On) w Paperless-ngx z użyciem dostawców tożsamości opierały się na przekazywaniu informacji o uwierzytelnieniu użytkownika przez nagłówek HTTP. Użytkownicy konfigurowali system, aby akceptował nazwy użytkowników przekazywane przez nagłówek, co umożliwiało integrację z systemami IdP jak Authentik. Dzięki temu rozwiązaniu możliwe było ułatwienie procesu logowania, eliminując potrzebę wielokrotnego wprowadzania danych uwierzytelniających przy dostępie do różnych aplikacji. Więcej szczegółów na temat tej konfiguracji można znaleźć na GitHubie Paperless-ngx.
Korzystanie z nagłówków do jednokrotnego logowania
Użycie nagłówków HTTP do logowania jednokrotnego w Paperless-ngx ma zarówno zalety, jak i wady. Plusy obejmują uproszczenie procesu logowania przez eliminację konieczności wielokrotnego wpisywania danych uwierzytelniających oraz integrację z systemami SSO, co zwiększa wygodę użytkowania. Minusy mogą dotyczyć bezpieczeństwa, gdyż nieodpowiednia konfiguracja serwera proxy lub niewłaściwe zarządzanie nagłówkami może prowadzić do luk w zabezpieczeniach, np. przez możliwość podszywania się pod użytkownika. Ważne jest zatem dokładne zabezpieczenie przekazywania nagłówków i upewnienie się, że są one odpowiednio weryfikowane.
Korzyści z aktualizacji
Integracja OIDC, zgodnie z pull requestem #5190 na GitHubie, umożliwia użytkownikom logowanie się do Paperless-ngx przy użyciu zewnętrznych dostawców tożsamości. Jest to szczególnie przydatne w środowiskach biznesowych lub dla użytkowników prywatnych, którzy preferują korzystanie z jednego uwierzytelniania do zarządzania dostępem do wielu aplikacji. Dzięki tej aktualizacji, zarządzanie dostępem i tożsamościami staje się bardziej centralne i bezpieczne, redukując potrzebę zarządzania wieloma hasłami.
Przygotowanie
W celu przygotowania poradnika, przyjmiemy nazwy domen oraz identyfikatory opisane poniżej. W trakcie konfiguracji, dostosuj ustawienia zgodnie z własnymi potrzebami.
- Pełna nazwa domeny (FQDN) Paperless-ngx: https://paperless.xyz.com
- Pełna nazwa domeny (FQDN) Authentik: https://auth.xyz.com
Czym jest OpenID Connect?
Protokół OpenID Connect (OIDC) jest warstwą uwierzytelniania opartą na protokole OAuth 2.0, który umożliwia bezpieczne uwierzytelnianie i zdobywanie informacji o tożsamości użytkownika w aplikacjach internetowych. Poniżej znajdują się kluczowe elementy, które opisują, jak działa OpenID Connect:
- Uwierzytelnianie przez OAuth 2.0: OpenID Connect wykorzystuje protokół OAuth 2.0 jako podstawę do uwierzytelniania. OAuth 2.0 umożliwia aplikacjom dostęp do zasobów na rzecz użytkownika, a OpenID Connect rozszerza ten protokół o warstwę uwierzytelniania.
- Wydawanie Tokenów: Po pomyślnym uwierzytelnieniu użytkownika dostaje się tokeny, które zawierają informacje o tożsamości. Są to zazwyczaj:
- ID Token: Zawiera podstawowe informacje o użytkowniku, takie jak identyfikator, imię, nazwisko itp.
- Access Token: Umożliwia dostęp do zasobów chronionych w imieniu użytkownika.
- Refresh Token: Służy do odświeżania lub uzyskiwania nowych tokenów po upływie ważności.
- JSON Web Tokens (JWT): Informacje przesyłane w tokenach są często zakodowane w formie JSON Web Tokens, co zapewnia ich zwięzłość i bezpieczeństwo.
- End-User Authentication: OpenID Connect obsługuje różne metody uwierzytelniania użytkownika, takie jak logowanie za pomocą hasła, uwierzytelnianie wieloskładnikowe czy nawet zewnętrzne dostawcy tożsamości.
- Informacje o Konfiguracji: Identyfikatory i informacje niezbędne do autoryzacji i otrzymywania tokenów są uzyskiwane z dokumentu konfiguracyjnego, który jest zazwyczaj dostępny pod stałym adresem URL.
- Bezpieczeństwo przez TLS: Komunikacja między klientem a dostawcą tożsamości, a także między dostawcą a serwerem zasobów, powinna odbywać się poprzez bezpieczne połączenie TLS (HTTPS).
Podsumowując, OpenID Connect ułatwia bezpieczne i skuteczne uwierzytelnianie użytkowników w aplikacjach internetowych, umożliwiając jednocześnie zdobycie informacji o ich tożsamości za pomocą tokenów.
Działanie OpenID Connect
Proces działania protokołu OpenID Connect (OIDC) można podzielić na kilka kroków. Poniżej znajdziesz ogólny opis etapów zaangażowanych w ten proces:
- Rozpoczęcie Autoryzacji (Authorization Request):
- Użytkownik chce zalogować się do aplikacji, obsługującej OpenID Connect.
- Aplikacja kieruje go do dostawcy tożsamości (IdP) z żądaniem autoryzacji.
- Żądanie to zawiera zakresy (scopes) dostępu, które aplikacja chce uzyskać, oraz informacje o tym, jakie działania są wymagane po zakończeniu autoryzacji.
- Uwierzytelnianie Użytkownika (Authentication):
- Dostawca tożsamości autoryzuje użytkownika.
- Jeśli użytkownik nie jest zalogowany, może być poproszony o podanie swoich danych uwierzytelniających.
- Przekierowanie z Powrotem (Redirection Back):
- Po pomyślnym uwierzytelnieniu użytkownika dostawca tożsamości przekierowuje go z powrotem do aplikacji, dostarczając jednocześnie kod autoryzacyjny.
- Wymiana Kodu na Tokeny (Token Exchange):
- Aplikacja przesyła otrzymany kod autoryzacyjny z powrotem do dostawcy tożsamości.
- W zamian otrzymuje zestaw tokenów, takich jak ID Token, Access Token i ewentualnie Refresh Token.
- Korzystanie z Tokenów (Access Resources):
- Aplikacja używa otrzymanego Access Token do uzyskania dostępu do zasobów chronionych w imieniu użytkownika.
- Dostęp do zasobów może być ograniczony zakresem dostępu określonym w tokenie.
- Weryfikacja Tokenów (Token Verification):
- Aplikacja weryfikuje poprawność otrzymanych tokenów, zwłaszcza ID Token, który zawiera informacje o tożsamości użytkownika.
- Weryfikacja może obejmować sprawdzenie podpisu tokena, jego ważności i zgodności z żądaniami autoryzacji.
- Odświeżanie Tokenów (Token Refresh):
- W przypadku użycia Refresh Token, aplikacja może odświeżyć swoje tokeny bez konieczności ponownego uwierzytelniania użytkownika.
Krok 1 – Instalacja Paperless-ngx na Synology
Zastanawiasz się, jak zainstalować Paperless-ngx na serwerze Synology? Krok 1 to podstawa, która przybliży Cię do osiągnięcia tego celu. Dowiedz się, jak skonfigurować swoje środowisko i zacząć korzystać z zaawansowanego zarządzania dokumentami bez papieru. Zapraszam do zapoznania się z moim najnowszym artykułem, gdzie krok po kroku wyjaśniam, jak to zrobić.
👉 Przejdź do instrukcji i zacznij transformację swoich dokumentów już dziś!
Krok 2 – Skonfigurowanie Nginx Proxy Managera w Portainerze
Zanim przystąpisz do implementacji Single Sign-On na Synology z Paperlessem-ngx, upewnij się, że Twój Nginx Proxy Manager jest skonfigurowany. Nie wiesz, jak to zrobić? Spokojnie! W moim najnowszym artykule znajdziesz szybką instrukcję, jak to zrobić krok po kroku przy użyciu Docker Compose w Portainerze.
👉 Sprawdź krok 2 teraz i przygotuj swoje środowisko do kolejnych wzmocnień!
Krok 3 – Skonfigurowanie Single Sign-On w Portainerze
Czy już wiesz, jak sprawić, by logowanie do Portainera było jednoczesne i bezproblemowe dzięki Single Sign-On? Jeśli nie, to czas to zmienić! W moim najnowszym poradniku krok po kroku dowiesz się, jak skonfigurować SSO z wykorzystaniem Authentik i Portainera.
👉 Odwiedź krok 3 teraz i zyskaj łatwiejszy dostęp do swojego środowiska Docker!
Krok 3 – Konfiguracja w Authentik
Poprzednia konfiguracja oparta o HTTP header
Jeśli wcześniej używałeś jednokrotnego logowania w Paperless-ngx za pomocą nagłówka HTTP i chcesz przejść na OpenID Connect, wykonaj następujące czynności:
- Usuń poprzednią konfigurację z Authentik przez Proxy Provider i skonfiguruj na nowo zgodnie z instrukcjami dla OpenID Connect
- Dla użytkowników Reverse Proxy np Nginx Proxy Manager: Zamień w Proxy Hosts port który przekierowywał do Authentik (jako Proxy Provider), na port odpowiadający temu który skonfigurowałeś wcześniej (np. 8777).
- W Docker Compose usuń określone parametry związane z poprzednią metodą autoryzacji i zapisz nową konfigurację.
PAPERLESS_ENABLE_HTTP_REMOTE_USER: TRUE
PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME: HTTP_X_AUTHENTIK_USERNAMETworzenie nowej konfiguracji w oparciu o OpenID Connect
- Zaloguj się na swoje konto i przejdź do interfejsu administracyjnego,
- Po pomyślnym zalogowaniu się do interfejsu administracyjnego, przejdź po lewej stronie ekranu do zakładki Applications, a następnie wybierz Providers.
- Kliknij przycisk Create i wybierz rodzaj providera OAuth2/OpenID Provider. Następnie przejdź dalej, klikając Next.
- Wypełnij providera następującymi wartościami:
- Name: paperless
- Authentication flow: Wybierz swój skonfigurowany lub ustaw domyślny (default-authentication-flow)
- Authorization flow: Wybierz swój skonfigurowany lub ustaw explicit lub implicit consent. (Ustawienie to odnosi się do funkcji używanej podczas autoryzacji dla tej aplikacji – definiujemy, czy Authentik ma wyświetlać przycisk umożliwiający przejście do aplikacji po zalogowaniu, czy po prostu ma Cię przekierować bez pytania).
- Protocol settings:
- Client type: Zostawiamy Confidential
- Client ID: Skopiuj i zachowaj na później
- Client Secret: Skopiuj i zachowaj na później
- Redirect URIs/Origins (RegEx): https://paperless.xyz.com/accounts/oidc/authentik/login/callback/
- Signing Key: authentik Self-signed Certificate
- Pozostaw pozostałe wartości bez zmian i kliknij Finish.
- Po lewej stronie ekranu wybierz Applications, a następnie ponownie Applications.
- Kliknij Create I wypełnij aplikację następującymi wartościami:
- Name: Paperless-ngx
- Slug: paperless-ngx
- Provider: paperless
- UI Settings możesz, ale nie musisz uzupełniać.
- Icon: pobierz ikonę Paperless-ngx z Internetu i wgraj.
- Publisher: np. GitHub community
- Description: Document Management System
- Zatwierdzamy utworzenie aplikacji przyciskiem Create.
Po stronie dostawcy tożsamości zakończyliśmy już niezbędne kroki. Teraz przyszedł czas na konfigurację systemu zarządzania dokumentami.
Krok 4 – Edycja parametrów w Docker Compose
W tym kroku zajmiemy się edycją parametrów w pliku Docker Compose, aby umożliwić korzystanie z systemów jednokrotnego logowania.
- Zaloguj się na swoje konto i przejdź do interfejsu administracyjnego Portainera.
- Wybierz swoje środowisko (eng: Environments) w którym będziesz edytować konfigurację utworzonego Docker Compose. Następnie przejdź do Stacks.
- Wybierz utworzony Stack o nazwie paperless-ngx (lub nazwany według Ciebie, odpowiadający Paperlessowi).
- Dodaj parametr do Environment przy Web serverze Paperless-ngx opisany poniżej:
PAPERLESS_APPS: "allauth.socialaccount.providers.openid_connect"
PAPERLESS_SOCIALACCOUNT_PROVIDERS: '{"openid_connect": {"APPS": [{"provider_id": "authentik","name": "Authentik SSO","client_id": "XX Client ID z Authentika XX","secret": "XX Client Secret z Authentika XX","settings": { "server_url": "https://auth.xyz.com/application/o/paperless-ngx/.well-known/openid-configuration"}}]}}'W podanym fragmencie konfiguracji, ustawiona wartość w PAPERLESS_APPS określać nam będzie używanie komponentu biblioteki Django Allauth, umożliwiający integrację z różnymi dostawcami tożsamości za pomocą standardu OpenID Connect. Z kolei PAPERLESS_SOCIALACCOUNT_PROVIDERS zawiera szczegółową komunikację połączenia z IdP Authentik, w tym identyfikator klienta, sekret klienta i adres URL serwera Well Known, gdzie znajduje się konfiguracja OIDC.
- Kliknij przycisk Deploy the stack, a następnie poczekaj, dopóki aż Portainer przetworzy nową zawartość i utworzy ponownie kontenery.
Krok 5 – Konfiguracja w Paperless-ngx
Nowa integracja z IdP
- Zaloguj się na swoje konto i przejdź do interfejsu systemu zarządzania dokumentami.
- Kliknij na swoje imię w prawym górnym rogu ekranu, aby otworzyć menu kontekstowe, a następnie wybierz opcję My Profile.
- W sekcji Connect new social account wybierz opcję Authentik SSO, aby połączyć swoje konto z IdP.
- Po wybraniu opcji połączenia z IdP w sekcji Connect new social account, zostaniesz przekierowany na stronę Authentika, aby dokonać autoryzacji połączenia między Twoim istniejącym kontem lokalnym w Paperlessie, a dostawcą tożsamości. Po zakończeniu procesu i powrocie do Paperless, zobaczysz swoje konto jako połączone z IdP.
- Gotowe! Teraz, aby zalogować się przy użyciu Authentik jako dostawcy tożsamości, wystarczy się wylogować, a następnie ponownie przejść do ekranu logowania, gdzie będziesz mógł skorzystać z nowo skonfigurowanej metody uwierzytelniania.
Jeśli masz dodatkowe pytania dotyczące konfiguracji, śmiało zostaw komentarz pod tym artykułem lub skontaktuj się ze mną bezpośrednio. Chętnie odpowiem na wszelkie wątpliwości i pomogę rozwiązać ewentualne problemy. Twoje pytania mogą pomóc w ulepszeniu tego poradnika dla innych użytkowników.
Dodatkowe źródła i Informacje
Chcesz wiedzieć, jak umożliwić wgranie podpisanych cyfrowo plików PDF do Paperless-ngx? Mój artykuł krok po kroku pokaże Ci, jak to zrobić, zapewniając wygodę i efektywność zarządzania dokumentami. Odkryj, jakie ustawienia są kluczowe, aby bezproblemowo integrować podpisane dokumenty z Twoim systemem.
👉 Dowiedz się więcej o procesie i ułatw sobie zarządzanie dokumentami.
W celu dalszego zgłębienia tematu i uzyskania szczegółowych informacji, polecam sprawdzenie poniższych linków. Są one wartościowymi źródłami, które zostały wykorzystane podczas opracowywania tego poradnika:
- https://docs.paperless-ngx.com – Paperless-ngx documentation,
- https://docs.allauth.org/en/latest/socialaccount/providers/openid_connect.html – OpenID Connect w Django-Allauth.
Przeczytaj także
- Jak skonfigurować wkładkę Leox GPON ONT na routerze Mikrotik / Poradnik krok po kroku jak skonfigurować wkładkę Leox LXT-010S-H GPON ONT na routerze Mikrotik RB5009, zamiast modułu ONT od Orange.
- UniFi Network Application: Podłączenie Access Point z innej sieci / Odkryj jak podłączyć urządzenie od Ubiquiti UniFi z innej sieci do Network Application – na przykładzie tunelu IPSec w Mikrotiku.
- UniFi Controller w Dockerze: Migracja do UniFi Network Application / UniFi Controller: Odkryj krok po kroku, jak skutecznie przeprowadzić migrację do Network Application, wykorzystując Docker Compose.
- Home Assistant: Instalacja oświetlenia lustra na ESPHome / Skonfiguruj proste oświetlenie lustra z ESPHome w Home Assistant. Odkryj prostą integrację i steruj światłem z łatwością.
- ADS-B: Instalacja i konfiguracja odbiornika na Raspberry Pi / Odkryj tajniki instalacji i konfiguracji własnej anteny ADS-B na Raspberry Pi. Rozwijaj umiejętności i śledź samoloty w czasie rzeczywistym.
- Traccar: Przewodnik instalacji na Synology w Dockerze / Przewodnik krok po kroku: Instalacja Traccar na Synology za pomocą Docker. Skuteczne śledzenie pojazdów na własnym serwerze.
Dodaj komentarz