Authentik: self-hosted SSO dla aplikacji

Jeden login do każdej hostowanej aplikacji

Authentik to hostowany samodzielnie serwer SSO (single sign-on): użytkownicy logują się raz, a każda aplikacja za nim akceptuje tę sesję, zamiast żądać własnego hasła. Instalacja korzysta z oficjalnego pliku Docker Compose i dwóch wygenerowanych wpisów tajnych. Najwięcej uwagi wymaga dalsza konfiguracja: skierowanie do niego reverse proxy oraz umieszczenie jednej istniejącej aplikacji za mechanizmem forward auth.

Authentik jest dostarczany w tym pliku Compose jako trzy usługi: baza danych PostgreSQL, proces server oraz proces worker. Kontener serwera uruchamia również wbudowany outpost. Jest to komponent, który dla każdej chronionej aplikacji sprawdza, czy żądanie pochodzi od zalogowanego użytkownika. Wersja 2026.5 jest bieżącym wydaniem w lipcu 2026, a projekt wymaga hosta z co najmniej 2 rdzeniami CPU i 2 GB pamięci RAM. Należy traktować te wartości jako minimum. Po całym dniu pracy PostgreSQL i worker nadal zajmują pamięć.

Wymagania wstępne

Wymagany jest Docker Engine z wtyczką Compose v2. Można to potwierdzić za pomocą docker compose version. Jeśli zostanie wyświetlony błąd zamiast wersji, przed kontynuowaniem należy zainstalować wtyczkę. Podstawowe informacje opisano w uruchamianiu aplikacji za pomocą Docker Compose na VPS. Wymagany jest również rekord DNS A wskazujący serwer, czyli auth.example.com w poniższych przykładach, ponieważ Authentik tworzy 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ównoznaczne z uprawnieniami root na hoście. Dlatego należy przyznać je jednemu kontu wdrożeniowemu i nikomu więcej, zgodnie z zasadami opisanymi w kontach 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 powinno wyświetlać trzy kontenery. postgresql powinno zgłaszać healthy, a server powinno zgłaszać worker i running. Przy pierwszym uruchomieniu wykonywane są migracje bazy danych. Przed sprawdzeniem, czy interfejs WWW odpowiada, należy odczekać minutę.

Obie wygenerowane wartości mają znaczenie, ale z różnych powodów. PG_PASS to hasło PostgreSQL. Jego długość nie może przekraczać 99 znaków. AUTHENTIK_SECRET_KEY służy do podpisywania sesji i tokenów. Późniejsza zmiana tej wartości wyloguje wszystkich użytkowników i unieważni wszystkie wydane tokeny API. Plik .env należy zachować z uprawnieniami 600 oraz przechowywać jego kopię w bezpiecznym miejscu. Baza danych odtworzona bez odpowiadającego jej klucza tajnego nie pozwoli na zalogowanie.

Plik Compose odczytuje obie wartości za pomocą składni ${PG_PASS:?database password required}. Oznacza to, że Compose odmawia uruchomienia, gdy brakuje tego pliku. Uruchomienie docker compose up -d z niewłaściwego katalogu wyświetla required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required i kończy działanie. Ten komunikat wskazuje na problem ze ścieżką, a nie z konfiguracją.

Istotne wartości środowiskowe

Wszystkie pozostałe wartości należy umieścić w tym samym pliku .env. Authentik mapuje podwójne podkreślenie na zagnieżdżony klucz konfiguracji, dlatego AUTHENTIK_EMAIL__HOST ustawia email.host. Pojedyncze podkreślenie jest ignorowane bez ostrzeżenia. Jest to najczęstszy powód, dla którego ustawienie nie przynosi widocznego efektu.

• AUTHENTIK_BOOTSTRAP_PASSWORD ustawia przy pierwszym uruchomieniu hasło wbudowanego użytkownika akadmin, dzięki czemu nie trzeba wpisywać go w publicznym formularzu internetowym. AUTHENTIK_BOOTSTRAP_EMAIL i AUTHENTIK_BOOTSTRAP_TOKEN w ten sam sposób ustawiają adres tego użytkownika oraz token API.
• COMPOSE_PORT_HTTP i COMPOSE_PORT_HTTPS zmieniają opublikowane porty z wartości domyślnych 9000 i 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS i AUTHENTIK_EMAIL__FROM konfigurują pocztę wychodzącą. Bez tych wartości Authentik próbuje użyć localhost na porcie 25, dlatego wiadomości służące do resetowania hasła kończą się błędem połączenia w logu workera.
• AUTHENTIK_LOG_LEVEL=debug włącza szczegółowe informacje potrzebne podczas diagnozowania nieprawidłowego działania flow logowania. Po zakończeniu diagnostyki należy przywrócić wartość info.
• AUTHENTIK_ERROR_REPORTING__ENABLED ma domyślnie wartość false. Wartość true należy ustawić tylko wtedy, gdy akceptowane jest wysyłanie raportów o awariach do dostawcy.

Są to sekrety zapisane w zwykłym pliku, dlatego katalog należy traktować tak samo jak każdy inny magazyn danych uwierzytelniających. Menedżer haseł, taki jak samodzielnie hostowana instancja Vaultwarden, jest lepszym miejscem na kopię odzyskiwania 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 sekcji Directory, a następnie Users, dodaj go do grupy authentik Admins i zaloguj się przy użyciu tego konta. Pozostaw akadmin jako konto awaryjne, używając długiego hasła przechowywanego offline. Codzienna praca przy użyciu wspólnego wbudowanego konta niszczy wartość dziennika audytowego, ponieważ każde zdarzenie wskazuje akadmin i nie pozwala ustalić, kto je wykonał.

Umieść Authentik za odwrotnym proxy

Publikowanie portu 9000 w internecie działa, ale wymagane są TLS (Transport Layer Security) i właściwa nazwa hosta. Jeśli jest już używana konfiguracja z sekcji Traefik jako odwrotne proxy dla wielu aplikacji Compose, należy dołączyć Authentik do tej samej zewnętrznej sieci proxy za pomocą pliku nadpisującego. 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 konfigurację za pomocą docker compose up -d. Compose automatycznie scala plik nadpisujący, dlatego usługa server zachowuje wszystkie ustawienia z oficjalnego pliku i otrzymuje dodatkowo etykiety. Sprawdź konfigurację za pomocą curl -I https://auth.example.com/if/user/. Powinno ono zwrócić HTTP/2 200. Błąd 404 page not found z Traefik oznacza, że kontener nie jest podłączony do sieci proxy. Traefik nie może kierować ruchu do kontenera, do którego nie ma dostępu.

Po uruchomieniu nazwy hosta przypisz opublikowane porty do 127.0.0.1 w pliku nadpisującym. Wtedy jedyną drogą dostępu będzie proxy.

Ochrona jednej aplikacji za pomocą forward auth

Provider proxy w Authentik ma trzy tryby. Wybór niewłaściwego trybu może kosztować godzinę pracy. Tryb Proxy oznacza, że outpost sam przekazuje ruch do aplikacji upstream. Tryb Forward auth (single application) oznacza, że własny reverse proxy nadal przekazuje ruch, a Authentik tylko sprawdza, czy użytkownik jest uwierzytelniony. Tryb Forward auth (domain level) chroni wszystkie aplikacje w ramach jednej domeny nadrzędnej za pomocą jednego providera, ale wymaga reguł autoryzacji dla poszczególnych aplikacji. W przypadku Traefik umieszczonego z przodu należy użyć trybu forward auth (single application).

W interfejsie webowym otwórz Applications, a następnie Providers, utwórz Proxy Provider, wybierz tryb forward auth single application i ustaw host zewnętrzny na https://app.example.com. Utwórz Application wskazującą ten provider. Następnie otwórz Outposts, edytuj authentik Embedded Outpost i przenieś nową aplikację do listy wybranych aplikacji. Outpost odpowiada tylko za aplikacje, które zostały mu przypisane. Pominięcie ostatniego kroku powoduje, że poprawnie skonfigurowany provider nadal nie zwraca odpowiedzi.

Zdefiniuj middleware jeden raz, na kontenerze Authentik, i odwołuj się do niego ze wszystkich chronionych 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 upstream. Po pominięciu tej listy aplikacja nadal jest chroniona, ale nie otrzymuje informacji o użytkowniku. W rezultacie funkcje odczytujące X-authentik-username w celu automatycznego logowania pozostają niezalogowane.

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, który często zostaje pominięty. Po zalogowaniu Authentik przekierowuje przeglądarkę na ścieżkę w ramach /outpost.goauthentik.io/ w hoście aplikacji, a nie w ramach auth.example.com. Bez routera przekazującego ten prefiks ścieżki do usługi Authentik żądanie trafia do aplikacji. Aplikacja zwraca kod 404, a logowanie nie zostaje zakończone. Wyższa wartość priority powoduje, że reguła dla konkretnej ścieżki ma pierwszeństwo przed zwykłą regułą Host() w tej samej domenie.

Przetestuj konfigurację w prywatnym oknie przeglądarki. Nastąpi przekierowanie do auth.example.com, następnie należy się zalogować i wrócić do aplikacji. docker compose logs -f server po stronie Authentik zapisuje zdarzenie autoryzacji dla każdej próby. Pozwala to sprawdzić, czy żądanie w ogóle dotarło do Authentik.

Awarie, które rzeczywiście wystąpią

Niekończąca się pętla przekierowań między aplikacją a stroną logowania. Zewnętrzny host skonfigurowany u dostawcy nie jest zgodny z hostem używanym przez przeglądarkę, zwykle http:// u dostawcy w porównaniu z https:// na pasku adresu. Plik cookie sesji jest wtedy ustawiany dla innego źródła, dlatego każde kolejne żądanie jest traktowane jako nowe żądanie anonimowe. Należy poprawić zewnętrzny host i przed ponownym testem usunąć pliki cookie dla obu domen.

Błąd 404 pod adresem /outpost.goauthentik.io/start. Brakuje routera outpost albo ma on niższy priorytet niż router typu catch-all dla tego hosta.

Aplikacja ładuje się bez wyświetlenia żądania logowania. Etykieta middlewares wskazuje middleware, który nie istnieje. Traefik nie wyświetla w takim przypadku ostrzeżenia, dlatego literówka w authentik@docker oznacza po prostu, że żaden middleware nie zostanie uruchomiony. Należy otworzyć panel Traefik i sprawdzić, czy router ma przypisany middleware.

Błąd 403 z Authentik po pomyślnym zalogowaniu. Użytkownik został uwierzytelniony, ale nie ma uprawnień: do aplikacji przypisano politykę albo wymaganie dotyczące grupy, którego użytkownik nie spełnia. Dziennik Events w interfejsie administracyjnym wskazuje politykę, która odrzuciła żądanie.

Kiedy Keycloak jest lepszym wyborem

Keycloak to starszy projekt wspierany przez Red Hat. Jest lepszym wyborem do klasycznych zastosowań związanych z tożsamością w przedsiębiorstwach: rozbudowanej federacji SAML, pośredniczenia w logowaniu z użyciem kilku zewnętrznych dostawców tożsamości jednocześnie oraz eksportu i importu realmów jako udokumentowanej ścieżki migracji. Dla niektórych organizacji znaczenie ma również dostępne dla tego rozwiązania wsparcie komercyjne. Kompromis polega na tym, że Keycloak nie ma własnego proxy. Ochrona aplikacji, która nie obsługuje OIDC (OpenID Connect), wymaga więc uruchomienia obok niego narzędzia takiego jak oauth2-proxy. Wbudowany provider proxy w Authentik zapewnia tę funkcję i jest już zintegrowany. Z tego powodu większość osób samodzielnie utrzymujących różnorodny zestaw aplikacji wybiera właśnie to rozwiązanie.

Kopie zapasowe i aktualizacje

Przywrócenie jest możliwe dzięki 3 elementom: bazie danych PostgreSQL, katalogowi ./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 razem z .env. Sam zrzut nie wystarcza, ponieważ klucz tajny chroniący dane sesji i tokenów znajduje się w .env.

Aktualizacja polega na zmianie tagu. Należy ustawić AUTHENTIK_TAG w .env na wersję, która ma zostać użyta, a następnie uruchomić docker compose pull, po czym docker compose up -d. Najpierw należy zapoznać się z informacjami o wydaniu, ponieważ Authentik używa wersji opartych na dacie, a niektóre wydania zawierają migracje wymagające przejścia z poprzedniej wersji. Zrzut bazy danych należy utworzyć przed wykonaniem pull, a nie po nim.

FAQ

Czy Authentik jest bezpłatny do samodzielnego hostowania?

Wydanie open source jest bezpłatne i obejmuje wszystkie opisane wcześniej funkcje: dostawcę proxy, forward auth, OIDC (OpenID Connect), SAML oraz silnik przepływów. Płatny poziom enterprise zapewnia dodatkowo wsparcie i niektóre funkcje klasy enterprise, ale do opisanej konfiguracji licencja nie jest potrzebna.

Czy do korzystania z Authentik potrzebny jest Traefik?

Nie. Forward auth działa z nginx za pośrednictwem auth_request oraz z Caddy za pośrednictwem forward_auth. Schemat jest zawsze taki sam: reverse proxy pyta Authentik o każde żądanie, a prefiks ścieżki /outpost.goauthentik.io/ w chronionej nazwie hosta musi kierować do Authentik, a nie do aplikacji.

Dlaczego chroniona aplikacja bez końca przełącza się między logowaniem a błędem?

Zewnętrzny host skonfigurowany u dostawcy proxy nie jest zgodny z adresem URL używanym przez przeglądarkę, najczęściej w przypadku http i https. Plik cookie sesji jest wystawiany dla jednego źródła, a odczytywany z innego, dlatego Authentik za każdym razem otrzymuje żądanie anonimowe. Należy poprawić zewnętrzny host, a następnie przed ponownym testem usunąć pliki cookie dla obu nazw hostów.

Ile pamięci RAM potrzebuje Authentik?

Według dokumentacji minimalne wymagania na lipiec 2026 to 2 rdzenie CPU i 2 GB pamięci RAM. Wartości te obejmują łącznie PostgreSQL, server i worker. Na serwerze z 2 GB pamięci worker jest pierwszym procesem zabijanym przez kernel w warunkach presji pamięci. Objawem jest zatrzymanie zadań w tle i poczty wychodzącej, podczas gdy strona logowania nadal działa. Jeśli ten sam serwer uruchamia również chronione aplikacje, należy przydzielić 4 GB pamięci RAM.