llm-wiki/raw/official-docs/keycloak-reverseproxy-official.md

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

- 같은 주제 다른 official-doc: [[raw/official-docs/keycloak-hostname-configuration]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-patterns]]
  - [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]]
  - [[raw/branch-notes/feature-keycloak-reverse-proxy-headers]]
  - [[raw/branch-notes/feature-keycloak-header-spoofing-defense]]
- 인용하는 wiki: (미작성)