llm-wiki/raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official.md

---
title: OAuth2 Proxy — Keycloak OIDC Provider (Official Docs)
source_type: official-doc
url: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc
archive_url:
status: raw
confidence: high
tags: [keycloak-patterns, p1a-edge-forward-auth, oauth2-proxy, keycloak, oidc, official-doc]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-patterns, feature-keycloak-edge-forwardauth-no-google, feature-keycloak-oauth2-proxy-oidc-flow]
created: 2026-05-25
last_reviewed: 2026-05-27
---

# OAuth2 Proxy — Keycloak OIDC Provider (Official Docs)

> Layer: `raw/official-docs/` — oauth2-proxy 의 `keycloak-oidc` provider 공식 문서 (Keycloak 17+ context-path 변경 반영). P1A 패턴의 oauth2-proxy ↔ Keycloak 연결 + role/group 인가의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-patterns]] | keycloak-patterns root — oauth2-proxy 채택 시 `provider=keycloak-oidc` 가 정식 provider 라는 공식 사실 |
| [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] | P1A sub-branch — `--client-id`/`--client-secret`/`--oidc-issuer-url` 3종 필수 설정 + Keycloak native user store 만으로 인증 가능 |
| [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] | OIDC code flow 5단계 (oauth2-proxy → Keycloak token 교환) + 6단계 (role/group 통과 제어) 의 정확한 CLI 플래그 매핑 근거 |

## 컨텍스트 / 왜 저장했는지

P1A 토큰 sequence 5단계(oauth2-proxy → Keycloak token 교환) 와 6단계(role/group 기반 통과 제어)가 어떤 설정 키로 구현되는지 공식 근거. Keycloak realm role vs client role 구분 + group authorization 동작을 확인.

## 출처 / Source

- 원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc
- 아카이브 URL: (미수집)
- 저자 / 조직: oauth2-proxy maintainers
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Usage] "--provider=keycloak-oidc    --client-id=<your client's id>    --client-secret=<your client's secret>"

> [§Usage] "--oidc-issuer-url=https://<keycloak host>/realms/<your realm> // For Keycloak versions <17: --oidc-issuer-url=https://<keycloak host>/auth/realms/<your realm>"

> [§Authorization] "OAuth2 Proxy will perform authorization by requiring a valid user, this authorization can be extended to take into account a user's membership in Keycloak `groups`, `realm roles`, and `client roles`"

> [§Usage] "--allowed-role=<realm role name> // Optional, required realm role" + "--allowed-role=<client id>:<client role name> // Optional, required client role" + "--allowed-group=</group name> // Optional, requires group client scope"

> [§Groups] "Create a new Client Scope with the name **groups** in Keycloak. Include a mapper of type **Group Membership**."

> [§Usage] "--code-challenge-method=S256 // PKCE"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| O2PK-C1 | `provider=keycloak-oidc` 사용 시 `--client-id`, `--client-secret`, `--oidc-issuer-url` 3개가 oauth2-proxy ↔ Keycloak 연결의 필수 CLI 파라미터 | [§Usage] "--provider=keycloak-oidc    --client-id=<your client's id>    --client-secret=<your client's secret>" | `official-vendor-doc` | oauth2-proxy `keycloak-oidc` provider 설정 | client_secret 없는 public client (PKCE-only) 도 동일 provider 로 동작한다는 뜻은 아님 — Usage 예시는 confidential client 형식 |
| O2PK-C2 | Keycloak 17 이상은 issuer URL 패턴이 `https://<keycloak host>/realms/<your realm>`, 17 미만은 `/auth/realms/<your realm>` (legacy context path) | [§Usage] "--oidc-issuer-url=https://<keycloak host>/realms/<your realm> // For Keycloak versions <17: --oidc-issuer-url=https://<keycloak host>/auth/realms/<your realm>" | `official-vendor-doc` | Keycloak 17+ context-path 마이그레이션 영향 | 17+ 에서 `/auth` prefix 를 reverse-proxy 로 재추가했을 때의 동작은 본 인용 범위 밖 |
| O2PK-C3 | oauth2-proxy 의 기본 인가는 "valid user" 요구이며, Keycloak `groups`/`realm roles`/`client roles` 멤버십을 인가에 추가할 수 있다 | [§Authorization] "OAuth2 Proxy will perform authorization by requiring a valid user, this authorization can be extended to take into account a user's membership in Keycloak `groups`, `realm roles`, and `client roles`" | `official-vendor-doc` | oauth2-proxy authorization layer | 인가 실패 시 응답 코드(401 vs 403) 의 정확한 의미는 본 인용에 명시 없음 |
| O2PK-C4 | realm role 제한은 `--allowed-role=<realm role name>`, client role 제한은 `--allowed-role=<client id>:<client role name>` 형식. group 제한은 `--allowed-group=</group name>` 이며 group client scope 필요 | [§Usage] "--allowed-role=<realm role name> // Optional, required realm role" + "--allowed-role=<client id>:<client role name> // Optional, required client role" + "--allowed-group=</group name> // Optional, requires group client scope" | `official-vendor-doc` | RBAC at edge via oauth2-proxy | group 이름의 leading `/` 가 nested group path 를 의미하는지는 본 인용에 명시 없음 |
| O2PK-C5 | `--allowed-group` 동작을 위해 Keycloak 측에 이름 `groups` 의 Client Scope + `Group Membership` 타입 mapper 가 필요 | [§Groups] "Create a new Client Scope with the name **groups** in Keycloak. Include a mapper of type **Group Membership**." | `official-vendor-doc` | group-based authorization 활성화 | client scope 이름이 정확히 `groups` 가 아니면 동작 안 함을 보장하는 별도 절차 (default vs optional scope) 는 본 인용 범위 밖 |
| O2PK-C6 | oauth2-proxy 는 PKCE 를 위해 `--code-challenge-method=S256` 플래그 지원 | [§Usage] "--code-challenge-method=S256 // PKCE" | `official-vendor-doc` | oauth2-proxy → Keycloak code flow 의 PKCE 활성화 | confidential client 에서도 PKCE 강제가 권장이라는 뜻은 아님 — RFC 8252 / OAuth 2.1 별도 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `O2PK-C1`: `keycloak-oidc` provider 의 3가지 필수 파라미터
  - `O2PK-C2`: Keycloak 버전별 issuer URL 패턴 (17+ vs <17)
  - `O2PK-C3`: oauth2-proxy 의 인가 확장 가능 차원 (group/realm role/client role)
  - `O2PK-C4`: 인가 CLI 플래그 정확한 syntax
  - `O2PK-C5`: group authorization 의 Keycloak 측 사전 요구사항 (client scope + mapper)
- **이 자료가 증명하지 않는 것**:
  - confidential client vs public client 사용 시 `--client-secret` 의 의무 여부 (provider 코드 측면)
  - `groups` claim 의 issuer policy 변경 시 oauth2-proxy 의 fallback 동작
  - Keycloak federation (e.g., Google IdP brokering) 활성화 시 본 provider 의 동작 차이 (별도 P1B 문서)
  - role hierarchy / composite role 의 `--allowed-role` 매칭 동작
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - P1A 의 Keycloak 버전 (26.x 가정) → `/realms/` 형식 사용 확정
  - SPA + BFF 구도가 아닌 edge forward-auth 구도에서 oauth2-proxy 가 confidential client (client_secret 보유) 인지 확인
  - 실제 realm 의 user 가 `--allowed-role` 매칭 가능한 role 을 보유하는지 export 확인

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. P1A 결정 컨텍스트 해석.

- 본 패턴(P1A)은 Keycloak federation을 쓰지 않으므로, Keycloak realm의 native user store만 사용. Google federation은 P1B에서 다룸.
- `--oidc-issuer-url` 가 `/realms/<realm>` 으로 끝나야 함 — Keycloak 17+ 의 컨텍스트 변경(`/auth` prefix 제거)에 주의.
- 인증(authentication)과 인가(authorization)를 분리해서 표기:
  - 인증: OIDC code flow로 사용자 식별.
  - 인가: `--allowed-role` / `--allowed-group` 으로 oauth2-proxy 레벨에서 거부. backend 도달 전에 차단.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/oauth2-proxy-overview-config-official]]
  - [[raw/official-docs/oauth2-proxy-nginx-integration-official]]
  - [[raw/official-docs/keycloak-securing-apps-overview-official]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] (P1A)
  - [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]]
- 인용하는 wiki: (미작성)