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. Najwięcej uwagi wymaga etap późniejszy: skierowanie na niego reverse proxy oraz umieszczenie istniejącej aplikacji za mechanizmem 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.5 jest aktualnym wydaniem na lipiec 2026 roku, a 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

Wymagany jest 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 kontynuowaniem; 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 je nadać 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 powinien zgłaszać healthy, a server oraz worker powinny zgłaszać 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 sztywny 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 zabezpieczyć jego kopię w bezpiecznym miejscu, ponieważ baza danych przywrócona bez pasującego klucza tajnego będzie uniemożliwiać logowanie.

Plik Compose odczytuje obie wartości za pomocą składni ${PG_PASS:?database password required}, co oznacza, że Compose odmawia uruchomienia w przypadku braku pliku. Uruchomienie docker compose up -d z niewłaściwego katalogu spowoduje wyświetlenie required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required i przerwanie działania. 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 konfiguracyjny, 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 publikacji 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 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 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 bezpieczniejszym 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ż skonfigurowane, ten krok zostanie pominięty i nastąpi przekierowanie bezpośrednio do strony logowania.

Utwórz dla siebie zwykłe 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 typu break-glass, używając długiego hasła przechowywanego offline. Codzienna praca na wspólnym wbudowanym koncie niszczy wartość dziennika audytowego, ponieważ każde zdarzenie wskazuje akadmin i nie zawiera informacji o osobie, która je wygenerowała. Dotyczy to również systemów znajdujących się za Authentik: rozwiązanie takie jak samodzielnie hostowany harness OneCLI, który udostępnia każdej osobie własnego agenta zapewnia 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 zaleca się stosowanie TLS (transport layer security) oraz poprawnej nazwy hosta. Jeśli konfiguracja opisana w Traefik jako reverse proxy dla wielu aplikacji Compose jest już aktywna, 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 konfigurację, dzięki czemu usługa server zachowuje wszystkie parametry z oficjalnego pliku i zyskuje dodatkowe etykiety. Sprawdź wynik 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 przekierować ruchu do nieosiągalnego kontenera.

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 ma trzy tryby. Wybranie niewłaściwego może kosztować godzinę pracy. Proxy oznacza, że sam outpost przekazuje ruch do aplikacji upstream. Forward auth (single application) oznacza, że własny reverse proxy nadal przekazuje ruch, a do Authentik wysyłane jest tylko pytanie, czy żądanie pochodzi od uwierzytelnionego użytkownika. Forward auth (domain level) chroni każdą aplikację w ramach jednej domeny nadrzędnej za pomocą jednego dostawcy, ale ogranicza możliwość definiowania reguł autoryzacji osobno dla poszczególnych aplikacji. W przypadku Traefik działającego z przodu należy użyć trybu forward auth (single application). Do ćwiczeń można wybrać konkretną aplikację, na przykład self-hostowany obszar roboczy AFFiNE. Jest to typ wewnętrznego narzędzia, który powinien być dostępny z własnych urządzeń i z żadnych innych. Narzędzie zespołowe jeszcze wyraźniej uzasadnia takie rozwiązanie: można umieścić self-hostowany helpdesk Chatwoot za tym samym dostawcą, aby każda osoba odpowiadająca na wiadomości logowała się raz na dany dzień, zamiast współdzielić kolejne hasło.

W interfejsie WWW należy przejść do sekcji 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, która wskazuje na tego dostawcę. Potem trzeba otworzyć Outposts, edytować authentik Embedded Outpost i przenieść nową aplikację do listy wybranych aplikacji (selected applications). Outpost odpowiada tylko za przypisane mu aplikacje, dlatego pominięcie tego kroku jest najczęstszą przyczyną, dla której 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-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 tego elementu sprawia, że aplikacja jest chroniona, ale nie otrzymuje informacji o użytkowniku, przez co mechanizmy odczytujące X-authentik-username w celu automatycznego logowania nie zadziałają.

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ę wewnątrz /outpost.goauthentik.io/ na nazwie hosta aplikacji, a nie na auth.example.com. Bez routera przekazującego ten prefiks ścieżki do usługi Authentik, żądanie trafia bezpośrednio do aplikacji, która zwraca błąd 404, przez co proces logowania nie zostaje ukoń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 zweryfikować, czy żądanie w ogóle dotarło do Authentik.

Błędy, które wystąpią w praktyce

Niekończąca się pętla przekierowań między aplikacją a stroną logowania. Zewnętrzny host u dostawcy nie zgadza się z tym, którego używa przeglądarka; zazwyczaj jest to http:// u dostawcy w porównaniu z https:// w pasku adresu. Ciasteczko sesyjne jest wtedy ustawiane dla innej domeny, więc każde kolejne żądanie wygląda jak nowe, anonimowe zapytanie. Należy poprawić zewnętrzny host i wyczyścić ciasteczka dla obu domen przed ponownym testowaniem.

Błąd 404 pod /outpost.goauthentik.io/start. Brakuje routera typu outpost lub jego priorytet jest niższy niż routera typu catch-all dla tego 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 ten użytkownik nie spełnia. Dziennik zdarzeń (Events) w interfejsie administratora wskazuje nazwę polityki, która odrzuciła dostęp.

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 istotnym 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

Możliwość przywrócenia systemu zależy od trzech elementów: bazy danych PostgreSQL, katalogu ./data oraz pliku .env.

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

Zrzut bazy danych oraz plik .env należy przechowywać razem. Sam zrzut jest niewystarczający, ponieważ klucz tajny zabezpieczają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ć polecenie docker compose pull, po którym następuje docker compose up -d. Przed aktualizacją należy zapoznać się z informacjami o wydaniu, ponieważ Authentik stosuje wersjonowanie oparte na dacie, a niektóre wydania zawierają migracje wymagające posiadania poprzedniej wersji. Zrzut bazy danych należy wykonać przed pobraniem obrazu, 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 (flows engine). 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 chronionym hoście musi kierować ruch 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 dla innego, 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 testowaniem.

Ile pamięci RAM potrzebuje Authentik?

Zgodnie z dokumentacją, stan na lipiec 2026, wymagane minimum to 2 rdzenie CPU oraz 2 GB pamięci RAM, co obejmuje łącznie PostgreSQL, serwer oraz worker. Na maszynie z 2 GB RAM worker jest pierwszym procesem, który jądro systemu zabija w przypadku braku pamięci; objawia się to zatrzymaniem zadań w tle i wysyłki e-maili, podczas gdy strona logowania nadal działa. Warto zapewnić 4 GB RAM, jeśli na tym samym serwerze uruchomione są również chronione aplikacje.