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, decisionStatus, decidedOn, studio, public, sourceRevision, source
| id | kind | slug | title | topic | topicName | project | status | version | decisionStatus | decidedOn | studio | public | sourceRevision | source | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 8c1ebea7-204e-445c-9812-0421d9eb0e9c | PROJECT_DECISION | federation-is-not-an-application-pattern | 외부 IdP와의 연동이라도 별도의 인증 방식이 아니다. | oauth-oidc-auth-boundary | OAuth/OIDC 인증 경계 | KeyCloak Patterns | 게시 중 | 17 | ADOPTED | 2026-08-24 | https://hyeonworks.com/studio/documents/8c1ebea7-204e-445c-9812-0421d9eb0e9c/edit | https://hyeonworks.com/projects/keycloak-patterns/decisions/federation-is-not-an-application-pattern | keycloak-patterns-lab@2026-08 |
|
외부 IdP와의 연동이라도 별도의 인증 방식이 아니다.
외부 IdP(Identity Provider, 인증 제공자)는 사용자 인증을 실제로 수행하는 쪽이고, Google이 그중 하나다. Keycloak은 Google의 인증 결과를 받아 애플리케이션이 사용할 토큰을 발급한다. 애플리케이션은 Google을 직접 신뢰하는 것이 아니라 Keycloak이 발급한 토큰을 기준으로 사용자를 인증한다. SPA(Single Page Application)나 BFF(Backend for Frontend) 같은 구조는 로그인한 사용자의 토큰과 세션을 어디에서 관리할지 정한다. 그래서 외부 IdP가 붙어도 애플리케이션의 인증 구조는 바뀌지 않는다.
근거
- 외부 IdP 연동과 Application 인증 구조의 경계 이 결정을 규칙 문장으로 적어 둔 기준이다.
- SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계 브로커가 발급한 Authorization Code를 받는 애플리케이션 경계다.
- OAuth Token과 Application Session을 구분하는 기준 upstream IdP 상태와 애플리케이션 상태를 같은 이름으로 부르지 않는다고 갈라 둔 기준이다.
결정문
외부 IdP 연동은 별도의 인증 구조가 아니다.
Google과 같은 외부 IdP는 사용자의 인증을 담당한다. Keycloak은 그 인증 결과를 받아 애플리케이션이 신뢰할 수 있는 토큰을 발급한다. SPA, Mediator, BFF, OAuth2-proxy와 같은 4가지 구조는 이렇게 발급된 토큰이나 세션을 애플리케이션에서 어디까지 노출하고 관리할지를 구분한다.
판단 이유
사용자가 Keycloak 로그인 화면에서 Google 로그인을 선택하면 브라우저는 Google의 Authorization Endpoint로 이동한다. Google에서 인증이 끝나면 그 결과는 Keycloak으로 돌아오고, Keycloak은 이 응답을 검증해 자신의 사용자 정보와 연결한다. 그다음 애플리케이션 콜백에는 Keycloak이 발급한 Authorization Code가 전달된다.
애플리케이션은 Google과 직접 토큰을 교환하지 않는다. Keycloak이 발급한 Authorization Code를 Keycloak의 Token Endpoint에서 토큰으로 교환한다. Resource Server가 검증하는 발급자(issuer)도 Google이 아니라 Keycloak이다. 애플리케이션은 Google이 발급한 토큰을 받지 않는다.
애플리케이션이 다루는 토큰을 Keycloak이 발급하기 때문에, Google 로그인을 추가해도 애플리케이션이 토큰을 관리하는 방식은 달라지지 않는다. SPA라면 여전히 브라우저에서 토큰을 관리하고, BFF라면 서버가 토큰을 관리하면서 API를 대신 호출한다.
Google을 다섯 번째 구조로 세면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 되는데, 두 경계는 검증하는 방법이 서로 다르다. 그래서 외부 IdP 연동과 애플리케이션 인증 구조는 별도의 경계로 나누어 설계하고 검증한다. 그 비교표도 처음에는 다른 모양이었다. 네 구조를 설명하는 용어부터 나란히 놓고 견주었는데, 용어만으로는 어느 계층이 Authorization Code를 교환하고 어느 계층이 API를 부르는지 보이지 않아 로그인과 API 요청을 맡는 구성요소를 같은 표에 놓았다.
영향
- Google을 추가해도 애플리케이션이 신뢰하고 토큰을 검증하는 대상은 계속 Keycloak이다. 토큰을 브라우저와 서버 중 어디에서 관리하고 어느 계층에서 API를 호출할지는 기존 4가지 구조가 그대로 정한다.
- 외부 IdP의 계정을 기존 사용자와 어떻게 연결할지는 인증 구조와 별개의 문제다. 외부 계정을 식별할 때는 Google과 같은 인증 제공자와 그 제공자가 부여한 사용자 고유 식별자를 함께 쓴다. 이메일 주소는 바뀔 수 있고 서로 다른 인증 제공자에서 같은 이메일을 쓸 수도 있어서, 이메일이 같다는 이유로 기존 계정에 자동으로 연결하지 않는다.
- 외부 IdP 연동은 테스트 환경에서 확인할 부분과 실제 서비스 환경에서 확인할 부분을 나눠서 검증한다. Mock Provider를 붙인 테스트에서는 Keycloak이 외부 IdP의 인증 결과를 제대로 받아들이는지, 필요한 사용자 정보가 제대로 매핑되는지 확인한다. 실제 Google과 같은 외부 IdP를 연동할 때는 실제 계정으로 로그인이 되는지, 공개 HTTPS 콜백이 정상 작동하는지, 사용자 동의 과정까지 진행되는지 확인해야 한다.
- Google과 같은 외부 IdP가 늘어나면 Keycloak에서 관리할 연동 설정도 같이 늘어난다. 이 설정을 애플리케이션 팀이 맡을지 별도의 인프라 팀이 맡을지는 아직 정하지 않았다.