Authentik 설치 및 Docker Compose SSO 설정 가이드

호스팅하는 모든 애플리케이션을 위한 단일 로그인

Authentik은 자체 호스팅 SSO(Single Sign-On) 서버입니다. 사용자가 한 번 로그인하면, 그 뒤에 있는 모든 애플리케이션은 별도의 비밀번호를 요구하는 대신 해당 세션을 수락합니다. 설치는 공식 Docker Compose 파일과 두 개의 생성된 비밀값(secret)을 사용합니다. 진정한 고민이 필요한 부분은 그 이후입니다. 리버스 프록시를 Authentik에 연결하고, 기존 애플리케이션 하나를 forward auth 뒤에 배치하는 과정입니다.

Authentik은 해당 Compose 파일 내에서 PostgreSQL 데이터베이스, server 프로세스, worker 프로세스라는 세 가지 서비스로 제공됩니다. 서버 컨테이너는 내장 아웃포스트(outpost)도 실행하는데, 이는 보호되는 모든 애플리케이션에 대해 "이 요청이 로그인된 상태인가?"라는 질문에 답하는 구성 요소입니다. 2026년 7월 기준 최신 릴리스는 버전 2026.5이며, 프로젝트에서는 최소 2개의 CPU 코어와 2 GB의 RAM을 갖춘 호스트를 권장합니다. 이를 최소 사양으로 간주하십시오. 서버가 하루 이상 가동되면 PostgreSQL과 워커 프로세스 모두 메모리를 점유하게 됩니다.

시작하기 전에 필요한 것

Docker Engine과 Compose v2 플러그인이 필요하며, docker compose version 명령어로 설치 여부를 확인할 수 있습니다. 만약 버전 정보 대신 오류가 출력된다면, 다음 단계로 넘어가기 전에 플러그인을 먼저 설치하십시오. 기본 사항은 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을 시도하므로, 비밀번호 재설정 메일이 워커 로그에 연결 오류로 기록됩니다.
• AUTHENTIK_LOG_LEVEL=debug은 로그인 흐름에 문제가 있을 때 필요한 상세 정보를 출력합니다. 작업이 끝나면 다시 info로 되돌려 놓으십시오.
• AUTHENTIK_ERROR_REPORTING__ENABLED은 기본값이 false입니다. 충돌 보고서를 업스트림으로 전송해도 괜찮은 경우에만 true로 설정하십시오.

이 파일에는 비밀 정보가 포함되어 있으므로, 다른 자격 증명 저장소와 동일하게 디렉터리를 관리해야 합니다. 복구용 사본은 노트북의 메모장보다는 자체 호스팅한 Vaultwarden 인스턴스와 같은 비밀번호 관리자에 보관하는 것이 더 안전합니다.

최초 로그인 및 관리자 계정

브라우저에서 http://SERVER_IP:9000을(를) 엽니다. Authentik은 초기 설정 흐름을 표시하며 기본 akadmin 사용자의 비밀번호를 설정하도록 요청합니다. 이미 AUTHENTIK_BOOTSTRAP_PASSWORD을(를) 설정했다면 해당 단계는 완료된 것이며 바로 로그인 페이지로 이동합니다.

Directory에서 Users로 이동해 일반 관리자 사용자를 생성한 다음 authentik Admins 그룹에 추가하고 해당 계정으로 로그인합니다. akadmin은 오프라인에 긴 비밀번호를 보관하는 break-glass 계정으로 남겨 둡니다. 공유 기본 제공 계정으로 일상적인 작업을 수행하면 모든 이벤트에 akadmin만 기록되고 실제 사용자가 기록되지 않으므로 감사 로그가 무용지물이 됩니다. 이 원칙은 Authentik 이후의 단계에도 적용됩니다. 예를 들어 각 사용자에게 고유한 에이전트를 제공하는 자체 호스팅 OneCLI 하네스도 전달되는 ID가 팀 전체가 공유하는 로그인 계정이 아니라 한 사람에게 속한 경우에만 읽을 수 있는 추적 기록을 남깁니다.

Authentik을 리버스 프록시 뒤에 배치하기

포트 9000을 인터넷에 직접 노출해도 동작은 하지만, TLS(Transport Layer Security)와 실제 호스트 이름이 필요합니다. 이미 여러 Compose 앱을 위한 리버스 프록시로서의 Traefik 설정을 운영 중이라면, override 파일을 사용하여 Authentik을 동일한 외부 proxy 네트워크에 연결하십시오. 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 서비스는 공식 파일의 모든 설정을 유지하면서 라벨을 추가로 갖게 됩니다. curl -I https://auth.example.com/if/user/로 확인하면 HTTP/2 200라는 응답이 나와야 합니다. Traefik에서 404 page not found 오류가 발생한다면 컨테이너가 proxy 네트워크에 연결되지 않았음을 의미하며, 이 경우 Traefik은 도달할 수 없는 컨테이너로 라우팅할 수 없습니다.

호스트 이름이 정상적으로 작동하면, override 파일에서 게시된 포트를 127.0.0.1에 바인딩하여 프록시를 통해서만 접근할 수 있도록 제한하십시오.

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)을 사용해야 한다. 연습할 구체적인 애플리케이션이 필요하다면 self-hosted AFFiNE workspace 같은 대상이 좋은 첫 후보다. 자체 장치에서는 접근할 수 있어야 하지만 다른 곳에서는 접근할 수 없어야 하는 내부 도구이기 때문이다. 팀 도구라면 이 구성이 더욱 적합하다. self-hosted Chatwoot support desk를 동일한 provider 뒤에 배치하면 받은 편지함에 답하는 모든 사용자가 하루에 한 번만 로그인하면 된다. 별도의 비밀번호를 하나 더 공유할 필요도 없다.

웹 인터페이스에서 Applications와 Providers를 차례로 열고, Proxy Provider를 생성한 뒤 Forward auth (single application) 모드를 선택하십시오. 그리고 외부 호스트를 https://app.example.com로 설정합니다. 해당 제공자를 가리키는 Application을 생성하십시오. 그 후 Outposts를 열어 authentik Embedded Outpost을 편집하고, 새로 만든 애플리케이션을 선택된 애플리케이션 목록에 추가하십시오. 아웃포스트는 할당된 애플리케이션에 대해서만 응답하므로, 마지막 단계를 생략하면 제공자를 올바르게 설정했더라도 아무런 응답을 받을 수 없습니다.

미들웨어를 Authentik 컨테이너에 한 번 정의하고, 보호하려는 모든 애플리케이션에서 이를 참조하십시오:

      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의 응답에서 복사하여 업스트림으로 보내는 요청 헤더 목록입니다. 이를 생략하면 애플리케이션은 보호되지만 사용자 정보를 알 수 없게 됩니다. 따라서 자동 로그인을 위해 X-authentik-username를 읽는 모든 기능이 로그아웃 상태로 유지됩니다.

보호 대상 애플리케이션에는 라우터가 하나가 아닌 두 개 필요합니다:

    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

두 번째 라우터는 많은 사용자가 놓치는 부분입니다. 로그인 후 Authentik은 브라우저를 auth.example.com가 아닌 애플리케이션 호스트네임의 /outpost.goauthentik.io/ 하위 경로로 다시 보냅니다. 해당 경로 접두사를 Authentik 서비스로 보내는 라우터가 없으면 요청이 애플리케이션에 도달하여 404 오류를 반환하고, 로그인 과정이 완료되지 않습니다. 더 높은 priority 설정은 동일한 도메인에서 일반 Host() 규칙보다 특정 경로 규칙이 우선하도록 만듭니다.

개인 정보 보호 브라우저 창에서 테스트하십시오. auth.example.com로 리다이렉트되어 로그인한 뒤, 다시 애플리케이션으로 돌아와야 합니다. Authentik 측의 docker compose logs -f server에는 시도할 때마다 인증 이벤트가 기록되므로, 요청이 Authentik에 도달했는지 확인할 수 있습니다.

실제로 마주하게 될 오류들

애플리케이션과 로그인 페이지 간의 무한 리다이렉트 루프. 제공자(provider)에 설정된 외부 호스트가 브라우저가 사용하는 주소와 일치하지 않는 경우입니다. 보통 제공자의 http://와 주소창의 https://이 서로 다를 때 발생합니다. 이 경우 세션 쿠키가 다른 오리진(origin)으로 설정되므로, 매번 요청이 새로 들어온 익명 사용자의 요청처럼 처리됩니다. 외부 호스트 설정을 수정하고 두 도메인의 쿠키를 모두 삭제한 뒤 다시 테스트하십시오.

/outpost.goauthentik.io/start에서 404 오류 발생. 아웃포스트(outpost) 라우터가 없거나, 해당 호스트에 대한 포괄적(catch-all) 라우터보다 우선순위가 낮을 때 발생합니다.

로그인 절차 없이 애플리케이션이 로드됨. middlewares 레이블이 존재하지 않는 미들웨어를 가리키고 있습니다. Traefik은 이에 대해 경고하지 않으므로, authentik@docker에 오타가 있으면 미들웨어가 전혀 실행되지 않습니다. Traefik 대시보드를 열어 라우터에 해당 미들웨어가 나열되어 있는지 확인하십시오.

성공적으로 로그인했으나 Authentik에서 403 오류 반환. 사용자는 인증되었으나 권한이 없는 상태입니다. 애플리케이션에 정책 바인딩이나 그룹 요구 사항이 설정되어 있는데, 현재 사용자가 이를 충족하지 못하는 경우입니다. 관리자 인터페이스의 Events 로그를 확인하면 접근을 거부한 정책의 이름을 알 수 있습니다.

Keycloak이 더 적합한 경우

Keycloak은 Red Hat이 지원하는 더 오래된 프로젝트이며, 전통적인 엔터프라이즈 ID 관리 작업에 더 강력한 선택지입니다. 복잡한 SAML 페더레이션, 여러 외부 ID 공급자로부터의 로그인 브로커링, 그리고 문서화된 마이그레이션 경로인 렐름(realm) 내보내기 및 가져오기 기능을 제공합니다. 일부 조직에서는 상용 지원 여부가 중요한 고려 사항이 되기도 합니다. 단점은 Keycloak 자체에는 프록시 기능이 없다는 점입니다. 따라서 OIDC(OpenID Connect)를 지원하지 않는 애플리케이션을 보호하려면 oauth2-proxy와 같은 별도의 도구를 함께 실행해야 합니다. 반면 Authentik은 내장 프록시 공급자가 이미 통합되어 있습니다. 이것이 다양한 애플리케이션을 직접 호스팅하는 사용자들이 Authentik을 선택하는 주된 이유입니다.

백업 및 업그레이드

복구를 가능하게 하는 요소는 세 가지입니다. 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 작업 이후가 아닌 이전에 수행하십시오.

FAQ

Authentik을 직접 호스팅하는 것은 무료입니까?

오픈 소스 에디션은 무료이며 프록시 제공자, 포워드 인증, OIDC(OpenID Connect), SAML, 흐름 엔진 등 위에서 언급한 모든 기능을 포함합니다. 유료 엔터프라이즈 티어는 기술 지원과 일부 기업용 기능을 제공하지만, 여기에 설명된 기능은 라이선스가 필요하지 않습니다.

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

아닙니다. 포워드 인증은 nginx의 경우 auth_request를 통해, Caddy의 경우 forward_auth을 통해 작동합니다. 모든 경우에 패턴은 동일합니다. 리버스 프록시가 각 요청에 대해 Authentik에 확인을 요청하며, 보호 대상 호스트네임의 경로 접두사 /outpost.goauthentik.io/는 애플리케이션이 아닌 Authentik으로 라우팅되어야 합니다.

보호 중인 애플리케이션에서 로그인 화면과 오류 화면이 무한히 반복되는 이유는 무엇입니까?

프록시 제공자에 설정된 외부 호스트가 브라우저가 사용하는 URL과 일치하지 않기 때문입니다. 주로 http와 https이 서로 다를 때 발생합니다. 세션 쿠키는 한 오리진에 대해 발급되지만 다른 오리진에서 읽히므로, Authentik은 매번 익명 요청으로 인식하게 됩니다. 외부 호스트 설정을 수정하고, 테스트를 다시 진행하기 전에 두 호스트네임의 쿠키를 모두 삭제하십시오.

Authentik은 어느 정도의 RAM이 필요합니까?

2026년 7월 기준, 문서화된 최소 사양은 PostgreSQL, 서버, 워커를 모두 포함하여 CPU 2코어와 RAM 2 GB입니다. 2 GB 환경에서는 메모리 부족 시 커널이 워커 프로세스를 가장 먼저 종료하며, 이 경우 로그인 페이지는 작동하지만 백그라운드 작업과 발신 이메일 전송이 중단되는 증상이 나타납니다. 보호하려는 애플리케이션을 동일한 서버에서 실행 중이라면 4 GB의 RAM을 할당하는 것이 좋습니다.