인증 제공자 (ForwardAuth)
Authelia, Authentik 또는 사용자 정의 인증 서비스를 프록시 호스트 앞단에 붙여, 백엔드에 도달하기 전에 모든 요청을 SSO(싱글 사인온)로 보호합니다.
동작 방식
nginx의 auth_request를 사용해, 요청이 백엔드로 전달되기 전에 인증 제공자에게 "이 사용자가 로그인되어 있는가?"를 먼저 물어봅니다.
| 상태 | 동작 |
|---|---|
| 인증됨 | 요청을 백엔드로 전달하고, 사용자 정보(이름·이메일·그룹 등)를 헤더로 함께 전달 |
| 미인증 | 로그인 포털로 리다이렉트(302) |
인증 제공자는 한 번 정의하고 여러 호스트에 재사용합니다. 제공자 하나를 만들어 두면, 여러 프록시 호스트에 같은 SSO를 연결할 수 있습니다.
지원 제공자
| 유형 | 설명 |
|---|---|
| Authelia | Authelia 4.37 이상. 세션 쿠키 도메인은 모든 보호 호스트와 포털의 상위 도메인이어야 합니다. |
| Authentik | authentik outpost를 통해 인증. 임베디드 outpost는 보통 authentik 서버:9000. |
| 사용자 정의 (Custom) | auth_request 호환 검증기(oauth2-proxy 등) — 검증 경로와 로그인 리다이렉트를 직접 지정 |
인증 제공자 만들기
설정 → 인증 제공자 (ForwardAuth) 에서 인증 제공자 추가를 선택합니다.
| 항목 | 설명 |
|---|---|
| 이름 | 식별용 이름 (예: 홈 Authelia) |
| 유형 | Authelia · Authentik · 사용자 정의 |
| 인증 서비스 URL | 프록시 컨테이너에서 접근 가능한 주소. host 네트워크 설치는 호스트 IP:포트, bridge 네트워크는 서비스 이름을 사용합니다. |
인증 서비스 URL은 NginxProxyGuard의 nginx 컨테이너에서 실제로 접근 가능한 주소여야 합니다. 외부 도메인이 아니라 내부 주소를 사용하세요.
도커 컨테이너에서 선택
URL을 직접 입력하는 대신 도커 컨테이너에서 선택을 누르면, 실행 중인 컨테이너에서 인증 서비스를 골라 자동으로 구성할 수 있습니다.
- 컨테이너의 현재 IP로 자동 구성됩니다.
- 컨테이너가 재시작되어 IP가 바뀌면 자동으로 다시 확인해 갱신합니다.
- 목록에서 동기화 상태(동기화됨 / 컨테이너 못 찾음)를 확인할 수 있습니다.
호스트에 적용
- 설정 → 인증 제공자에서 제공자를 먼저 만듭니다.
- 프록시 호스트 → 편집 → 보안 탭 → "인증 제공자" 에서 호스트에 적용합니다. 예외 경로도 여기서 지정합니다.
보호 대상 호스트는 반드시 HTTPS여야 합니다 — Authelia/Authentik은 http 대상을 거부합니다.
인증 제공자 화면의 호스트 탭에서 한 번에 여러 호스트를 연결할 수도 있습니다. 단, 미적용 HTTPS 호스트만 연결 대상으로 표시되며, 챌린지(CAPTCHA) 모드가 켜져 있거나 사용자 정의 location / 가 있는 호스트는 거부됩니다.
예외 경로 (Bypass Paths)
인증 없이 통과시킬 경로를 한 줄에 하나씩 지정합니다 (예: /api/health, /webhook).
/로 시작해야 하며, 공백과;{}#문자는 사용할 수 없습니다.- Webhook 수신 엔드포인트나 헬스체크처럼 로그인 없이 접근해야 하는 경로에 사용합니다.
제공자별 설정
Authelia
- 별도 추가 필드 없이 인증 서비스 URL만 지정하면 됩니다 (예:
http://127.0.0.1:9091). - 로그인한 사용자 정보가
Remote-User·Remote-Groups·Remote-Name·Remote-Email헤더로 백엔드에 전달됩니다. - 인증 실패 시 Authelia 포털로 리다이렉트됩니다.
Authentik
- 인증 서비스 URL에 outpost 주소를 지정합니다 (임베디드 outpost는
authentik 서버:9000). - authentik의
/outpost.goauthentik.io경로를 통해 인증/로그인 흐름을 처리합니다. - 사용자 정보가
X-authentik-username·X-authentik-groups·X-authentik-email등의 헤더로 전달됩니다.
사용자 정의 (Custom)
auth_request 호환 검증기(oauth2-proxy 등)를 직접 연결할 때 사용합니다.
| 항목 | 설명 |
|---|---|
| 검증 경로 | 인증 검증 엔드포인트 경로 |
| 로그인 리다이렉트 방식 | Location 헤더 (검증기가 리다이렉트 URL 제공) 또는 리다이렉트 템플릿 (사용자 지정 URL) |
| 로그인 리다이렉트 URL | 리다이렉트 템플릿 방식일 때 사용할 URL |
| Set-Cookie 전달 | 검증 응답의 Set-Cookie를 클라이언트로 전달 |
| 대용량 헤더 버퍼 | 인증 응답 헤더가 큰 경우(JWT·그룹·권한 등) 헤더 버퍼를 키웁니다 |
주의사항 및 제약
| 항목 | 내용 |
|---|---|
| 챌린지와 상호 배타 | 한 호스트에서 ForwardAuth와 CAPTCHA/지역 챌린지 모드를 동시에 사용할 수 없습니다. 인증 제공자를 쓰려면 챌린지 모드를 끄세요. |
| HTTPS 필수 | Authelia/Authentik은 http 대상을 거부하므로 보호 호스트는 HTTPS여야 합니다. |
| 신뢰 IP에도 적용 | 인증은 신뢰 IP를 포함한 모든 요청에 적용됩니다 (예외 경로 제외). |
사용자 정의 location / 충돌 | 사용자 정의 location / 설정이 있는 호스트에는 적용할 수 없습니다. |
| 삭제 시 보호 해제 | 사용 중인 인증 제공자를 삭제하면 연결된 호스트의 인증 보호가 함께 해제됩니다. |
인증 제공자 설정 변경은 nginx 설정 재생성을 통해 적용됩니다. 보호 호스트가 HTTPS인지, 인증 서비스 URL이 프록시 컨테이너에서 접근 가능한지 먼저 확인하세요.