donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
55de4f55b037af9554af9007ce834030ac7e729e
llm-wiki/raw/official-docs/keycloak-reverseproxy-official.md
T

9.3 KiB
Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
Keycloak — Using a reverse proxy (official) official-doc https://www.keycloak.org/server/reverseproxy raw high
keycloak-patterns
p3b-single-ec2-google
reverse-proxy
proxy-headers
kc-proxy-headers
kc-hostname
keycloak-patterns
feature-keycloak-patterns
feature-keycloak-single-ec2-google-federation
feature-keycloak-reverse-proxy-headers
feature-keycloak-header-spoofing-defense
2026-05-25 2026-05-27

Keycloak — Reverse Proxy 운영 (공식)

Layer: raw/official-docs/ — Keycloak 공식 운영 가이드 발췌. P3B (단일 EC2 + nginx/Caddy 앞단 + Keycloak) 의 proxy header 신뢰·relative path·TLS termination 설정 근거. 검증된 요약은 /ingest 후 wiki/concepts/keycloak-reverse-proxy.md (가칭) 에 별도 작성.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns P3B 변형의 reverse proxy 기반 deployment 채택 근거
raw/branch-notes/feature-keycloak-single-ec2-google-federation nginx → Keycloak 8080 forward + KC_HOSTNAME/KC_HTTP_RELATIVE_PATH 설정 근거
raw/branch-notes/feature-keycloak-reverse-proxy-headers KC_PROXY_HEADERS=xforwarded 채택 + X-Forwarded-* 신뢰 모델 근거
raw/branch-notes/feature-keycloak-header-spoofing-defense KC_PROXY_TRUSTED_ADDRESSES 화이트리스트 도입 근거 (공식 spoofing 경고에 대응)

컨텍스트

P3B 단일 EC2 에서 한 호스트에 nginx (또는 Caddy) + Spring Boot + Keycloak 가 같이 떠 있다. 외부에서는 https://kc.example.com/keycloak/... 로 도달하고, 내부적으로 nginx 가 Keycloak (:8080) 에 reverse proxy. Google 이 redirect 할 broker endpoint URL 은 이 public URL 이어야 하고, Keycloak 이 발급하는 issuer / OIDC discovery URL 도 동일해야 한다 (그렇지 않으면 토큰 audience / issuer 불일치).

출처 / Source

  • 원본 URL: https://www.keycloak.org/server/reverseproxy
  • 아카이브 URL: (미수집)
  • 저자 / 조직: Keycloak (Red Hat) — Server Administration Documentation
  • 발행일: rolling docs
  • 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§proxy-headers] forwarded enables parsing of the Forwarded header as per RFC 7239.

[§proxy-headers] xforwarded enables parsing of non-standard X-Forwarded-* headers, such as X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Prefix.

[§Header spoofing warning] "If this header is incorrectly configured, rogue clients can set this header and trick Keycloak into thinking the client is connected from a different IP address than the actual address."

[§TLS termination] "If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the http-enabled setting is required."

[§Trusted proxies] --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8

[§Subpath options] "Use a simple hostname for the hostname option, xforwarded for the proxy-headers option, and have the proxy set the X-Forwarded-Prefix header"

[§Subpath options] "Change the context path of Keycloak itself to match the context path for the reverse proxy using the http-relative-path option."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
KC-RP-C1 proxy-headers=forwarded 는 RFC 7239 표준 Forwarded 헤더를 파싱 [§proxy-headers] "forwarded enables parsing of the Forwarded header as per RFC 7239." official-vendor-doc Keycloak (Quarkus distro) reverse proxy 운영 모든 proxy 가 RFC 7239 Forwarded 를 정확히 emit 한다는 뜻은 아님 — proxy 측 설정 의존
KC-RP-C2 proxy-headers=xforwarded 는 비표준 X-Forwarded-For/Proto/Host/Port/Prefix 헤더를 파싱 [§proxy-headers] "xforwarded enables parsing of non-standard X-Forwarded-* headers, such as X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Prefix." official-vendor-doc nginx / Caddy / Traefik 등 X-Forwarded-* 만 emit 하는 proxy 헤더 신뢰는 별도 (trusted addresses 필요) — 본 옵션은 파싱 활성화 뿐
KC-RP-C3 proxy 헤더가 잘못 구성되면 rogue client 가 헤더를 위조하여 Keycloak 을 다른 IP 에서 접속한 것처럼 속일 수 있음 (공식 경고) [§Header spoofing warning] "If this header is incorrectly configured, rogue clients can set this header and trick Keycloak into thinking the client is connected from a different IP address than the actual address." official-vendor-doc proxy 가 없는데 KC_PROXY_HEADERS 가 켜진 경우, 또는 신뢰 IP 목록이 누락된 경우 spoofing 방어책의 모든 디테일은 별도 (예: 신뢰 IP 외에 mTLS, network segmentation 도 가능)
KC-RP-C4 reverse proxy 에서 TLS edge termination 시 http-enabled 설정으로 HTTP 활성화가 필수 [§TLS termination] "If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the http-enabled setting is required." official-vendor-doc edge termination (Cloudflare / nginx / Caddy / LB) 시나리오 TLS passthrough 모드에서는 http-enabled 불필요 — 본 인용 범위 밖
KC-RP-C5 --proxy-trusted-addresses (=KC_PROXY_TRUSTED_ADDRESSES) 로 신뢰할 proxy IP/CIDR 화이트리스트 지정 [§Trusted proxies] "--proxy-trusted-addresses=192.168.0.32,127.0.0.0/8" official-vendor-doc 동일 호스트 nginx (127.0.0.1), 동일 VPC LB 등 화이트리스트 외 IP 가 proxy 헤더를 emit 했을 때의 정확한 동작 (drop / ignore / log) 은 본 인용에 없음
KC-RP-C6 subpath 노출 방법 2가지: (A) proxy 가 X-Forwarded-Prefix 주입 + Keycloak xforwarded, (B) Keycloak 자체에 http-relative-path 설정 [§Subpath options] "Use a simple hostname for the hostname option, xforwarded for the proxy-headers option, and have the proxy set the X-Forwarded-Prefix header" + "Change the context path of Keycloak itself to match the context path for the reverse proxy using the http-relative-path option." official-vendor-doc https://host/keycloak/... subpath 노출 시 두 방법의 정확한 trade-off (admin console URL, OIDC discovery 경로 영향 등) 비교는 본 인용에 부분만 있음

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • KC-RP-C1~C2: KC_PROXY_HEADERS 옵션 값과 파싱 대상 헤더
    • KC-RP-C3: spoofing 위험에 대한 공식 경고 자체
    • KC-RP-C4: edge termination 시 http-enabled 필수
    • KC-RP-C5~C6: 신뢰 IP 옵션과 subpath 노출 2가지 방법
  • 이 자료가 증명하지 않는 것:
    • KC_HOSTNAME / hostname-v2 의 동작 디테일 (별도 페이지 keycloak-hostname-official 참조)
    • iss claim 이 KC_HOSTNAME 과 정확히 어떻게 결합되는지 (issuer URL 생성 규칙)
    • nginx / Caddy / Traefik 각각의 X-Forwarded-* 주입 기본값 / 정확한 directive
    • Google OAuth redirect URI 검증이 forwarded host 와 어떻게 상호작용하는지
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • 단일 EC2 환경에서 KC_PROXY_TRUSTED_ADDRESSES=127.0.0.1 로 충분한지 (loopback 만 신뢰 ⇒ 같은 호스트 nginx 만 헤더 신뢰)
    • /keycloak/ subpath + KC_HTTP_RELATIVE_PATH 조합에서 OIDC discovery (.well-known/openid-configuration) endpoint 경로 변화 검증
    • Caddy 가 기본으로 emit 하는 X-Forwarded-* 헤더 셋이 Keycloak 의 파싱 기대치와 일치하는지

P3B 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아니라 P3B 결정 컨텍스트 해석. wiki 추출 시 wiki/concepts/ 또는 wiki/projects/ source-summary 로 옮겨야 함.

  • nginx 가 EC2 80/443 listen → Keycloak :8080 HTTP forward → Keycloak KC_HTTP_ENABLED=true + KC_PROXY_HEADERS=xforwarded + KC_HOSTNAME=https://kc.example.com + KC_HTTP_RELATIVE_PATH=/keycloak.
  • Google 이 redirect 할 broker endpoint URL: https://kc.example.com/keycloak/realms/{realm}/broker/google/endpoint. 이 URL 이 Google Console authorized redirect URI 에 등록되어야 함.
  • EC2 가 단일 호스트이므로 신뢰 프록시 (= 같은 호스트 nginx) 만 헤더 주입 → KC_PROXY_TRUSTED_ADDRESSES=127.0.0.1 권장.

메모 / Notes

  • 2026-05-27 재검증: 모든 핵심 인용 verbatim 으로 메인 페이지에 존재 확인. --proxy-trusted-addresses 의 예시 IP 192.168.0.32,127.0.0.0/8 도 공식 예시 그대로.
  • 후속: keycloak-hostname-configuration.md (hostname-v2) 와 합쳐서 wiki/concepts 추출 — issuer URL 생성 규칙 통합 정리.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink