Authentik: konfiguracja SSO przez Docker Compose

Jeden login dla każdej hostowanej aplikacji

Authentik to samodzielnie hostowany serwer SSO (single sign-on): użytkownicy logują się raz, a każda aplikacja za nim akceptuje tę sesję zamiast prosić o własne hasło. Instalacja opiera się na oficjalnym pliku Docker Compose oraz dwóch wygenerowanych sekretach. Część wymagająca rzeczywistego przemyślenia następuje później: skierowanie na niego reverse proxy i umieszczenie istniejącej aplikacji za forward auth.

Authentik jest dostarczany jako trzy usługi w tym pliku Compose: baza danych PostgreSQL, proces server oraz proces worker. Kontener serwera uruchamia również wbudowany outpost, czyli komponent odpowiadający na pytanie „czy to żądanie jest uwierzytelnione?” dla każdej chronionej aplikacji. Wersja 2026.8.3 jest aktualnym wydaniem na stan z października 2026 roku. Została opublikowana 17 września 2026 roku jako najnowsza poprawka serii 2026.8, która rozpoczęła się wersją 2026.8.0 w dniu 18 sierpnia, a oficjalny plik Compose używa jej teraz jako domyślnego tagu obrazu. Projekt wymaga hosta z co najmniej 2 rdzeniami CPU i 2 GB pamięci RAM. Należy traktować to jako wartość minimalną. PostgreSQL oraz proces worker zajmują pamięć po dobie działania serwera.

Wymagania wstępne

Wymagane jest środowisko Docker Engine z wtyczką Compose v2, co można zweryfikować za pomocą docker compose version. Jeśli polecenie to zwraca błąd zamiast wersji, należy zainstalować wtyczkę przed przejściem do dalszych kroków; podstawy zostały opisane w uruchamianie aplikacji za pomocą Docker Compose na VPS. Wymagany jest również rekord DNS typu A wskazujący na serwer, oznaczony jako auth.example.com w poniższych przykładach, ponieważ Authentik generuje adresy URL przekierowań na podstawie nazwy hosta użytej przez przeglądarkę.

Stos należy uruchamiać jako zwykły użytkownik należący do grupy docker, a nie jako root. Członkostwo w tej grupie jest równoważne z uprawnieniami roota na hoście, dlatego należy przyznać je wyłącznie jednemu kontu wdrożeniowemu, zgodnie z zasadami opisanymi w konta użytkowników z minimalnymi uprawnieniami na VPS.

Instalacja przy użyciu oficjalnego pliku Compose

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps powinien wyświetlić listę trzech kontenerów, przy czym postgresql zgłasza healthy, a server oraz worker zgłaszają running. Pierwsze uruchomienie wykonuje migracje bazy danych, dlatego należy odczekać minutę, zanim interfejs WWW zacznie odpowiadać.

Obie wygenerowane wartości są istotne z różnych powodów. PG_PASS to hasło do PostgreSQL, które posiada twardy limit 99 znaków. AUTHENTIK_SECRET_KEY służy do podpisywania sesji oraz tokenów, więc jego późniejsza zmiana wyloguje wszystkich użytkowników i unieważni wszystkie wydane tokeny API. Plik .env należy przechowywać z uprawnieniami 600 i wykonać jego kopię zapasową w bezpiecznym miejscu, ponieważ baza danych przywrócona bez pasującego klucza tajnego jest bazą, do której nikt nie może się zalogować.

Plik Compose odczytuje obie wartości w formacie ${PG_PASS:?database password required}, co oznacza, że Compose odmawia uruchomienia, gdy plik jest nieobecny. Uruchomienie docker compose up -d z niewłaściwego katalogu powoduje wyświetlenie required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required i zatrzymanie procesu. Ten komunikat wskazuje na problem ze ścieżką, a nie z konfiguracją.

Istotne zmienne środowiskowe

Wszystkie pozostałe parametry umieszcza się w tym samym pliku .env. Authentik interpretuje podwójne podkreślenie jako zagnieżdżony klucz konfiguracji, dlatego AUTHENTIK_EMAIL__HOST ustawia email.host. Pojedyncze podkreślenie jest ignorowane bez ostrzeżenia, co stanowi najczęstszą przyczynę sytuacji, w której ustawienie wydaje się nie działać.

• AUTHENTIK_BOOTSTRAP_PASSWORD ustawia hasło wbudowanego użytkownika akadmin przy pierwszym uruchomieniu, dzięki czemu nie trzeba wpisywać go w publicznym formularzu internetowym. AUTHENTIK_BOOTSTRAP_EMAIL oraz AUTHENTIK_BOOTSTRAP_TOKEN ustawiają w ten sam sposób adres e-mail tego użytkownika oraz token API.
• COMPOSE_PORT_HTTP oraz COMPOSE_PORT_HTTPS zmieniają domyślne porty 9000 i 9443 na inne.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS oraz AUTHENTIK_EMAIL__FROM konfigurują pocztę wychodzącą. Bez nich Authentik próbuje użyć localhost na porcie 25, co skutkuje błędem połączenia w dzienniku procesu worker podczas wysyłania wiadomości z resetem hasła.
• AUTHENTIK_LOG_LEVEL=debug włącza szczegółowe logowanie przydatne podczas diagnozowania problemów z procesem logowania. Po zakończeniu prac należy przywrócić wartość info.
• AUTHENTIK_ERROR_REPORTING__ENABLED jest domyślnie ustawione na false. Wartość true należy ustawić tylko w przypadku zgody na przesyłanie raportów o awariach do twórców oprogramowania.

Są to dane uwierzytelniające przechowywane w pliku tekstowym, dlatego katalog z tym plikiem należy traktować jak każdy inny magazyn haseł. Menedżer haseł, taki jak samodzielnie hostowana instancja Vaultwarden, jest lepszym miejscem na kopię zapasową niż notatka na laptopie.

Pierwsze logowanie i konto administratora

Otwórz http://SERVER_IP:9000 w przeglądarce. Authentik wyświetli proces wstępnej konfiguracji i poprosi o ustawienie hasła dla domyślnego użytkownika akadmin. Jeśli AUTHENTIK_BOOTSTRAP_PASSWORD zostało już ustawione, ten krok jest pominięty i następuje przekierowanie bezpośrednio do strony logowania.

Utwórz osobne konto administratora w sekcji Directory, a następnie Users, dodaj je do grupy authentik Admins i zaloguj się na to konto. Pozostaw akadmin jako konto awaryjne (break-glass) z długim hasłem przechowywanym w trybie offline. Codzienna praca na współdzielonym, wbudowanym koncie uniemożliwia prowadzenie rzetelnego audytu, ponieważ każde zdarzenie jest przypisane do akadmin, co uniemożliwia identyfikację sprawcy. Ten argument dotyczy również systemów zintegrowanych z Authentik: rozwiązania takie jak własny zestaw narzędzi OneCLI przypisujący każdemu użytkownikowi osobnego agenta zapewniają czytelną ścieżkę audytu tylko wtedy, gdy tożsamość przekazywana do systemu należy do konkretnej osoby, a nie do konta współdzielonego przez cały zespół.

Umieszczenie Authentik za reverse proxy

Udostępnienie portu 9000 w Internecie działa, jednak wymagane jest TLS (transport layer security) oraz właściwa nazwa hosta. Jeśli konfiguracja z Traefik jako reverse proxy dla wielu aplikacji Compose jest już uruchomiona, należy dołączyć Authentik do tej samej zewnętrznej sieci proxy za pomocą pliku override. Należy utworzyć docker-compose.override.yml obok compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Zastosuj zmiany za pomocą docker compose up -d. Compose automatycznie scala plik override, dzięki czemu usługa server zachowuje wszystkie ustawienia z oficjalnego pliku i zyskuje dodatkowe etykiety. Weryfikację przeprowadza się za pomocą curl -I https://auth.example.com/if/user/, co powinno zwrócić HTTP/2 200. Błąd 404 page not found ze strony Traefik oznacza, że kontener nie znajduje się w sieci proxy, przez co Traefik nie może skierować ruchu do kontenera, z którym nie ma połączenia.

Gdy nazwa hosta zacznie działać, należy ograniczyć powiązanie opublikowanych portów do 127.0.0.1 w pliku override, aby jedyną drogą dostępu pozostało proxy.

Ochrona aplikacji za pomocą forward auth

Dostawca proxy w Authentik oferuje trzy tryby pracy, a wybór niewłaściwego skutkuje stratą czasu. Tryb Proxy oznacza, że sam outpost przekazuje ruch do aplikacji nadrzędnej. Forward auth (single application) oznacza, że własny reverse proxy obsługuje ruch i jedynie pyta Authentik, czy żądanie jest uwierzytelnione. Forward auth (domain level) chroni wszystkie aplikacje w ramach jednej domeny nadrzędnej za pomocą jednego dostawcy, kosztem braku możliwości definiowania reguł autoryzacji dla poszczególnych aplikacji. Przy użyciu Traefik należy wybrać forward auth (single application). Jeśli potrzebna jest konkretna aplikacja do testów, dobrym kandydatem będzie samodzielnie hostowany obszar roboczy AFFiNE, ponieważ jest to narzędzie wewnętrzne, które powinno być dostępne wyłącznie z własnych urządzeń. W przypadku narzędzi zespołowych argument jest jeszcze silniejszy: umieszczenie samodzielnie hostowanego systemu wsparcia Chatwoot za tym samym dostawcą pozwala użytkownikom zalogować się raz dziennie, zamiast udostępniać kolejne hasło.

W interfejsie webowym należy przejść do Applications, następnie Providers, utworzyć Proxy Provider, wybrać tryb forward auth single application i ustawić external host na https://app.example.com. Następnie należy utworzyć Application wskazującą na tego dostawcę. Kolejnym krokiem jest otwarcie sekcji Outposts, edycja authentik Embedded Outpost i dodanie nowej aplikacji do listy wybranych aplikacji (selected applications). Outpost odpowiada tylko za przypisane mu aplikacje, dlatego pominięcie tego kroku sprawia, że poprawnie skonfigurowany dostawca nie zwraca żadnej odpowiedzi.

Middleware należy zdefiniować raz, w kontenerze Authentik, a następnie odwoływać się do niego z każdej chronionej aplikacji:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders to lista nagłówków, które Traefik kopiuje z odpowiedzi Authentik do żądania wysyłanego do backendu. Pominięcie tej konfiguracji sprawi, że aplikacja będzie chroniona, ale nie otrzyma informacji o użytkowniku, przez co funkcje odczytujące X-authentik-username w celu automatycznego logowania nie zadziałają. Problem ten jest najbardziej widoczny w aplikacjach posiadających własny mechanizm logowania, takich jak samodzielnie hostowany tracker treningów openGym z obsługą passkey, gdzie nagłówki decydują o tym, czy użytkownik musi logować się raz, czy dwukrotnie.

Chroniona aplikacja wymaga dwóch routerów, a nie jednego:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

Drugi router jest elementem, o którym często się zapomina. Po zalogowaniu Authentik przekierowuje przeglądarkę na ścieżkę pod adresem /outpost.goauthentik.io/ w domenie aplikacji, a nie auth.example.com. Bez routera przekazującego ten prefiks ścieżki do usługi Authentik, żądanie trafi bezpośrednio do aplikacji, która zwróci błąd 404, a proces logowania nie zostanie zakończony. Wyższa wartość priority sprawia, że reguła dla konkretnej ścieżki ma pierwszeństwo przed ogólną regułą Host() w tej samej domenie.

Test należy przeprowadzić w oknie prywatnym przeglądarki. Użytkownik powinien zostać przekierowany na auth.example.com, zalogować się i wrócić do aplikacji. docker compose logs -f server po stronie Authentik rejestruje zdarzenie autoryzacji dla każdej próby, co pozwala sprawdzić, czy żądanie w ogóle dotarło do Authentik.

Typowe przyczyny awarii

Niekończąca się pętla przekierowań między aplikacją a stroną logowania. Zewnętrzny host u dostawcy nie zgadza się z adresem używanym przez przeglądarkę; zazwyczaj jest to http:// u dostawcy w porównaniu z https:// w pasku adresu. Ciasteczko sesyjne jest wówczas ustawiane dla innego źródła, więc każda kolejna próba wygląda jak nowe, anonimowe żądanie. Należy poprawić zewnętrzny host i wyczyścić ciasteczka dla obu domen przed ponownym testowaniem.

Błąd 404 pod adresem /outpost.goauthentik.io/start. Brak routera typu outpost lub jego priorytet jest niższy niż routera typu catch-all dla danego hosta.

Aplikacja ładuje się bez żądania logowania. Etykieta middlewares wskazuje na middleware, który nie istnieje. Traefik nie zgłasza ostrzeżeń w takiej sytuacji, więc literówka w authentik@docker oznacza po prostu, że żaden middleware nie jest uruchamiany. Należy otworzyć panel sterowania Traefik i sprawdzić, czy router zawiera listę middleware.

Błąd 403 z Authentik po poprawnym zalogowaniu. Użytkownik jest uwierzytelniony, ale nieautoryzowany: aplikacja posiada powiązanie z polityką lub wymóg przynależności do grupy, których dany użytkownik nie spełnia. Dziennik zdarzeń (Events) w interfejsie administratora wskazuje nazwę polityki, która odmówiła dostępu.

Kiedy Keycloak jest lepszym wyborem

Keycloak to starszy projekt, wspierany przez Red Hat, który stanowi solidniejsze rozwiązanie w klasycznych zastosowaniach korporacyjnych: rozbudowanej federacji SAML, pośredniczeniu w logowaniu z wielu zewnętrznych dostawców tożsamości jednocześnie oraz eksporcie i imporcie realmów jako udokumentowanej ścieżce migracji. Komercyjne wsparcie jest dla niektórych organizacji wymogiem formalnym. Ceną za to jest brak wbudowanego proxy w Keycloak, co oznacza, że zabezpieczenie aplikacji nieobsługującej OIDC (OpenID Connect) wymaga uruchomienia dodatkowego komponentu, takiego jak oauth2-proxy. Wbudowany dostawca proxy w Authentik stanowi gotowe, zintegrowane rozwiązanie, dlatego większość użytkowników samodzielnie hostujących zróżnicowany zestaw aplikacji wybiera właśnie to narzędzie.

Kopie zapasowe i aktualizacje

Trzy elementy umożliwiają przywrócenie systemu: baza danych PostgreSQL, katalog ./data oraz .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Należy przechowywać ten zrzut bazy danych oraz .env razem. Sam zrzut jest niewystarczający, ponieważ klucz kryptograficzny chroniący dane sesji i tokenów znajduje się w .env.

Aktualizacje polegają na zmianie tagu obrazu. Należy ustawić AUTHENTIK_TAG w pliku .env na wybraną wersję, a następnie wykonać docker compose pull, a po nim docker compose up -d. Jeśli zmienna AUTHENTIK_TAG nie została zdefiniowana, wersja jest pobierana z wartości domyślnej zapisanej w samym compose.yml. W takim przypadku pobranie nowszej kopii tego pliku stanowi proces aktualizacji, co jest ścieżką opisaną w oficjalnej dokumentacji. Należy najpierw zapoznać się z informacjami o wydaniu. Authentik stosuje wersjonowanie oparte na dacie. Według stanu na październik 2026, dokumentacja wskazuje, że aktualizacje muszą odbywać się zgodnie z kolejnością wydań głównych: należy przejść do najnowszej poprawki w ramach używanej serii, a następnie przechodzić przez każdą kolejną serię bez pomijania żadnej z nich. Authentik nie wspiera procedury przywracania starszej wersji, dlatego zrzut bazy danych należy wykonać przed operacją pull, a nie po niej.

FAQ

Czy Authentik jest darmowy do samodzielnego hostowania?

Wersja open source jest darmowa i obejmuje wszystkie wymienione funkcje: dostawcę proxy, forward auth, OIDC (OpenID Connect), SAML oraz silnik przepływów (flows engine). Płatna wersja enterprise oferuje wsparcie techniczne oraz dodatkowe funkcje korporacyjne, jednak żadne z opisanych tutaj rozwiązań nie wymaga licencji.

Czy do korzystania z Authentik wymagany jest Traefik?

Nie. Mechanizm forward auth współpracuje z nginx poprzez auth_request oraz z Caddy poprzez forward_auth. Schemat działania jest w każdym przypadku identyczny: reverse proxy wysyła zapytanie do Authentik w sprawie każdego żądania, a ścieżka /outpost.goauthentik.io/ na chronionym hoście musi być kierowana do Authentik zamiast do samej aplikacji.

Dlaczego chroniona aplikacja ciągle przełącza się między logowaniem a błędem?

Zewnętrzny host skonfigurowany u dostawcy proxy nie zgadza się z adresem URL używanym przez przeglądarkę, najczęściej w przypadku http względem https. Ciasteczko sesyjne jest wydawane dla jednego źródła (origin), a odczytywane w innym, przez co Authentik za każdym razem traktuje żądanie jako anonimowe. Należy poprawić konfigurację zewnętrznego hosta, a następnie wyczyścić ciasteczka dla obu nazw hostów przed ponownym testem.

Ile pamięci RAM wymaga Authentik?

Zalecane minimum to 2 rdzenie CPU oraz 2 GB pamięci RAM (stan na październik 2026), co obejmuje łącznie PostgreSQL, serwer oraz proces worker. Na maszynie z 2 GB RAM proces worker jest pierwszym, który jądro systemu zamyka w przypadku braku pamięci; objawia się to zatrzymaniem zadań w tle i wysyłki wiadomości e-mail, podczas gdy strona logowania nadal działa. W przypadku, gdy na tym samym serwerze uruchomione są również chronione aplikacje, zaleca się przydzielenie 4 GB pamięci RAM.