Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

8.4 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

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:///realms/ // For Keycloak versions <17: --oidc-issuer-url=https:///auth/realms/"

[§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= // Optional, required realm role" + "--allowed-role=: // 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:///realms/ // For Keycloak versions <17: --oidc-issuer-url=https:///auth/realms/"	`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= // Optional, required realm role" + "--allowed-role=: // 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 도달 전에 차단.

같은 주제 다른 official-doc:
인용하는 branch:
- raw/branch-notes/feature-keycloak-edge-forwardauth-no-google (P1A)
- raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow
인용하는 wiki: (미작성)

8.4 KiB Raw Blame History