Authelia - 리버스 프록시 환경 강력한 인증(Authentication)과 인가(Authorization) 오픈소스 보안 서버

Authelia - 리버스 프록시 환경에서 강력한 인증(Authentication)과 인가(Authorization) 오픈소스 보안 서버

Authelia는 리버스 프록시와 긴밀하게 통합되어 웹 서비스에 대한 인증(Authentication)과 인가(Authorization)를 대행하는 오픈소스 보안 서버입니다. 사용자가 보호된 서비스에 접근하려고 할 때 프록시 서버가 Authelia에 해당 요청의 유효성을 확인하도록 요청하는 방식으로 작동

[세부 내용]
가. Authelia를 Nginx 기능과 특징
나. Authelia를 Nginx와 연동  구축 절차
[참고 #1]    Local Domain에서 Authelia  설치

 
 

가. Authelia를 Nginx 기능과 특징

 

1. Authelia  주요 기능

   Authelia는 자체 구축이 가능한 인증/인가(Authentication & Authorization) 서버로, 다음과 같은 기능을 제공합니다:

• 2단계 인증(2FA)
• 싱글 사인온(SSO)
• 세분화된 접근 제어
• LDAP/AD 통합
• 역방향 프록시 연동(Nginx, Traefik 등)

 

2. 주요 기능 및 장점

• Single Sign-On (SSO): 한 번 로그인하면 Authelia로 보호되는 모든 서비스에 추가 로그인 없이 접속할 수 있습니다.
• 다양한 2FA 지원: Yubikey와 같은 하드웨어 키부터 모바일 앱 OTP까지 폭넓은 2차 인증 수단을 제공합니다.
• 보안 강화: 자체 로그인 기능이 없거나 보안이 취약한 오래된 웹 서비스 앞단에 두어 보안 계층을 즉시 추가할 수 있습

 

3. 주요 구성 요소

• 리버스 프록시 (Reverse Proxy): Nginx Proxy Manager, Traefik, Caddy 등과 연동되어 실질적인 관문 역할을 합니다.
• 사용자 백엔드 (User Backend): 사용자 정보를 저장하는 곳으로, 간단한 YAML 파일이나 기업용 LDAP/Active Directory를 지원합니다.
• 데이터베이스 (Storage Backend): 인증 세션, 2FA 장치 정보 등을 저장하기 위해 SQLite, PostgreSQL, MariaDB 등을 사용합니다.
• 접근 제어 정책 (Access Control): 특정 도메인, IP 대역, 사용자 그룹에 따라 "인증 생략", "1단계만 필요", "2단계 필수" 등의 상세 규칙을 설정

 

4. Authelia 핵심 작동 방식 (워크플로우)

   사용자가 보호된 웹사이트에 접속할 때의 일반적인 과정은 다음과 같습니다:

1. 요청 가로채기: 사용자가 웹 서비스에 접속하면, Nginx나 Traefik 같은 리버스 프록시가 이 요청을 먼저 받습니다.
2. 인증 확인: 프록시 서버는 Authelia의 API(주로 /api/verify)에 "이 사용자가 인증되었는가?"를 묻습니다.
3. 인증 진행:
   • 미인증 시: 사용자를 Authelia 로그인 페이지로 리다이렉트합니다.
   • 1단계 인증: 사용자가 아이디/비밀번호를 입력하면 Authelia는 백엔드(LDAP, 파일 등)에서 정보를 확인합니다.
   • 2단계 인증 (2FA): 정책에 따라 TOTP(구글 OTP), WebAuthn(FIDO2 보안키), Duo 푸시 알림 등을 추가로 요구합니다.
4. 세션 생성: 인증이 완료되면 Authelia는 사용자 브라우저에 쿠키(세션)를 생성합니다.
5. 접근 허용: 이후 프록시 서버는 인증된 요청에 대해 사용자 정보 헤더(예: X-Forwarded-User)를 추가하여 실제 웹 서비스로 전달합니다

 
 

나 . Authelia를 Nginx와 연동  구축 절차

---

전용 인증 서버인 Authelia를 Nginx와 연동하여 Google Authenticator(2FA)를 구현하는 현대적인 표준 구성(Docker 기반)을 안내해 드립니다.

1. 작동 환경 및 아키텍처 (Architecture)

이 구성은 모든 서비스를 Docker 컨테이너로 띄워 관리하는 방식입니다.

• 사용자(Browser): 웹사이트 접속 시도.
• Nginx (Reverse Proxy): 외부 요청을 받아 Authelia에게 "이 사용자 인증됨?"이라고 물어봄 (auth_request 모듈 사용).
• Authelia (Auth Server): 사용자가 로그인(ID/PW)하고 Google Authenticator 코드(2FA)를 입력하는 페이지 제공.
• Redis/File (Storage): 인증 세션 및 사용자 정보를 저장 (가장 간단한 파일 기반 설정 기준).
•  

2. 구성 파일 (Source Codes)

가장 핵심이 되는 3가지 파일을 작성해 드립니다.

① docker-compose.yml (서비스 구성)

services:
  nginx:
    image: nginx:latest
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - authelia

  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia:/config
    environment:
      - TZ=Asia/Seoul
    restart: unless-stopped

 
 

② nginx.conf (인증 연동 핵심 설정)

Nginx가 Authelia에게 인증 여부를 묻도록 설정합니다.

server {
    listen 80;
    server_name ://example.com;

    # 1. Authelia 인증 체크 경로
    location /internal/authelia/authz {
        internal;
        proxy_pass http://authelia:9091/api/authz/forward-auth;
    }

    # 2. 실제 보호하려는 웹 서비스
    location / {
        # Authelia 인증 요청 활성화
        auth_request /internal/authelia/authz;
        
        # 인증 안됐을 경우 Authelia 로그인 페이지로 리다이렉트
        error_page 401 =302 https://example.com;

        proxy_pass http://my-backend-service:8080;
    }
}

 

③ authelia/configuration.yml (2FA 설정)

Authelia 설정 파일에서 2FA(TOTP)를 활성화합니다.

 

authentication_backend:
  file:
    path: /config/users_database.yml

# Google Authenticator (TOTP) 설정
totp:
  issuer: "MyHomeServer"
  period: 30
  skew: 1

access_control:
  default_policy: 'one_factor' # 기본은 ID/PW만
  rules:
    - domain: "://example.com"
      policy: 'two_factor' # 특정 도메인은 무조건 OTP 강제

 

3. 연동 및 작동 프로세스 (Flow) 확인

1. 첫 접속: 사용자가 Nginx(보호된 사이트)에 접속합니다.
2. 인증 확인: Nginx가 auth_request를 통해 Authelia에게 사용자의 세션 쿠키가 유효한지 확인합니다.
3. 로그인 이동: 인증되지 않은 사용자라면 Authelia 로그인 화면(://example.com)으로 보냅니다.
4. 1단계 인증: 사용자가 ID와 비밀번호를 입력합니다.
5. 2단계 인증(Google OTP): ID/PW가 맞으면 Authelia가 OTP 입력창을 띄웁니다. 사용자는 스마트폰의 Google Authenticator 앱에 뜬 6자리 번호를 입력합니다.
6. 세션 발급: 인증 성공 시 Authelia는 세션 쿠키를 굽고 원래 접속하려던 페이지로 돌려보냅니다.
7. 최종 승인: 이제 Nginx는 Authelia로부터 "인증됨(200 OK)" 응답을 받고 실제 내부 서버의 콘텐츠를 보여줍니다.

 
 

4. 구축 시 주의사항

• HTTPS 필수: OTP 번호와 세션 쿠키를 보호하기 위해 반드시 SSL(HTTPS) 환경에서 구축해야 합니다 (Let's Encrypt 추천).
• 도메인: Authelia와 서비스 도메인이 같은 상위 도메인(예: *.example.com)을 공유해야 쿠키 공유가 원활합니다.

 

---

[참고 #1]    Local Domain에서 Authelia  설치
 
다. Local Domain으로 작동 검증 

로컬 환경(Local Domain)에서 테스트하기 위해서는 hosts 파일 수정과 HTTPS 처리가 가장 중요합니다. 브라우저 보안 정책상 OTP 관련 쿠키와 인증 정보는 HTTPS가 아니면 정상 작동하지 않을 수 있기 때문입니다.

로컬 도메인(예: my-app.local, auth.local)을 기준으로 하는 가이드를 정리해 드립니다.

1. 로컬 도메인 설정 (hosts 파일)

먼저 PC의 hosts 파일을 수정하여 로컬 도메인이 자신의 PC(127.0.0.1)를 가리키게 합니다.

• Windows: C:\Windows\System32\drivers\etc\hosts
• Mac/Linux: /etc/hosts

127.0.0.1 auth.local
127.0.0.1 my-app.local

 

2. 로컬 HTTPS 환경 구성 (mkcert 추천)

Authelia는 보안상 HTTPS를 강력히 권장합니다. 로컬에서 가짜 인증서를 쉽게 만들려면 mkcert 도구를 추천합니다.

1. mkcert -install (로컬 신뢰 기관 등록)
2. mkcert auth.local my-app.local (인증서 파일 생성: _wildcard.local.pem, _wildcard.local-key.pem)

 
 

authelia/ ├── docker-compose.yml ├── config/ │ ├── configuration.yml │ └── users_database.yml

 

 

3. Docker Compose 소스 (로컬 최적화)

생성한 인증서를 적용한 전체 구조입니다.

 

services:
  # 1. Nginx: 모든 요청의 입구
  nginx:
    image: nginx:latest
    container_name: nginx
    ports:
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro # mkcert로 만든 인증서
    depends_on:
      - authelia

  # 2. Authelia: 인증 서버 (Google OTP 처리)
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia:/config
    environment:
      - TZ=Asia/Seoul

  # 3. 테스트용 실제 앱
  my-app:
    image: nginxdemos/hello
    container_name: my-app

 

4. Nginx 설정 핵심 (nginx.conf)

 

server {
    listen 443 ssl;
    server_name my-app.local;

    ssl_certificate /etc/nginx/certs/auth.local+1.pem;
    ssl_certificate_key /etc/nginx/certs/auth.local+1-key.pem;

    # Authelia 인증 체크
    location /internal/authelia/authz {
        internal;
        proxy_pass http://authelia:9091/api/authz/forward-auth;
    }

    location / {
        auth_request /internal/authelia/authz;
        error_page 401 =302 https://auth.local; # 미인증 시 이동

        proxy_pass http://my-app:80;
    }
}

server {
    listen 443 ssl;
    server_name auth.local; # Authelia 로그인 페이지용 도메인

    ssl_certificate /etc/nginx/certs/auth.local+1.pem;
    ssl_certificate_key /etc/nginx/certs/auth.local+1-key.pem;

    location / {
        proxy_pass http://authelia:9091;
    }
}

 

5. 로컬 연동 프로세스 요약

1. 접속: 브라우저에서 https://my-app.local 접속.
2. 판단: Nginx가 Authelia에게 물어보고 401 코드를 받음.
3. 이동: https://auth.local로 리다이렉트.
4. 로그인: 미리 설정한 ID/PW 입력 (Authelia users_database.yml에 설정).
5. 2FA 등록: 처음 접속 시 Authelia가 이메일 링크 대신 로컬 로그에 OTP 등록 QR 코드 주소를 남깁니다. (로컬은 메일 서버가 없으므로 도커 로그 확인 필요)
   • docker logs authelia 명령어로 QR 코드 링크 확인 후 스마트폰 스캔.
6. 완료: OTP 번호 입력 후 다시 my-app.local로 넘어가서 서비스 확인

 

---

[참고 #2]  users_database.yml 샘플 코드

Authelia의 기본 사용자 정보를 담는 users_database.yml 파일 샘플입니다. 이 파일에서 사용자의 비밀번호 해시값과 이메일, 그룹을 정의합니다.

 

authelia/ ├── docker-compose.yml ├── config/ │ ├── configuration.yml │ └── users_database.yml

 
1. users_database.yml 샘플 코드

users:
  # 사용자 아이디 (로그인 시 사용)
  myuser:
    # 비밀번호: 'password' (Argon2 해시 방식 권장)
    password: "$argon2id$v=19$m=65536,t=3,p=4$uC6SInX8Uunb9SAn1f6D7Q$H5r9vA88U3p0Z3E/x9Xo/vX4vB8"
    displayname: "My Admin"
    emails:
      - "myuser@example.com"
    groups:
      - admins
      - users

 

2. 중요 설정 포인트

1. 비밀번호 해시: Authelia는 보안상 평문 비밀번호를 저장하지 않습니다.
   • 초기 비밀번호 생성은 Docker 명령어로 간단히 할 수 있습니다

docker run --rm authelia/authelia:latest authelia hash-password "원하는비밀번호"

 

• 위 명령어를 실행해서 나온 결과를 password: 뒤에 붙여넣으세요.
• 이메일 주소: 로컬 테스트 환경이라도 이메일 형식을 갖춰야 합니다. (실제 수신 여부와 상관없이 초기 등록 시 식별자로 쓰입니다.)
• 그룹(Groups): configuration.yml의 access_control 섹션에서 특정 그룹만 접근 가능하게 제한할 때 활용합니다.

 

3. Google Authenticator(2FA) 등록 팁 (로컬 환경)

로컬에서 이메일 서버를 구축하지 않았다면, 처음 OTP를 등록할 때 인증 메일을 받을 수 없습니다. 이때는 다음 과정을 따르세요.

  1) configuration.yml에서 이메일 전송 방식을 file로 설정합니다

notifier:
  filesystem:
    filename: /config/notification.txt

 
 2) 로그인 페이지에서 2FA 등록 버튼을 누릅니다.
 3) 도커 볼륨으로 연결된 authelia/notification.txt 파일을 열어보면 QR 코드 링크가 텍스트로 찍혀 있습니다.
 4) 그 링크를 브라우저에 붙여넣어 QR 코드를 띄운 후 Google Authenticator 앱으로 스캔하면 등록이 완료됩니다.

5) 이 설정까지 마치고 docker-compose up -d를 실행하면 로컬에서 완벽하게 작동할 것 입니다.

 

(관련 문서)
1. Authelia - 오픈소스 보안 서버 구축
https://couplewith.tistory.com/m/926

Authelia - 리버스 프록시 환경의 인증(Authentication)과 인가(Authorization)를 대행하는 오픈소스 보안 서

2. Authelia - 강력한 인증 특징과 장점 비교
https://couplewith.tistory.com/m/927

Authelia - 오픈 소스 기반의 강력한 인증 서버 분석 비교