DongHyeonkaandClaude Fable 5.1
4d50bb939a
- 계약 채택 — 독자 질문, 후보 29건(PROMOTE 24 · MERGE_INTO 4 · KEEP_IN_SSOT 1). 게시 중 17건은 전부 유지. 저장소 keycloak-pattern 은 패턴 넷이 브랜치로 갈라져 있어 revisions 로 tip 넷을 적었다. keycloak-session-store 는 같은 저장소 @ cdac9b8 - 게시된 기록의 redirect_uri 가 SSOT·코드와 달랐다 — OAuth2callback.html → callback.html (frontend/src/app.js 에서 확인). 계약 title 이 기록과 다른 7건도 기록 쪽으로 맞췄다 - 미작성 1건 작성 — 패턴 검증을 실제로 돌릴 때의 안전한 순서(Reference) - 리뷰 100건 반영 — 설명 뒤에 붙은 평가·차례 예고·독자 오해 가정·작성 지시를 지웠다. 삭제가 남긴 조각 4건을 고치고, 원래부터 잘려 있던 로컬 미리보기 라벨 1건도 닫았다 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
5.5 KiB
id, kind, slug, title, topic, topicName, project, status, version, basisVersion, studio, sourceRevision, source
| id | kind | slug | title | topic | topicName | project | status | version | basisVersion | studio | sourceRevision | source | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 | keycloak-patterns-lab@2026-08 |
|
외부 IdP Brokering의 동작
브로커링(brokering)은 브로커가 외부 IdP(Identity Provider)의 인증 결과를 대신 받아 검증하고, 자기 realm 안의 사용자와 연결하는 동작이다. 연결이 끝나면 브로커는 자기가 만든 authorization code를 애플리케이션으로 보낸다. 애플리케이션이 받는 코드와 토큰은 언제나 브로커가 발급한 것이라, 외부 IdP를 붙여도 애플리케이션이 상대하는 issuer, 곧 그 토큰을 발급한 주체는 바뀌지 않는다.
관계
- 외부 IdP 연동과 Application 인증 구조의 경계 이 동작을 경계 기준으로 정리한 기록이다.
- OAuth Token과 Application Session을 구분하는 기준 외부 IdP 세션과 애플리케이션 상태를 구분하는 기준이다.
- Authorization Code Flow의 Endpoint와 Credential 이동 기준 브로커가 발급하는 코드가 지나는 endpoint다.
본문
두 개의 OAuth 왕복이 이어진다
사용자가 브로커 로그인 화면에서 어느 외부 IdP로 로그인할지 고르면 인증 왕복이 두 번 일어난다. 앞의 왕복은 브로커와 외부 IdP 사이에서, 뒤의 왕복은 애플리케이션과 브로커 사이에서 일어난다. 브로커보다 앞에 있는 외부 IdP 쪽을 upstream이라고 부른다.
먼저 브라우저가 외부 IdP에 authorization 요청을 보내고, 브로커는 돌아온 응답을 검증해 자기 realm의 사용자와 연결한다. 그다음 애플리케이션으로 나가는 값은 브로커가 다시 만든다. 무엇이 무엇으로 바뀌는지 순서로 적으면 이렇다.
Google identity assertion
→ Keycloak broker validation
→ provider alias + upstream sub로 account identity 결정
→ Keycloak local user/session
→ Keycloak authorization code
→ AP1·AP2·AP3·AP4 중 선택한 downstream 경계
외부 IdP가 보낸 것은 첫 줄의 Google identity assertion 하나이고, 그 아래 Keycloak local user/session과 Keycloak authorization code는 브로커가 만든다.
애플리케이션이 상대하는 issuer는 그대로다
AP1의 Resource Server가 검증하는 issuer도 브로커이고, AP2와 AP3가 주고받는 authorization code의 issuer도 브로커이며, AP4의 oauth2-proxy가 OIDC(OpenID Connect) 공급자로 연결하는 곳도 브로커다. 외부 IdP가 발급한 토큰은 애플리케이션까지 내려가지 않는다.
| 계층 | 무엇을 발급하나 | 누가 검증하나 |
|---|---|---|
| 외부 IdP | upstream identity assertion | 브로커 |
| 브로커 | authorization code, access·ID token | 애플리케이션과 Resource Server |
그래서 소셜 로그인을 붙여도 브라우저가 토큰을 받는지, 어느 계층이 API를 부르는지는 달라지지 않는다. 그 둘은 AP1부터 AP4까지 네 패턴 중 무엇을 골랐는지가 정한다.
account identity를 정하는 key
브로커가 외부 IdP의 사용자를 자기 realm의 사용자와 연결할 때 쓰는 안정적인 키는 provider alias와 upstream sub를 묶은 값이다. alias는 브로커에 등록한 외부 IdP마다 붙인 이름이고, sub는 그 IdP가 사용자 한 명에게 부여하는 고유 식별자다.
이메일은 이 키가 아니다. 외부 IdP가 보낸 이메일이 기존 계정과 같다는 이유만으로 자동 연결하면, 그 이메일의 소유권을 증명하지 않은 채로 계정이 합쳐지기 때문이다. 계정 연결은 인증 구조와 떼어서 따로 설계할 항목이다.
경계를 섞으면 생기는 일
외부 IdP 연동을 다섯 번째 애플리케이션 인증 구조로 세면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 되는데, 두 경계는 검증 방법이 다르다. 그러면 비교표에 성격이 다른 항목이 끼어들고, 계정 연결 규칙도 인증 구조 이야기에 섞여서 따로 설계하지 않고 넘어가게 된다.
화면에서 어느 외부 IdP로 로그인할지 고르게 하거나 IdP마다 계정 연결을 다루는 것은 브로커가 하는 일이라 경계를 넘지 않는다. Resource Server의 토큰 검증이나 애플리케이션 인가가 외부 IdP별로 갈리기 시작하면, 브로커 경계가 애플리케이션까지 샜는지 확인한다. 외부 IdP의 토큰을 애플리케이션이 직접 받아 검증하는 경로를 만들면 브로커가 하던 계정 연결과 정책 판단도 함께 빠진다.
현재 검증한 범위
지금 자동화는 실제 Google 대신 controllable mock OIDC provider를 세워 브로커와 claim mapping 계약을 확인하도록 작성되어 있다. 실제 Google 계정과 공개 HTTPS redirect가 성공하는지는 증명하지 않았다. 사용자 동의와 운영 도메인 정책을 통과했다는 뜻도 아니다.
그래서 upstream IdP를 어디까지 검증했는지와 애플리케이션이 다루는 자격 증명 경계는 따로 적는다.