Authentik Docker Compose로 SSO 구축하기

호스팅하는 모든 앱에 하나의 로그인 사용

Authentik은 자체 호스팅 SSO(single sign-on) 서버입니다. 사용자는 한 번 로그인하면 됩니다. 이후 Authentik 뒤에 있는 모든 앱이 자체 비밀번호를 요구하지 않고 해당 세션을 사용합니다. 설치에는 공식 Docker Compose 파일과 생성된 보안 비밀 2개가 필요합니다. 실제로 고려할 부분은 그 다음입니다. reverse proxy가 Authentik을 가리키도록 설정하고, 기존 앱 하나를 forward auth 뒤에 배치해야 합니다.

Authentik은 해당 Compose 파일에서 PostgreSQL 데이터베이스, server 프로세스, worker 프로세스의 3가지 서비스로 실행됩니다. 서버 컨테이너는 embedded outpost도 실행합니다. embedded outpost는 보호된 각 앱의 요청에 대해 "이 요청이 로그인되어 있는가?"를 확인하는 구성 요소입니다. 2026.5는 2026년 7월 기준 최신 릴리스입니다. 프로젝트에서는 최소 2 CPU 코어와 2 GB RAM이 있는 호스트를 요구합니다. 이 사양을 최소 기준으로 사용합니다. 서버를 하루 동안 실행하면 PostgreSQL과 worker가 모두 메모리를 사용합니다.

시작하기 전에 필요한 항목

docker compose version로 확인할 수 있는 Compose v2 플러그인이 포함된 Docker Engine이 필요합니다. 버전 대신 오류가 출력되면 계속 진행하기 전에 플러그인을 설치합니다. 기본 내용은 VPS에서 Docker Compose로 앱 실행하기에서 확인할 수 있습니다. 또한 서버를 가리키는 DNS A 레코드가 필요합니다. 아래 예시에서는 auth.example.com이 해당 레코드입니다. Authentik은 브라우저가 사용한 호스트 이름을 기준으로 리디렉션 URL을 생성하기 때문입니다.

스택은 root가 아니라 docker 그룹에 속한 일반 사용자로 실행합니다. 이 그룹의 권한은 호스트에서 root 권한과 동일하므로, VPS의 최소 권한 사용자 계정에 설명된 방식으로 배포 계정 하나에만 이 그룹을 부여합니다.

공식 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에는 3개의 컨테이너가 표시되어야 합니다. postgresql에는 healthy 및 server이 보고되고, worker에는 running가 보고되어야 합니다. 최초 시작 시 데이터베이스 마이그레이션이 실행되므로 웹 인터페이스가 응답할 때까지 1분 정도 기다립니다.

생성된 두 값은 서로 다른 이유로 중요합니다. PG_PASS은 PostgreSQL 비밀번호이며, 최대 길이는 99자입니다. AUTHENTIK_SECRET_KEY은 세션과 토큰에 서명하므로 나중에 변경하면 모든 사용자가 로그아웃되고 발급한 모든 API 토큰이 무효화됩니다. .env의 모드를 600으로 유지하고 안전한 곳에 사본을 보관합니다. 일치하는 비밀 키 없이 복원한 데이터베이스에는 아무도 로그인할 수 없기 때문입니다.

Compose 파일은 ${PG_PASS:?database password required} 형식으로 두 값을 읽습니다. 따라서 파일이 없으면 Compose는 시작을 거부합니다. 잘못된 디렉터리에서 docker compose up -d을 실행하면 required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required이 출력되고 중지됩니다. 이 메시지는 설정 문제가 아니라 경로 문제를 나타냅니다.

중요한 환경 변수

나머지 내용은 동일한 .env 파일에 추가합니다. Authentik은 이중 밑줄을 중첩된 구성 키로 매핑하므로, AUTHENTIK_EMAIL__HOST은 email.host를 설정합니다. 단일 밑줄은 경고 없이 무시됩니다. 설정이 아무 효과가 없는 것처럼 보이는 가장 일반적인 원인입니다.

• AUTHENTIK_BOOTSTRAP_PASSWORD는 처음 시작할 때 기본 제공되는 akadmin 사용자의 비밀번호를 설정하므로, 공개 웹 양식에 비밀번호를 입력할 필요가 없습니다. AUTHENTIK_BOOTSTRAP_EMAIL과 AUTHENTIK_BOOTSTRAP_TOKEN도 같은 방식으로 해당 사용자의 주소와 API 토큰을 설정합니다.
• COMPOSE_PORT_HTTP와 COMPOSE_PORT_HTTPS은 공개 포트를 기본값인 9000 및 9443에서 변경합니다.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS 및 AUTHENTIK_EMAIL__FROM은 발신 메일을 구성합니다. 이 값이 없으면 Authentik은 포트 25에서 localhost을 시도합니다. 그러면 비밀번호 재설정 메일 전송이 worker 로그에서 연결 오류로 끝납니다.
• AUTHENTIK_LOG_LEVEL=debug은 로그인 flow가 제대로 작동하지 않을 때 필요한 상세 정보를 활성화합니다. 이후에는 info로 되돌립니다.
• AUTHENTIK_ERROR_REPORTING__ENABLED의 기본값은 false입니다. crash report를 upstream으로 전송해도 괜찮은 경우에만 true로 설정합니다.

이 값은 일반 파일에 저장되는 비밀 정보입니다. 따라서 이 디렉터리를 다른 자격 증명 저장소와 동일하게 보호해야 합니다. 노트북의 메모보다 self-hosted Vaultwarden 인스턴스와 같은 password manager가 복구용 사본을 보관하기에 더 적합합니다.

최초 로그인 및 관리자 계정

브라우저에서 http://SERVER_IP:9000을 엽니다. Authentik에 초기 설정 화면이 표시되고 기본 akadmin 사용자의 비밀번호를 설정하라는 메시지가 나타납니다. 이미 AUTHENTIK_BOOTSTRAP_PASSWORD을 설정했다면 이 단계는 완료된 것이므로 바로 로그인 페이지로 이동합니다.

Directory에서 Users로 이동하여 본인이 사용할 일반 관리자 사용자를 만든 다음, 해당 사용자를 authentik Admins 그룹에 추가하고 이 계정으로 로그인합니다. akadmin은 오프라인에 보관한 긴 비밀번호를 사용하는 비상 계정으로 유지합니다. 기본 제공 공유 계정으로 일상적인 작업을 수행하면 모든 이벤트에 akadmin만 표시되고 작업자가 누구인지는 표시되지 않으므로 감사 로그가 무용지물이 됩니다.

reverse proxy 뒤에 Authentik 배치

port 9000을 인터넷에 공개할 수 있지만, TLS(transport layer security)와 실제 hostname을 사용해야 합니다. 여러 Compose 앱의 reverse proxy로서 Traefik 설정을 이미 실행 중이라면 override file을 사용하여 Authentik을 동일한 external proxy network에 연결합니다. compose.yml 옆에 docker-compose.override.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

docker compose up -d로 적용합니다. Compose는 override를 자동으로 병합하므로 server service는 공식 file의 모든 설정을 유지하면서 label을 추가로 얻습니다. curl -I https://auth.example.com/if/user/로 확인합니다. 이 명령은 HTTP/2 200에 응답해야 합니다. Traefik에서 404 page not found이 반환되면 container가 proxy network에 연결되지 않은 것입니다. Traefik은 연결할 수 없는 container로 traffic을 전달할 수 없습니다.

hostname이 작동하면 override에서 공개된 port를 127.0.0.1에 bind합니다. 그러면 proxy를 통해서만 접근할 수 있습니다.

하나의 앱을 forward auth로 보호

Authentik의 proxy provider에는 3가지 모드가 있으며, 잘못 선택하면 1시간을 허비할 수 있습니다. Proxy는 outpost 자체가 트래픽을 upstream 앱으로 전달한다는 의미입니다. Forward auth (single application)은 자체 reverse proxy가 트래픽을 계속 전달하고, 요청이 로그인되어 있는지만 Authentik에 확인한다는 의미입니다. Forward auth (domain level)은 하나의 provider로 동일한 상위 도메인 아래의 모든 앱을 보호하지만, 애플리케이션별 권한 부여 규칙을 설정할 수 없다는 비용이 있습니다. 앞에 Traefik을 배치하는 경우에는 forward auth (single application)을 사용해야 합니다.

웹 인터페이스에서 Applications를 연 다음 Providers를 열고, Proxy Provider를 생성합니다. forward auth single application 모드를 선택하고 외부 호스트를 https://app.example.com로 설정합니다. 해당 provider를 가리키는 Application을 생성합니다. 그런 다음 Outposts를 열고 authentik Embedded Outpost을 편집한 뒤, 새 애플리케이션을 selected applications에 추가합니다. outpost는 할당된 애플리케이션에 대해서만 응답하므로, 이 마지막 단계를 건너뛰면 provider가 올바르게 구성되어도 응답하지 않는 원인이 됩니다.

Authentik container에서 middleware를 한 번만 정의하고, 보호할 모든 앱에서 이를 참조합니다.

      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은 Traefik이 Authentik의 응답에서 가져와 upstream으로 보내는 요청에 복사하는 header 목록입니다. 이를 생략하면 앱 자체는 보호되지만 사용자를 식별할 수 없습니다. 따라서 자동 로그인을 위해 X-authentik-username를 읽는 기능은 계속 로그아웃된 상태로 남습니다.

보호할 앱 자체에는 router가 하나가 아니라 2개 필요합니다.

    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

두 번째 router가 빠지는 경우가 많습니다. 로그인 후 Authentik은 브라우저를 auth.example.com가 아니라 앱의 호스트 이름에 있는 /outpost.goauthentik.io/ 아래 경로로 돌려보냅니다. 해당 경로 prefix를 Authentik service로 전달하는 router가 없으면 요청이 앱에 도착하고, 앱은 404를 반환하므로 로그인이 완료되지 않습니다. 더 높은 priority가 있어야 동일한 도메인에서 일반적인 Host() 규칙보다 구체적인 경로 규칙이 우선 적용됩니다.

private browser window에서 테스트합니다. auth.example.com로 이동되고 로그인한 다음 앱으로 돌아와야 합니다. Authentik 측의 docker compose logs -f server은 시도마다 authorization event를 출력하므로 요청이 Authentik에 도달했는지 확인할 수 있습니다.

실제로 발생하는 오류

앱과 로그인 페이지 사이에서 리디렉션이 무한 반복됩니다. 제공업체에 설정된 외부 호스트가 브라우저가 사용하는 호스트와 일치하지 않습니다. 일반적으로 제공업체에는 http://가 설정되어 있지만 주소 표시줄에는 https://이 표시됩니다. 그러면 세션 쿠키가 다른 origin에 설정되므로, 돌아올 때마다 새로운 익명 요청으로 처리됩니다. 다시 테스트하기 전에 외부 호스트를 수정하고 두 도메인의 쿠키를 삭제합니다.

/outpost.goauthentik.io/start에서 404가 발생합니다. outpost router가 없거나, 해당 호스트의 catch-all router보다 우선순위가 낮습니다.

로그인을 요청하지 않고 앱이 로드됩니다. middlewares 레이블이 존재하지 않는 middleware를 가리킵니다. Traefik은 이 경우 경고를 표시하지 않습니다. 따라서 authentik@docker의 오타가 있으면 middleware가 실행되지 않습니다. Traefik 대시보드를 열고 router에 해당 middleware가 나열되어 있는지 확인합니다.

로그인에 성공한 후 Authentik에서 403이 발생합니다. 사용자는 인증되었지만 권한이 없습니다. 애플리케이션에 이 사용자가 충족하지 못하는 policy binding 또는 group requirement가 설정되어 있습니다. 관리자 인터페이스의 Events 로그에서 액세스를 거부한 policy를 확인할 수 있습니다.

Keycloak이 더 적합한 경우

Keycloak은 Red Hat이 지원하는 오래된 프로젝트입니다. 클래식한 엔터프라이즈 ID 관리 작업에는 더 강력한 선택입니다. 주요 예로는 대규모 SAML 페더레이션, 여러 외부 ID 공급자의 로그인을 동시에 중개하는 작업, 문서화된 마이그레이션 경로로서 realm을 내보내고 가져오는 작업이 있습니다. 일부 조직에서는 상용 지원이 제공된다는 점도 중요하게 고려합니다. 대신 Keycloak에는 자체 proxy가 없습니다. 따라서 OIDC (OpenID Connect)를 사용하지 않는 애플리케이션을 보호하려면 oauth2-proxy 같은 도구를 함께 실행해야 합니다. Authentik의 내장 proxy provider는 이 기능을 이미 통합해 제공합니다. 따라서 여러 유형의 애플리케이션을 함께 운영하는 대부분의 self-hosting 사용자는 Authentik을 선택합니다.

백업 및 업그레이드

복원하려면 3가지가 필요합니다. PostgreSQL 데이터베이스, ./data 디렉터리, .env입니다.

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

해당 덤프와 .env를 함께 보관합니다. 세션 및 토큰 데이터를 보호하는 비밀 키가 .env에 있으므로 덤프만으로는 충분하지 않습니다.

업그레이드는 태그를 변경하는 작업입니다. .env에서 AUTHENTIK_TAG을 원하는 릴리스로 설정한 다음 docker compose pull을 실행하고 docker compose up -d을 실행합니다. 먼저 릴리스 노트를 읽습니다. Authentik은 날짜 기반 버전을 사용하며 일부 릴리스에는 이전 릴리스에서 순차적으로 업그레이드할 것을 전제로 하는 마이그레이션이 포함되어 있습니다. 데이터베이스 덤프는 pull 이후가 아니라 pull 이전에 생성합니다.

FAQ

Authentik을 자체 호스팅하면 무료입니까?

오픈 소스 에디션은 무료이며, 앞에서 설명한 프록시 공급자, forward auth, OIDC (OpenID Connect), SAML 및 flows engine을 모두 제공합니다. 유료 엔터프라이즈 계층에서는 지원과 일부 엔터프라이즈 기능을 추가로 제공하지만, 여기서 설명한 기능에는 라이선스가 필요하지 않습니다.

Authentik을 사용하려면 Traefik이 필요합니까?

아니요. auth_request를 사용하면 nginx에서 forward auth를 사용할 수 있고, forward_auth를 사용하면 Caddy에서도 사용할 수 있습니다. 모든 경우의 패턴은 같습니다. reverse proxy가 각 요청에 대해 Authentik에 확인을 요청하고, 보호된 호스트 이름의 경로 접두사 /outpost.goauthentik.io/가 앱이 아니라 Authentik으로 라우팅되어야 합니다.

보호된 앱이 로그인과 오류 화면 사이를 계속 반복해서 전환하는 이유는 무엇입니까?

프록시 공급자에 구성한 외부 호스트가 브라우저에서 사용하는 URL과 일치하지 않습니다. 가장 흔한 경우는 http와 https가 서로 다른 경우입니다. 세션 쿠키가 한 origin에 대해 발급되고 다른 origin에서 읽히므로 Authentik은 매번 익명 요청으로 인식합니다. 외부 호스트를 수정한 다음, 다시 테스트하기 전에 두 호스트 이름의 쿠키를 삭제합니다.

Authentik에는 RAM이 얼마나 필요합니까?

2026년 7월 기준으로 문서에 명시된 최소 요구 사항은 CPU 코어 2개와 RAM 2 GB입니다. 이 요구 사항은 PostgreSQL, server 및 worker를 함께 실행하는 경우를 기준으로 합니다. 2 GB 서버에서는 메모리 압박이 발생할 때 커널이 가장 먼저 종료하는 프로세스가 worker입니다. 이때 로그인 페이지는 계속 작동하지만 백그라운드 작업과 발신 이메일이 중지됩니다. 같은 서버에서 보호하는 앱도 실행한다면 4 GB를 할당합니다.