forward_auth 지시문
forward_auth 지시문 (인증 게이트웨이 프록시)
forward_auth 지시문은 요청의 복제본을 인증 게이트웨이로 프록시해서, 처리를 계속할지 로그인 페이지로 보낼지 결정하도록 해주는 의견이 반영된(opinionated) 지시문이에요.
출처: Caddy 공식 문서
본문
요청의 복제본을 인증 게이트웨이로 프록시하는 의견이 반영된 지시문이에요. 인증 게이트웨이가 처리를 계속해야 할지, 로그인 페이지로 보내야 할지 결정할 수 있어요.
Caddy의 reverse_proxy는 외부 서비스에 "사전-확인 요청(pre-check request)"을 수행할 수 있지만, 이 지시문은 인증 사용 사례에 특화되어 있어요. 사실 이 지시문은 길고 흔한 설정(아래)을 쓰는 편리한 방법일 뿐이에요.
이 지시문은 uri가 재작성된 상태로 설정된 업스트림에 GET 요청을 보내요:
-
업스트림이
2xx상태 코드로 응답하면 접근이 허용되고copy_headers의 헤더 필드를 원래 요청에 복사한 다음 처리를 계속해요. -
그렇지 않고 업스트림이 다른 상태 코드로 응답하면, 업스트림의 응답을 클라이언트에 그대로 복사해요. 이 응답은 보통 인증 게이트웨이의 로그인 페이지로의 리다이렉트를 포함해요.
이 동작이 정확히 원하는 것이 아니라면 아래의 확장 형태를 기반으로 필요에 맞게 커스터마이즈할 수 있어요.
reverse_proxy의 모든 하위 지시문을 지원하며, 기본 reverse_proxy 핸들러로 전달돼요.
문법 (Syntax)
forward_auth [<matcher>] [<upstreams...>] {
uri <to>
copy_headers <fields...> {
<fields...>
}
}
-
**<upstreams...>**는 인증 요청을 보낼 업스트림(백엔드) 목록이에요.
-
uri는 업스트림에 보내는 요청에 설정할 URI(경로 및 쿼리)예요. 보통 인증 게이트웨이의 검증 엔드포인트가 될 거예요. 한 번만 지정할 수 있어요.
-
copy_headers는 요청이 성공 상태 코드일 때 응답에서 원래 요청으로 복사할 HTTP 헤더 필드 목록이에요.
>뒤에 새 이름을 붙여 필드 이름을 바꿀 수 있어요. 예:Before>After.가독성을 위해 블록을 사용해 필드를 한 줄에 하나씩 나열할 수 있어요.
이 지시문은 리버스 프록시를 감싼 의견이 반영된 래퍼이므로, reverse_proxy의 어떤 하위 지시문이든 커스터마이즈에 사용할 수 있어요.
확장 형태 (Expanded form)
forward_auth 지시문은 다음 설정과 동일해요. Authelia 같은 인증 게이트웨이는 이 프리셋과 잘 작동해요. 그렇지 않다면 forward_auth 단축 대신 이 형태에서 필요한 부분을 가져와 커스터마이즈해도 좋아요.
reverse_proxy <upstreams...> {
# 항상 GET을 사용해 들어오는
# 요청의 본문을 소비하지 않게 함
method GET
# URI를 인증 게이트웨이의
# 검증 엔드포인트로 변경
rewrite <to>
# 위에서 재작성되므로 원래 method와 URI를
# 전달함. 이는 reverse_proxy가 이미 설정한
# 다른 X-Forwarded-* 헤더에 추가로 붙음
header_up X-Forwarded-Method {method}
header_up X-Forwarded-Uri {uri}
# 성공 응답 시 응답 헤더 복사
@good status 2xx
handle_response @good {
# 예: 각 copy_headers 필드에 대해...
request_header Remote-User {rp.header.Remote-User}
request_header Remote-Email {rp.header.Remote-Email}
}
}
예시 (Examples)
Authelia
앱을 리버스 프록시로 서빙하기 전에 Authelia로 인증을 위임해요:
# 인증 게이트웨이 자체를 서빙
auth.example.com {
reverse_proxy authelia:9091
}
# 앱을 서빙
app1.example.com {
forward_auth authelia:9091 {
uri /api/authz/forward-auth
copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
}
reverse_proxy app1:8080
}
자세한 내용은 Caddy와의 연동에 대한 Authelia 문서를 참고해요.
Tailscale
Tailscale(현재 이름은 nginx-auth지만 Caddy에서도 여전히 동작해요)로 인증을 위임하고, copy_headers의 대체 문법을 사용해 복사된 헤더를 이름 변경해요(각 헤더의 >에 주의):
forward_auth unix//run/tailscale.nginx-auth.sock {
uri /auth
header_up Remote-Addr {remote_host}
header_up Remote-Port {remote_port}
header_up Original-URI {uri}
copy_headers {
Tailscale-User>X-Webauth-User
Tailscale-Name>X-Webauth-Name
Tailscale-Login>X-Webauth-Login
Tailscale-Tailnet>X-Webauth-Tailnet
Tailscale-Profile-Picture>X-Webauth-Profile-Picture
}
}