메모

[메모] sso 인증 관련 도커

KING

— 12 min read
[메모] sso 인증 관련 도커
📝 Memos에서 자동 발행됨
🕐 작성일: 2026-01-11
✨ AI가 보충 설명을 추가했습니다 🔍 웹 조사 자료를 바탕으로 작성되었습니다

개요

오늘날 디지털 환경에서 사용자들은 수많은 애플리케이션과 서비스에 접근합니다. 이 과정에서 각 서비스마다 별도의 계정을 관리하고 로그인하는 것은 사용자에게 번거로움을 줄 뿐만 아니라, 기업에게는 보안 및 관리의 복잡성을 야기합니다. 이러한 문제를 해결하기 위한 강력한 솔루션이 바로 싱글 사인온(SSO, Single Sign-On) 입니다. SSO는 한 번의 인증으로 여러 애플리케이션에 접근할 수 있게 하여 사용자 경험을 향상시키고 보안을 강화하며, 관리 부담을 줄여주는 핵심 기술입니다.

SSO 솔루션을 구축하는 방법은 다양하지만, Docker를 활용하면 환경에 구애받지 않고 빠르고 효율적으로 SSO 인프라를 구축하고 관리할 수 있습니다. Docker 컨테이너를 통해 SSO 인증 서버를 배포함으로써, 개발 환경이든 소규모 프로덕션 환경이든 일관된 설정과 손쉬운 확장을 가능하게 합니다. 특히 authentik이나 Keycloak과 같은 오픈소스 ID 공급자(Identity Provider)를 Docker 위에 올리는 방식은 개발자들 사이에서 널리 활용되고 있습니다.

이 블로그 포스트에서는 유연하고 다양한 기능을 제공하는 오픈소스 ID 공급자 authentik을 Docker Compose를 이용하여 구축하고 SSO 서비스로 활용하는 방법에 대해 자세히 알아볼 것입니다. authentik은 기존 환경에 새로운 인증 프로토콜을 추가하거나, 애플리케이션 내의 가입/복구 로직을 직접 구현할 필요 없이 authentik이 대신 처리하도록 하여 개발 생산성을 크게 높일 수 있습니다. 본 가이드를 통해 여러분의 서비스에 강력한 SSO 기능을 손쉽게 통합하는 방법을 숙지하시길 바랍니다.

상세 가이드: Docker와 authentik을 이용한 SSO 구축

authentik을 Docker Compose를 이용하여 구축하는 상세 과정을 단계별로 설명합니다.

1단계: 필수 소프트웨어 설치 및 확인

authentik을 설치하기 전에 시스템에 Docker와 Docker Compose가 설치되어 있는지 확인해야 합니다.

  • Docker 설치: sudo apt-get update && sudo apt-get install -y docker.io (Ubuntu 기준)
  • Docker Compose 설치: sudo apt-get install -y docker-compose (Ubuntu 기준, 최신 버전은 curl 설치 권장)
  • 또는 Docker Desktop 설치 시 Docker Compose가 함께 설치됩니다.

2단계: docker-compose.yml 파일 다운로드

authentik 공식 홈페이지에서 제공하는 Docker Compose 설정 파일을 다운로드합니다. 이 파일은 authentik 서비스를 구성하는 데 필요한 PostgreSQL, Redis, authentik 서버 및 워커 컨테이너를 정의합니다.

wget https://goauthentik.io/docker-compose.yml

다운로드된 docker-compose.yml 파일의 내용은 다음과 같습니다:

version: "3.7"
services:
  postgresql:
    image: docker.io/library/postgres:12-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 5s
    volumes:
      - database:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${PG_PASS:?database password required}
      POSTGRES_USER: ${PG_USER:-authentik}
      POSTGRES_DB: ${PG_DB:-authentik}
    env_file:
      - .env
  redis:
    image: docker.io/library/redis:alpine
    command: --save 60 1 --loglevel warning
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s
    volumes:
      - redis:/data
  server:
    image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2023.6.1}
    restart: unless-stopped
    command: server
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
    volumes:
      - ./media:/media
      - ./custom-templates:/templates
    env_file:
      - .env
    ports:
      - "${COMPOSE_PORT_HTTP:-9000}:9000"
      - "${COMPOSE_PORT_HTTPS:-9443}:9443"
    depends_on:
      - postgresql
      - redis
  worker:
    image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2023.6.1}
    restart: unless-stopped
    command: worker
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
    # `user: root` and the docker socket volume are optional.
    # See more for the docker socket integration here:
    # https://goauthentik.io/docs/outposts/integrations/docker
    # Removing `user: root` also prevents the worker from fixing the permissions
    # on the mounted folders, so when removing this make sure the folders have the correct UID/GID
    # (1000:1000 by default)
    user: root
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./media:/media
      - ./certs:/certs
      - ./custom-templates:/templates
    env_file:
      - .env
    depends_on:
      - postgresql
      - redis
volumes:
  database:
    driver: local
  redis:
    driver: local

3단계: .env 파일 생성 및 암호화 키 설정

보안을 위해 데이터베이스 비밀번호(PG_PASS)와 authentik의 비밀 키(AUTHENTIK_SECRET_KEY)를 .env 파일에 저장합니다. pwgen 도구를 사용하여 강력한 무작위 문자열을 생성하는 것을 권장합니다.

# 키를 생성해줄 패키지를 설치
sudo apt-get install -y pwgen

# PG_PASS 와 AUTHENTIK_SECRET_KEY 생성하여 .env에 저장
echo "PG_PASS=$(pwgen -s 40 1)" >> .env
echo "AUTHENTIK_SECRET_KEY=$(pwgen -s 50 1)" >> .env

생성된 .env 파일은 docker-compose.yml과 동일한 디렉터리에 위치해야 합니다.

4단계: Docker Compose 서비스 시작

모든 설정이 완료되었으면, 다음 명령어를 사용하여 authentik 서비스를 시작합니다. -d 옵션은 백그라운드에서 서비스를 실행하도록 합니다.

docker-compose up -d

5단계: 서비스 확인

서비스가 정상적으로 실행되고 있는지 확인합니다.

docker-compose ps

모든 서비스(postgresql, redis, server, worker)가 Up 상태로 표시되어야 합니다.

6단계: authentik 서비스 접속 및 초기화 설정

웹 브라우저를 열고 http://[서버 IP]:9000으로 접속합니다. (기본 HTTP 포트가 9000번입니다.) 초기 접속 시 authentik의 초기 설정 페이지로 리다이렉트됩니다.

http://[서버 IP]:9000/if/flow/initial-setup/

이 페이지에서 관리자 계정을 생성하고 authentik을 초기 설정합니다.

7단계: Admin Interface 접속 및 Provider 생성

초기 설정 완료 후, Admin interface 버튼을 클릭하여 authentik 관리자 대시보드에 접속합니다.

좌측 메뉴에서 Application > Provider를 클릭한 후, Create 버튼을 눌러 새로운 Provider를 생성합니다. SSO를 적용할 애플리케이션의 종류에 따라 OAuth2/OpenID Provider, SAML Provider, Proxy Provider 등 적절한 Provider 유형을 선택합니다. 이 예시에서는 Proxy Provider 생성을 가정합니다.

Proxy Provider 선택 후, 애플리케이션의 요구사항에 맞게 필요한 정보를 입력하고 설정을 완료합니다. 예를 들어, 리다이렉션 URL, 인증 흐름 등을 설정하게 됩니다.

실제 사용 예시

authentik을 구축하고 초기 설정을 마쳤다면, 이제 여러분의 애플리케이션과 연동할 차례입니다. 가장 기본적인 연동 방법 중 하나는 Proxy Provider를 사용하여 기존 애플리케이션에 SSO 기능을 추가하는 것입니다.

예시: Nginx와 authentik Proxy Provider 연동

authentik의 Proxy Provider는 Nginx와 같은 웹 서버의 리버스 프록시 설정과 결합하여, 기존에 인증 로직이 없는 애플리케이션 앞에 authentik 인증 레이어를 추가할 수 있습니다.

  1. authentik에서 Proxy Provider 생성:
    • authentik Admin Interface 접속 (http://[서버 IP]:9000).
    • Application > Provider 메뉴에서 Create 클릭 후 Proxy Provider 선택.
    • Name (예: MyWebApp-Proxy), Authentication Flow (기본 default-authentication-flow), Authorization Flow 등을 설정합니다.
    • 중요한 것은 이 Provider가 보호할 애플리케이션의 실제 URL을 지정하는 것입니다. (이는 Nginx 설정에서 사용됩니다.)
    • External Host 필드에 여러분의 서비스 도메인(예: mywebapp.example.com)을 입력하고, Internal Host는 Proxy Provider가 접근할 실제 애플리케이션의 내부 주소(예: http://mywebapp-internal:80)를 지정합니다.

Nginx 설정 추가: 여러분의 Nginx 설정 파일 (nginx.conf 또는 sites-available 내부 설정 파일)에 authentik Proxy Provider를 통과하도록 설정을 추가합니다.

server {
    listen 80;
    server_name mywebapp.example.com; # 여러분의 서비스 도메인

    location / {
        # authentik으로 요청을 리다이렉트 (여기서는 authentik의 Proxy Outpost가 처리)
        # authentik의 Proxy Outpost가 Nginx를 대체하거나, Nginx 뒤에서 동작합니다.
        # 실제 설정은 authentik 문서의 Proxy Outpost 연동 가이드를 따르는 것이 정확합니다.
        # 하지만 간단한 개념을 위해 Nginx가 authentik으로 요청을 보내는 것으로 가정합니다.

        # 일반적으로 authentik은 자체 Proxy Outpost를 배포하여 애플리케이션과 연동합니다.
        # 다음은 authentik Proxy Outpost가 애플리케이션 요청을 가로채는 방식의 가상 예시입니다.
        # 실제로는 authentik Proxy Outpost를 Docker로 배포하고,
        # Nginx는 해당 아웃포스트로 요청을 보내도록 설정합니다.

        # Nginx가 authentik proxy outpost로 리버스 프록시하는 예시 (개념 설명용)
        proxy_pass http://authentik-proxy-outpost:9000; # authentik proxy outpost 주소
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

참고: authentik은 Proxy Outpost라는 전용 컴포넌트를 제공하여 이러한 프록시 연동을 더욱 쉽게 합니다. docker-compose.yml의 worker 서비스 주석에 언급된 outposts/integrations/docker 링크를 참고하여 Proxy Outpost를 배포하는 것이 일반적인 방식입니다. Proxy Outpost는 애플리케이션 컨테이너와 동일한 네트워크에 배포되어 요청을 authentik 서버로 전달하고 인증된 세션을 관리합니다.

이러한 방식으로 사용자가 mywebapp.example.com에 접근하면 authentik의 인증 페이지로 리다이렉트되고, 성공적으로 로그인하면 실제 애플리케이션 페이지로 진입하게 됩니다.

💡 유용한 팁

  1. authentik의 유연한 프로토콜 지원 활용: authentik은 OAuth2/OpenID Connect, SAML, LDAP 등 다양한 인증 프로토콜을 지원합니다. 여러분의 애플리케이션 스택에 맞는 프로토콜을 선택하여 유연하게 SSO를 구성할 수 있습니다.
  2. Docker Compose를 통한 빠른 개발/테스트 환경 구축: 제공된 docker-compose.yml은 테스트 및 소규모 프로덕션 환경에 최적화되어 있습니다. 개발 단계에서 빠르고 일관된 환경을 구축하는 데 활용하여 개발 생산성을 높일 수 있습니다.
  3. 환경 변수를 통한 보안 강화: PG_PASS와 AUTHENTIK_SECRET_KEY 같은 중요한 정보는 .env 파일을 통해 관리하고, 버전 관리 시스템에 직접 포함하지 않는 것이 좋습니다. pwgen과 같은 도구로 강력하고 무작위적인 키를 생성하여 보안을 강화하세요.
  4. 컨테이너 헬스 체크 활용: docker-compose.yml에 포함된 PostgreSQL 및 Redis 서비스의 healthcheck 설정은 서비스의 안정성을 보장하는 데 중요합니다. 컨테이너가 정상적으로 동작하는지 지속적으로 모니터링하여 문제가 발생했을 때 자동으로 재시작되도록 합니다.
  5. worker 서비스의 Docker 소켓 통합 옵션 이해: worker 서비스의 volumes: - /var/run/docker.sock:/var/run/docker.sock 설정은 authentik 워커가 Docker 호스트와 통신할 수 있게 합니다. 이는 authentik의 아웃포스트(Outposts) 기능을 활용하여 다른 Docker 컨테이너 기반 애플리케이션에 SSO를 적용할 때 유용합니다. 필요에 따라 이 설정을 조정할 수 있습니다.

⚠️ 주의사항

  1. 보안 키 관리: .env 파일에 저장된 PG_PASS 및 AUTHENTIK_SECRET_KEY는 authentik 인스턴스의 보안에 직접적인 영향을 미칩니다. 이 파일이 노출되지 않도록 철저히 관리하고, 절대 공개 저장소에 업로드하지 마십시오. 프로덕션 환경에서는 Docker Secrets나 Kubernetes Secrets와 같은 더 안전한 방법을 고려해야 합니다.
  2. 리소스 할당: authentik은 PostgreSQL 데이터베이스와 Redis 캐시를 사용합니다. 특히 PostgreSQL은 데이터 저장량이 증가함에 따라 더 많은 디스크 공간과 메모리를 요구할 수 있습니다. 운영 환경에서는 서버의 충분한 리소스 할당을 고려하고, Docker Compose 대신 Kubernetes와 같은 오케스트레이션 도구를 사용하는 것을 검토할 필요가 있습니다.
  3. 볼륨 권한 설정: worker 서비스의 volumes 설정에서 ./media, ./certs, ./custom-templates 등 호스트와 마운트되는 볼륨의 권한에 주의해야 합니다. 만약 worker 서비스에서 user: root 설정을 제거한다면, 해당 볼륨들이 authentik이 요구하는 UID/GID(기본적으로 1000:1000)를 가질 수 있도록 수동으로 권한을 조정해야 할 수 있습니다. 잘못된 권한 설정은 서비스 오작동의 원인이 될 수 있습니다.

🔗 참고 자료

Read more

개인정보보호링크