Files

T

DongHyeonkaandClaude Opus 5 b2963105a8 docs(keycloak-session-store): import the session-storage lab as a new project

The keycloak project ended with four open questions that design could not
settle. A two-VM lab was built to answer them by measurement, and this is
that material: 26 experiments, 125 raw command outputs, 22 browser captures.

Follows the import procedure in README.md.

  source/     the originating repository verbatim — 78 documents, 28 SVGs,
              8 manifests, plus .source-revision recording the commit
  final/      the SSOT
    document.md   729 lines written from the 29 experiment documents, not
                  concatenated: what was predicted, what was measured, and
                  where the measurement itself was wrong
    evidence/raw    125 outputs, flattened to <experiment>__<file> because
                    the originals collided (01-baseline.txt appeared three
                    times) and the audit only globs the top level
    evidence/meta   one per raw file; command and exitCode are null and the
                    README says why rather than inventing them
    evidence/browser  22 captures
    assets/       three diagrams through techviz
    .techviz/     their VizSpecs

A separate project rather than an addition to keycloak: the B-layer answers
that project's four questions, but the A, C and D layers are about cluster
failure, SSO and operations, and one document.md should hold one subject.
The four question records there can point here through 관계.

Recorded rather than papered over: only three of the 28 diagrams were
remade. The repository forbids hand-drawn SVG and forbids titles inside the
canvas; all 28 originals carry both, so converting them is redrawing, not
reformatting. They stay in source/ and the gap is written into the document.

verify-pipeline.py passes. audit-records.py reports no issues.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-04 22:51:59 +09:00

4.4 KiB

Raw Blame History

id, kind, slug, title, topic, topicName, project, status, version, basisVersion, studio

id	kind	slug	title	topic	topicName	project	status	version	basisVersion	studio
d99fdec9-fe9e-4e0f-a50b-6fb9b9ed5719	CONCEPT	idp-brokering	외부 IdP Brokering의 동작	oauth-oidc-auth-boundary	OAuth/OIDC 인증 경계	KeyCloak Patterns	게시 전	4	Keycloak 26.7.0 identity brokering	https://hyeonworks.com/studio/documents/d99fdec9-fe9e-4e0f-a50b-6fb9b9ed5719/edit

외부 IdP Brokering의 동작

브로커는 외부 IdP의 응답을 검증해 자기 realm의 identity로 연결한 뒤, 자기가 만든 authorization code를 애플리케이션으로 보낸다. 애플리케이션이 받는 code와 token은 언제나 브로커가 발급한 것이므로, 외부 IdP를 붙여도 애플리케이션이 상대하는 issuer는 바뀌지 않는다.

관계

외부 IdP 연동과 Application 인증 구조의 경계 이 동작을 경계 기준으로 정리한 기록이다.
OAuth Token과 Application Session을 구분하는 기준 upstream IdP session과 애플리케이션 상태를 구분하는 기준이다.
Authorization Code Flow의 Endpoint와 Credential 이동 기준 브로커가 발급하는 code가 지나는 endpoint다.

본문

두 개의 OAuth 왕복이 이어진다

사용자가 브로커 로그인 화면에서 외부 IdP를 고르면 인증이 두 번 일어난다. 앞의 왕복은 브로커와 외부 IdP 사이이고, 뒤의 왕복은 애플리케이션과 브로커 사이다.

Google identity assertion
  → Keycloak broker validation
  → provider alias + upstream sub로 account identity 결정
  → Keycloak local user/session
  → Keycloak authorization code
  → AP1·AP2·AP3·AP4 중 선택한 downstream 경계

브라우저가 upstream authorization을 수행하고, 브로커가 그 응답을 검증해 local identity와 연결한다. 그다음 애플리케이션으로 나가는 데이터는 다시 브로커가 만든다.

애플리케이션이 상대하는 issuer는 그대로다

계층	무엇을 발급하나	누가 검증하나
외부 IdP	upstream identity assertion	브로커
브로커	authorization code, access·ID token	애플리케이션과 Resource Server

AP1 Resource Server가 검증하는 issuer도 브로커이고, AP2와 AP3가 교환하는 code의 issuer도 브로커이며, AP4의 oauth2-proxy가 연결하는 OIDC provider도 브로커다. 애플리케이션은 외부 IdP의 token을 받지 않는다.

그래서 소셜 로그인을 붙여도 브라우저가 token을 받는지, 어느 계층이 API를 부르는지는 바뀌지 않는다. 그 선택은 네 패턴 중 무엇을 골랐는지가 정한다.

account identity를 정하는 key

브로커가 upstream 사용자를 local user와 연결할 때 쓰는 안정적인 key는 provider alias와 upstream sub의 조합이다.

email은 key가 아니다. upstream email이 기존 계정과 같다는 이유만으로 자동 연결하면, 그 email의 소유권을 증명하지 않은 상태에서 계정이 합쳐진다. 계정 연결은 인증 구조와 분리된 별도 설계 항목이다.

경계를 섞으면 생기는 일

외부 IdP를 애플리케이션 인증 구조 하나로 세면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 된다. 두 경계는 검증 방법이 다르다.

비교표에 성격이 다른 항목이 끼어들고, 계정 연결 규칙도 인증 구조 이야기에 섞여서 따로 설계하지 않고 넘어가게 된다.

경계가 새는지는 다음 지점에서 본다. UI에서 provider를 고르게 하거나 provider별 계정 연결을 다루는 것은 자연스럽다. Resource Server의 token 검증이나 애플리케이션 인가가 upstream IdP별로 갈리기 시작하면 브로커 경계가 애플리케이션까지 새고 있는지 본다.

외부 IdP의 token을 애플리케이션이 직접 받아 검증하는 경로를 만들면 브로커가 하던 계정 연결과 정책 판단이 함께 빠진다.

현재 검증한 범위

지금 자동화는 controllable mock OIDC provider로 broker와 claim mapping 계약을 확인한다. 실제 Google 계정, public HTTPS callback, consent와 production domain policy를 통과했다는 뜻은 아니다.

upstream IdP 검증 범위와 애플리케이션 credential 경계를 분리해서 적어야 이 사실 경계가 유지된다.

4.4 KiB Raw Blame History