본문 바로가기
WIKI 기술 지식 베이스

Traefik ForwardAuth 미들웨어

원문 보기 위키 갱신

출처: Traefik ForwardAuth 미들웨어 (ForwardAuth Documentation)

본문

ForwardAuth

forwardAuth 미들웨어는 인증을 외부 서비스에 위임해요. 서비스가 2XX 코드로 응답하면 접근이 허용되고 원래 요청이 수행돼요. 그렇지 않으면 인증 서버의 응답이 반환돼요.

설정 예시

구조화 (YAML)

# example.com으로 인증 전달
http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"

구조화 (TOML)

# example.com으로 인증 전달
[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"

Labels

# example.com으로 인증 전달
labels:
  - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"

Tags

// example.com으로 인증 전달
{
  "Tags" : [
    "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  ]
}

Kubernetes

# example.com으로 인증 전달
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth

설정 옵션

| 필드 | 설명 | 기본값 | 필수 | | address | 인증 서버 주소. | "" | 예 | | trustForwardHeader | 모든 X-Forwarded-* 헤더를 신뢰해요. trustForwardHeader 옵션은 더 이상 사용되지 않으며(deprecated) 다음 주요 버전에서 제거될 예정이에요. 자세한 내용은 여기 | - | 아니요 | | authResponseHeaders | 인증 서버 응답에서 복사해 전달된 요청에 설정할 헤더 목록이에요. 기존에 충돌하는 헤더는 대체해요. | [] | 아니요 | | authResponseHeadersRegex | 인증 서버 응답에서 복사해 전달된 요청에 설정할 헤더와 일치시키는 정규식이에요. 정규식과 일치하는 모든 헤더를 제거한 뒤 적용돼요. 자세한 내용은 여기. | "" | 아니요 | | authRequestHeaders | 요청에서 인증 서버로 복사할 헤더 목록이에요. 인증 서버에 전달되지 않아야 할 헤더를 필터링할 수 있어요. 설정하지 않거나 비어 있으면 모든 요청 헤더가 전달돼요. | [] | 아니요 | | addAuthCookiesToResponse | 인증 서버에서 응답으로 복사할 쿠키 목록이에요. 전달된 응답에서 충돌하는 기존 쿠키는 대체해요. 구성된 목록과 일치하는 모든 백엔드 쿠키는 응답에 추가되지 않는다는 점을 참고하세요. | [] | 아니요 | | forwardBody | 본문을 보내려면 forwardBody 옵션을 true로 설정해요. 본문은 전달되기 전에 Traefik 내부에서 읽히므로, 이는 스트리밍을 깨뜨려요. | false | 아니요 | | maxBodySize | maxBodySize를 설정해 본문 크기를 바이트 단위로 제한해요. 본문이 이보다 크면 401(unauthorized)을 반환해요. 설정하지 않으면 요청 본문 크기에 제한이 없어 성능이나 보안 문제가 생길 수 있어요. 자세한 내용은 여기. | -1 | 아니요 | | maxResponseBodySize | maxResponseBodySize를 설정해 인증 서버로부터의 응답 본문 크기를 바이트 단위로 제한해요. 응답 본문이 이 제한을 초과하면 401(unauthorized)을 반환해요. 설정하지 않으면 응답 본문 크기에 제한이 없어 성능이나 보안 문제가 생길 수 있어요. 자세한 내용은 여기. | - | 아니요 | | headerField | 인증된 사용자를 저장할 헤더 필드를 정의해요. | "" | 아니요 | | preserveLocationHeader | Location 헤더를 그대로 클라이언트로 전달할지, 아니면 인증 서버의 도메인 이름을 접두사로 붙일지 정의해요. | false | 아니요 | | preserveRequestMethod | 요청을 인증 서버로 전달할 때 원래 요청 메서드를 보존할지 여부를 정의해요. | false | 아니요 | | authSigninURL | 인증 서버가 401 Unauthorized를 반환할 때 리다이렉트할 URL을 지정해요. | "" | 아니요 | | tls.ca | 인증 서버와의 보안 연결에 사용되는 인증 기관의 경로를 설정해요. 기본값은 시스템 번들이에요. | "" | 아니요 | | tls.cert | 인증 서버와의 보안 연결에 사용되는 공개 인증서의 경로를 설정해요. 이 옵션을 사용할 때는 key 옵션을 설정해야 해요. | "" | 아니요 | | tls.key | 인증 서버와의 보안 연결에 사용되는 개인 키의 경로를 설정해요. 이 옵션을 사용할 때는 cert 옵션을 설정해야 해요. | "" | 아니요 | | tls.caSecret | 인증 서버와의 보안 연결에 사용되는 인증 기관을 담고 있는 secret을 정의해요. 기본값은 시스템 번들이에요. 이 옵션은 Kubernetes CRD에서만 사용할 수 있어요. | | 아니요 | | tls.certSecret | 인증 서버와의 보안 연결에 사용되는 개인 및 공개 인증서를 모두 담고 있는 secret을 정의해요. 이 옵션은 Kubernetes CRD에서만 사용할 수 있어요. | | 아니요 | | tls.insecureSkipVerify | TLS 연결 중 이 옵션이 true로 설정되면, 인증 서버는 서버가 제시하는 인증서를 호스트 이름과 무관하게 수락해요. | false | 아니요 |

authResponseHeadersRegex

헤더 키에 대한 정규식의 부분 일치를 허용해요. 헤더 키에 대한 완전 일치를 보장하려면 문자열 시작(^)과 끝($) 앵커를 사용해야 해요. 정규식과 대체는 Go Playground나 Regex101 같은 온라인 도구로 테스트할 수 있어요.

maxBodySize

maxBodySize 옵션은 인증 서버로 전달될 요청 본문의 최대 크기를 제어해요.

⚠️ 중요한 보안 고려 사항

기본적으로 maxBodySize는 설정되어 있지 않아서(값: -1) 요청 본문 크기에 제한이 없어요. 이는 심각한 보안 및 성능 문제를 일으킬 수 있어요:

  • 보안 위험: 공격자가 매우 큰 요청 본문을 보내 DoS 공격이나 메모리 고갈을 일으킬 수 있어요

  • 성능 영향: 큰 요청 본문은 메모리와 처리 리소스를 소비해 전체 시스템 성능에 영향을 줘요

  • 리소스 소비: 무제한 본문 크기는 예상치 못한 리소스 사용 패턴을 초래할 수 있어요

권장 구성

사용 사례에 맞는 적절한 maxBodySize 값을 설정하는 것을 강력히 권장해요:

# 대부분의 웹 애플리케이션용 (1MB 제한)
maxBodySize: 1048576  # 1MB (바이트)

# 더 큰 페이로드를 기대하는 API 엔드포인트용 (10MB 제한)  
maxBodySize: 10485760  # 10MB (바이트)

# 파일 업로드 인증용 (100MB 제한)
maxBodySize: 104857600  # 100MB (바이트)

maxBodySize 설정 지침

  • 웹 폼: 대부분의 폼 제출에는 1-5MB가 일반적으로 충분해요

  • API 엔드포인트: 가장 큰 예상 JSON/XML 페이로드 + 버퍼를 고려하세요

  • 파일 업로드: 최대 예상 파일 크기를 기준으로 설정하세요

  • 높은 트래픽 서비스: 리소스 고갈을 막기 위해 더 작은 제한을 사용하세요

maxResponseBodySize

maxResponseBodySize 옵션은 인증 서버로부터의 최대 허용 응답 본문 크기(바이트)를 정의해요. 응답 본문이 구성된 제한을 초과하면 요청은 401 (Unauthorized) 상태로 거부돼요. 설정하지 않으면 요청 본문 크기에 제한이 없어 성능이나 보안 문제가 생길 수 있어요.

경고

이 옵션을 적절한 값으로 설정하는 것을 강력히 권장해요. 설정하지 않으면(또는 -1로 설정하면) 무제한 응답 본문 크기가 허용되어 DoS 공격과 메모리 고갈로 이어질 수 있어요.

trustForwardHeader

경고

trustForwardHeader 옵션은 더 이상 사용되지 않으며 다음 주요 버전에서 제거될 예정이에요.

forwardedHeaders.trustedIPs를 사용해 EntryPoint 수준에서 신뢰된 IP들을 구성하고, 이 미들웨어에서 trustForwardHeader를 true로 설정하세요.

이 설정을 사용하면 EntryPoint가 들어오는 X-Forwarded-* 헤더를 정화하는 책임을 져요. 신뢰되지 않은 클라이언트가 보낸 그러한 헤더는 제거하고, 신뢰된 업스트림 프록시에서 온 것만 보존해요. ForwardAuth 미들웨어가 요청을 처리할 때쯤이면 모든 X-Forwarded-* 헤더가 신뢰할 수 있다고 보장돼요. 여기에는 체인에서 다른 미들웨어가 의도적으로 추가한 것도 포함돼요 — 예를 들어 StripPrefix 미들웨어가 설정하는 X-Forwarded-Prefix 헤더 같은 것들이요.

trustForwardHeader가 명시적으로 설정되지 않으면, Traefik은 시작 시 경고를 기록하고 일부 X-Forwarded-* 헤더(예: X-Forwarded-For, X-Forwarded-Proto)는 제거하지만 다른 것들(예: X-Forwarded-Prefix)은 그대로 전달하는 레거시 동작을 사용해요. 이 경고를 끄려면 trustForwardHeader를 명시적으로 true 또는 false로 설정하세요.

trustForwardHeader 옵션을 true로 설정하면 모든 X-Forwarded-* 헤더를 신뢰해요.

Forward-Request 헤더

다음 요청 속성들이 X-Forwarded- 헤더로 forward-auth 대상 엔드포인트에 제공돼요.

| 속성 | Forward-Request 헤더 | | HTTP 메서드 | X-Forwarded-Method | | 프로토콜 | X-Forwarded-Proto | | 호스트 | X-Forwarded-Host | | 요청 URI | X-Forwarded-Uri | | 소스 IP 주소 | X-Forwarded-For |

프로덕션에서 Traefik OSS를 사용 중이신가요?

직장에서 Traefik을 사용하고 있다면, 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS용 상용 지원을 추가하는 걸 고려해 보세요.

  • API Gateway 데모 영상 보기

  • 24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 추가하는 건 빠르고 매끄러워요. rip-and-replace 방식이 없고 모든 구성이 그대로 유지돼요. 짧은 영상으로 직접 확인해 보세요.

더 알아보기 (Learn more)