NGINX auth request module 활용 외부 인증 구성 가이드
이 포스트에서는 NGINX auth request module 과 간단하게 사용자 인증을 구성할 수 있는 Simple Auth 서버를 활용하여 외부 인증을 구성하는 방법에 관해 설명합니다.
이 포스트에서는 Simple Auth 서버를 Docker을 통해서 구성하고 NGINX가 요청을 수신하면, Simple Auth 서버를 통해서 인증 후 요청이 처리되도록 구성하겠습니다. 예시에 사용된 Simple Auth 뿐만이 아닌, 자체적으로 구성한 인증 서버를 통해서도 인증을 진행할 수 있습니다.
목차
1. NGINX auth request module이란?
2. Simple Auth란?
3. Simple Auth 서버 구성
4. NGINX auth request module 활용 인증 설정
5. 결론
1. NGINX auth request module 이란?
NGINX auth request module(ngx_http_auth_request_module)은 하위 요청(subrequest)의 결과에 따라 요청을 처리하는 모듈입니다. NGINX가 클라이언트의 요청을 수신하면 NGINX auth request module을 통해 설정된 엔드포인트로 하위 요청을 전송하고, 반환된 응답에 따라 요청이 처리됩니다. 2xx 응답이 반환된 경우 요청이 정상적으로 처리되고, 401 혹은 403 응답을 반환한 경우 해당 응답 코드와 함께 요청이 거부됩니다. 이를 제외한 하위 요청의 응답 코드는 에러로 처리됩니다.
NGINX auth request module을 통해 NGINX 내부적으로 API Key/JWT 토큰(NGINX Plus) 인증을 구현하거나, 외부 인증 서버를 통해 인증하도록 구성할 수 있습니다.
NGINX auth request module은 패키지 설치 시 자동으로 구성되지만, 컴파일 설치 시 --with-http_auth_request_module 매개변수를 통해 활성화해야 합니다.
2. Simple Auth란?
Simple Auth는 로그인 및 사용자 관리를 쉽게 구현할 수 있도록 설계된 인증 서비스입니다. Okta, Keycloak을 비롯한 다른 인증 솔루션을 대체하기보단, 빠르고 간단하게 구성하는 것에 집중한 인증 서비스입니다.
Docker 혹은 Binary 방식을 통해서 Simple Auth 서버를 구성할 수 있으며, 사용자 ID와 비밀번호를 자체 데이터베이스(sqlite3)에 저장하여 로그인하도록 구성할 수 있습니다.
포함된 기능은 다음과 같습니다.
- 로컬 사용자 관리
- API 및 OAuth2 / OIDC를 통한 자격 검증
- 요청별 보증을 통한 인증 포털과 같은 역할
- 쿠키 검증을 통한 동일 도메인/서브 도메인 로그인 제공자
- 사용자 인증을 위한 다양한 API
- 환영 이메일/이메일 인증(선택 사항)
- 비밀번호 찾기
- 로그인/접속 시도 확인
- 모든 기능을 제공하는 REST API
- Postgres, Mysql DB지원
3. Simple Auth 서버 구성
먼저 Docker 컨테이너를 통해 Simple Auth 서버를 구성하도록 하겠습니다. NGINX auth request module과의 연동을 위한 Vouch 옵션을 활성화한 간단한 구성입니다.
1. Simple Auth 컨테이너를 위한 docker-compose 파일을 준비합니다.
docker-compose.yml
services:
simpleauth:
image: zix99/simple-auth:latest
ports:
- 8000:80 # 컨테이너에 연결할 포트 지정
environment:
SA_WEB_LOGIN_COOKIE_JWT_SIGNINGKEY: <임의의 JWT 서명 키> # 외부에 노출되지 않도록 주의
SA_VERBOSE: 'true' # debug 레벨 로깅 활성화
SA_WEB_LOGIN_SETTINGS_ROUTEONLOGIN: "/" # 로그인 완료 시 /경로로 리다이렉트
SA_AUTHENTICATORS_VOUCH_ENABLED: 'true' # Vouch 엔드포인트 활성화
volumes:
- sadb:/var/lib/simple-auth # 사용자 데이터 저장을 위한 볼륨 설정
volumes:
sadb: {} # 호스트 VM에 마운트 하지 않고, Docker 볼륨으로 사용NGINX auth request module을 통해 하위 요청을 전송하기 위해 파일의 환경 변수 설정을 통해 Vouch 엔드포인트를 활성화합니다.
2. docker-compose.yml 파일이 위치한 디렉터리에서 명령어를 통해 컨테이너를 생성하고 실행합니다.
$ sudo docker compose up -d
[+] Running 3/3
✔ Network simple-auth_default Created 0.2s
✔ Volume "simple-auth_sadb" Created 0.0s
✔ Container simple-auth-simpleauth-1 Started 0.6s3. 컨테이너의 실행을 확인하고, Simple Auth 서버(192.168.200.222)에 접속해 봅니다.
docker-compose 파일에서 호스트의 8000번 포트를 통해 컨테이너의 80번 포트로 연결하도록 설정하여, 8000번 포트로 접속합니다.
$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f463d63fca1a zix99/simple-auth:latest "./simple-auth-server" About an hour ago Up About an hour 0.0.0.0:8000->80/tcp, :::8000->80/tcp simple-auth-simpleauth-1
4. NGINX auth request module 활용 인증 설정
이제 NGINX의 설정 파일에 auth request module을 통해 Simple Auth 서버로 인증을 처리하도록 구성하겠습니다.
1. NGINX의 설정 파일을 auth_request 지시문을 사용하여 작성합니다.
simple-auth.conf
server {
listen 80;
location / {
auth_request /auth-validate; # / 경로로 요청 시 /auth-validate 블록으로 하위 요청을 전송합니다
root /usr/share/nginx/html;
index index.html index.html;
}
location = /auth-validate {
internal; # 인증을 위한 location으로 외부 접근을 막습니다
proxy_pass http://<192.168.200.222:8000>/api/v1/auth/vouch; # Simple Auth 서버의 vouch 엔드포인트로 요청을 프록시합니다
proxy_pass_request_body off; # 원본 요청의 body를 전달하지 않도록 설정합니다
proxy_set_header Content-Length ""; # 요청의 body가 없음을 명시합니다
proxy_set_header X-Original-URI $request_uri; # 원본 요청의 URI를 헤더로 설정하여 전달합니다
}
# 401 응답을 처리합니다. 최초 요청시 로그인 페이지로 리다이렉트 됩니다.
error_page 401 = @error401;
location @error401 {
return 302 $scheme://$http_host/auth/; # /auth 블록으로 요청을 리다이렉트 합니다
}
location /auth {
rewrite /auth/(.*) /$1 break; # URI에서 /auth를 제거하고 요청을 프록시합니다
proxy_pass http://<192.168.200.222:8000>; # Simple Auth 서버로 요청을 프록시합니다
}
}위 구성에 따른 흐름은 다음과 같습니다.
- 사용자가 루트 경로
/에 접근합니다. - NGINX는
/auth-validate를 호출하여 사용자의 인증 상태를 확인합니다. - 사용자가 로그인되어 있지 않으면
/auth-validate에서 401 응답을 반환합니다. - NGINX는 이를
@error401블록으로 리다이렉트합니다. @error401블록에서 사용자는/auth경로로 리다이렉트되며, 로그인을 진행하게 됩니다.- 로그인 완료 시 NGINX 기본 페이지로 접속됩니다.
위 예시 파일의 192.168.200.222:8000은 Simple Auth 서버의 IP:Port로, 실제 구성 시 환경에 맞게 수정합니다. 또한 예시는 NGINX 기본 페이지를 반환하도록 설정했으나, proxy_pass 설정을 통해 백엔드 서버로 프록시 되도록 구성할 수 있습니다.
위 구성은 예시를 위한 HTTP 서버 설정으로, 실제 환경에선 SSL 설정이 적용된 HTTPS 서버로 구성하세요. NGINX의 HTTPS 설정 구성 방법은 NGINX SSL Termination 문서를 참고하세요.
2. 설정 파일을 확인하고, 적용합니다.
$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ sudo nginx -s reload3. NGINX 서버(192.168.200.176)에 접속하여 Simple Auth를 통한 인증 화면을 확인합니다.
최초 접속 시 앞서 구성한 Simple Auth 서버로 연결됨을 확인할 수 있습니다.
계정을 생성합니다. 예시 사진의 경우 사전에 계정을 생성하여 중복된 사용자 이름 경고가 표시되어 있습니다.
생성한 계정을 통해 로그인합니다.
로그인을 통한 인증이 완료되어 NGINX 기본 페이지로 접속됩니다.
5. 결론
이번 포스트에서는 NGINX auth request module과 외부 인증 서버인 Simple Auth를 활용하여 NGINX에 외부 인증 시스템을 연동하는 방법에 대해 살펴보았습니다. NGINX auth request module은 NGINX 내부에서 API Key 인증, JWT 인증(NGINX Plus)을 간단히 구현할 수 있을 뿐만 아니라, 이번 포스트의 예시처럼 Simple Auth나 자체 인증 서비스를 구축하여 인증을 처리하도록 구성할 수 있습니다. 이와 같은 설정을 통해 NGINX는 다양한 외부 인증 서비스와 연동하여 더욱 유연하고 안전한 인증 솔루션을 제공할 수 있습니다.
NGINX auth request module을 통한 인증 뿐만이 아닌, 외부 인증 제공자와 연동을 통한 OIDC 인증까지 구현할 수 있는 NGINX Plus를 체험해 보고 싶으시다면 NGINX STORE를 통해 문의해 무료로 NGINX Plus trial을 체험해 보세요.
댓글을 달려면 로그인해야 합니다.