Authentik: konfiguracja SSO przez Docker Compose

Jeden login do wszystkich hostowanych aplikacji

Authentik to samodzielnie hostowany serwer SSO (single sign-on): użytkownik loguje się raz, a każda aplikacja znajdująca się za nim akceptuje tę sesję zamiast wymagać własnego hasła. Instalacja polega na użyciu oficjalnego pliku Docker Compose i dwóch wygenerowanych sekretów. Najwięcej uwagi wymaga dalsza konfiguracja: wskazanie reverse proxy na Authentik oraz umieszczenie jednej istniejącej aplikacji za forward auth.

Authentik składa się z trzech usług zdefiniowanych w tym pliku Compose: bazy danych PostgreSQL, procesu server oraz procesu worker. Kontener serwera uruchamia również wbudowany outpost. Jest to komponent, który dla każdej chronionej aplikacji odpowiada na pytanie: „czy to żądanie pochodzi od zalogowanego użytkownika?”. Wersja 2026.8.5 jest bieżącym wydaniem na dzień 25 October 2026. Opublikowano ją 21 October 2026 jako najnowszą poprawkę serii 2026.8, rozpoczętej wersją 2026.8.0 z 18 August. Zastępuje ona wersję 2026.8.4 z 14 October jako domyślny tag obrazu w oficjalnym pliku Compose. Projekt wymaga hosta z co najmniej 2 rdzeniami CPU i 2 GB pamięci RAM. Należy traktować to jako minimum. PostgreSQL i worker zajmują pamięć po całym dniu 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 z użyciem 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 powinno wyświetlić trzy kontenery, wszystkie w stanie działania, a postgresql powinno zwracać healthy po pomyślnym przejściu kontroli. Przy pierwszym uruchomieniu wykonywane są migracje bazy danych, dlatego przed próbą otwarcia interfejsu WWW należy odczekać minutę.

Obie wygenerowane wartości są istotne, ale z różnych powodów. PG_PASS to hasło PostgreSQL. Dokumentacja instalacji Authentik podaje, że hasła dłuższe niż 99 znaków nie są obsługiwane, dlatego samodzielnie wybrane hasło powinno być krótsze; wygenerowane hasło jest znacznie krótsze. AUTHENTIK_SECRET_KEY to klucz używany przez Authentik do podpisywania cookies. Dokumentacja konfiguracji informuje, że jego zmiana unieważnia aktywne sesje, więc ustawienie nowego klucza wyloguje każdego zalogowanego użytkownika. Należy zachować .env z trybem 600 oraz przechowywać jego kopię w bezpiecznym miejscu razem z kopiami zapasowymi, aby po odtworzeniu używany był ten sam klucz.

Plik Compose oznacza obie wartości jako wymagane za pomocą składni ${VAR:?message}: ${PG_PASS:?database password required} w usłudze PostgreSQL oraz ${AUTHENTIK_SECRET_KEY:?secret key required} w usługach server i worker. Oznacza to, że Compose odmówi uruchomienia, gdy pliku brakuje. Uruchomienie docker compose up -d z niewłaściwego katalogu wyświetla wiersz taki jak required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required i kończy działanie. Jest to problem ze ścieżką, a nie problem z konfiguracją.

Istotne zmienne środowiskowe

Wszystkie pozostałe parametry umieszcza się w tym samym pliku .env. Authentik mapuje podwójne podkreślenie na zagnieżdżony klucz konfiguracyjny, dlatego AUTHENTIK_EMAIL__HOST ustawia email.host. Pojedyncze podkreślenie nie tworzy mapowania do zagnieżdżonego klucza, co jest 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 publikowane 9000 i 9443.
• 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 powoduje, że wiadomości z resetem hasła kończą się błędem połączenia w dzienniku procesu worker.
• AUTHENTIK_LOG_LEVEL=debug włącza szczegółowe logowanie przydatne podczas 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. Zmień tę wartość na true tylko wtedy, gdy akceptujesz wysył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 początkowy proces konfiguracji i poprosi o ustawienie hasła dla domyślnego użytkownika akadmin. Jeśli AUTHENTIK_BOOTSTRAP_PASSWORD zostało już ustawione, ten etap jest zakończony i nastąpi bezpośrednie przejście do strony logowania.

Utwórz dla siebie zwykłego użytkownika administracyjnego w sekcjach Directory, a następnie Users, dodaj go do grupy authentik Admins i zaloguj się za pomocą tego konta. Konto akadmin pozostaw jako konto awaryjne, z długim hasłem przechowywanym offline. Jeśli uszkodzony flow lub stage zablokuje dostęp, docker compose run --rm server create_recovery_key 10 akadmin uruchomione z /opt/authentik wyświetli link umożliwiający bezpośrednie zalogowanie jako akadmin. Każda osoba posiadająca ten link ma taki sam dostęp, dlatego należy traktować go jak hasło. Codzienna praca na wspólnym wbudowanym koncie niszczy wartość dziennika audytowego, ponieważ każde zdarzenie wskazuje akadmin i nie zawiera informacji o tym, kto faktycznie wykonał operację. Dotyczy to również systemów znajdujących się za Authentik: rozwiązanie takie jak samodzielnie hostowany harness OneCLI, który zapewnia każdej osobie własnego agenta pozostawia czytelny ślad tylko wtedy, gdy docierająca do niego tożsamość należy do jednej osoby, a nie do loginu 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 korzystasz już z konfiguracji opisanej w Traefik jako reverse proxy dla wielu aplikacji Compose, dołącz Authentik do tej samej zewnętrznej sieci proxy za pomocą pliku override. Utwórz 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. Sprawdź wynik poleceniem curl -I https://auth.example.com/if/user/, które powinno zwrócić HTTP/2 200. Kod 404 page not found z Traefik oznacza, że żaden router nie dopasował żądania. Sprawdź, czy etykiety zostały przypisane do kontenera, czy reguła Host() dokładnie odpowiada nazwie hosta oraz czy żądanie dotarło do punktu wejścia HTTPS, na którym nasłuchuje router.

Gdy nazwa hosta zacznie działać, ogranicz powiązanie opublikowanych portów do 127.0.0.1 w pliku override, aby jedyną drogą dostępu był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 migracji opartej na udokumentowanym eksporcie i imporcie realmów. Komercyjne wsparcie jest dla niektórych organizacji istotnym wymogiem formalnym. Ceną za to jest brak wbudowanego proxy w Keycloak, co oznacza, że zabezpieczenie aplikacji nieobsługującej OIDC (OpenID Connect) ani SAML wymaga uruchomienia dodatkowego komponentu, takiego jak oauth2-proxy. Wbudowany dostawca proxy w Authentik stanowi gotowe, zintegrowane rozwiązanie, dlatego większość użytkowników self-hosted z różnorodnym zestawem aplikacji wybiera właśnie ten produkt.

Kopie zapasowe i aktualizacje

Odtworzenie systemu wymaga trzech elementów: bazy danych PostgreSQL, katalogu ./data oraz .env.

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

Ten zrzut i .env należy przechowywać razem. Zrzut nie zawiera kopii AUTHENTIK_SECRET_KEY, a odtworzenie systemu z użyciem innego klucza unieważnia każdą aktywną sesję. Zachowanie oryginalnego klucza sprawia więc, że odtworzony serwer działa tak jak wcześniej.

Aktualizacja polega na zmianie tagu. Ustaw AUTHENTIK_TAG w .env na wybrane wydanie, a następnie uruchom docker compose pull i docker compose up -d. Jeśli AUTHENTIK_TAG nie zostanie ustawione, wersja jest pobierana z wartości domyślnej zapisanej bezpośrednio w compose.yml. W takim przypadku pobranie nowszej kopii tego pliku stanowi aktualizację. Jest to procedura opisana w oficjalnej dokumentacji aktualizacji. Najpierw należy przeczytać informacje o wydaniu. Authentik używa wersji opartych na datach, a według dokumentacji z October 2026 aktualizacje muszą przebiegać w kolejności głównych wydań: najpierw należy przejść do najnowszej poprawki używanej serii, a następnie przechodzić kolejno przez każdą następną serię, bez pomijania żadnej z nich. Authentik nie obsługuje obniżania wersji, dlatego zrzut bazy danych należy wykonać przed pull, a nie po nim.

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. Płatna wersja enterprise dodaje wsparcie techniczne oraz wybrane funkcje korporacyjne, jednak żadne z opisanych tutaj rozwiązań nie wymaga licencji.

Czy do korzystania z Authentik potrzebuję Traefik?

Nie. 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 pyta Authentik o każde żądanie, a prefiks ścieżki /outpost.goauthentik.io/ na chronionej nazwie hosta musi kierować ruch do Authentik zamiast do 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 wystawiane dla jednego źródła, a odczytywane w innym, przez co Authentik za każdym razem traktuje żądanie jako anonimowe. Należy poprawić zewnętrzny host, a następnie wyczyścić ciasteczka dla obu nazw hostów przed ponownym testem.

Ile pamięci RAM potrzebuje Authentik?

Dokumentowane minimum to 2 rdzenie CPU i 2 GB pamięci RAM według stanu na październik 2026, co obejmuje łącznie PostgreSQL, serwer oraz worker. Na maszynie z 2 GB pamięci presja na zasoby może wywołać mechanizm OOM killer jądra systemu, który kończy proces o najwyższym wskaźniku badness: w przybliżeniu jest to udział wykorzystywanej pamięci w stosunku do dostępnej, powiększony o oom_score_adj. Gdy dotyczy to workera, objawem jest zatrzymanie zadań w tle oraz wysyłki poczty, podczas gdy strona logowania nadal działa. Warto przydzielić 4 GB, jeśli na tym samym serwerze uruchomione są również chronione aplikacje.