document-haness/docs/keycloak/tech-log-studio/oauth-oidc-auth-boundary/reference/reference-idp-federation-boundary.md

id, kind, slug, title, topic, topicName, project, status, version, verifiedOn, studio, public, sourceRevision, source

id	kind	slug	title	topic	topicName	project	status	version	verifiedOn	studio	public	sourceRevision	source
1a00a640-8987-4075-a9e4-7ec023cdffbb	REFERENCE	external-idp-federation-application-boundary	외부 IdP 연동과 Application 인증 구조의 경계	oauth-oidc-auth-boundary	OAuth/OIDC 인증 경계	KeyCloak Patterns	게시 중	27	2026-08-30	https://hyeonworks.com/studio/documents/1a00a640-8987-4075-a9e4-7ec023cdffbb/edit	https://hyeonworks.com/references/external-idp-federation-application-boundary	keycloak-patterns-lab@2026-08	final/document.md#선택이-코드와-흐름에-반영되는-방식-google-login

외부 IdP 연동과 Application 인증 구조의 경계

Google 로그인을 붙였다고 해서 SPA, Mediator, BFF, OAuth2-Proxy에 이어 다섯 번째 인증 구조가 새로 생기는 것은 아니다. 사용자가 Google에서 인증을 마치면 Keycloak이 그 결과를 받아 사용자를 확인하고, 애플리케이션에는 Keycloak 자신이 발급한 Authorization Code를 전달한다.

관계

• 외부 IdP와의 연동이라도 별도의 인증 방식이 아니다. 이 기준을 프로젝트 결정으로 굳힌 기록이다.
• SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계 브로커가 만든 authorization code를 애플리케이션이 받는 흐름이다.
• Authorization Code Flow의 Endpoint와 Credential 이동 기준 외부 IdP를 붙여도 애플리케이션이 오가는 endpoint의 순서는 바뀌지 않는다.

목적

외부 IdP(Identity Provider)는 Keycloak 앞에 서서 사용자 인증을 실제로 수행하는 인증 공급자이고, Google이 그중 하나다. 사용자가 Keycloak 로그인 화면에서 Google을 고르면 브라우저는 Google로 이동해 인증을 마치고, Keycloak이 그 결과를 확인해 자신이 가진 사용자 정보와 연결한다. 그런 다음 Keycloak이 애플리케이션에 자신이 발급한 Authorization Code를 전달한다.

그래서 Google 같은 외부 IdP를 추가해도 애플리케이션의 인증 구조는 달라지지 않는다. 토큰을 브라우저가 직접 받을지 서버에서 관리할지, 브라우저와 서버 중 어느 계층이 Resource Server의 API를 호출할지는 기존 SPA, Mediator, BFF, OAuth2-Proxy 구조 중 무엇을 골랐는지가 정한다.

규칙

1. 외부 IdP 인증과 애플리케이션 인증 구조를 나눈다

외부 IdP는 Keycloak 앞에서 사용자 인증을 맡고, 애플리케이션이 고른 SPA, Mediator, BFF, OAuth2-Proxy 구조는 Keycloak에서 인증이 끝난 뒤 토큰과 API 호출을 어떻게 처리할지를 정한다.

Google에서 인증이 끝나면 그 결과는 먼저 Keycloak이 검증한다. 이후 애플리케이션이 쓰는 Authorization Code와 토큰은 Google이 아니라 Keycloak이 발급한 것이고, Resource Server가 검증하는 토큰도 Keycloak이 발급한 것이다.

로그인 화면에서 Google이나 다른 IdP를 고르게 하거나, IdP마다 다른 계정을 Keycloak 사용자와 어떻게 연결할지를 따로 처리하는 것은 자연스럽다. 다만 Resource Server가 Google이 발급한 토큰과 Keycloak이 발급한 토큰을 각각 다르게 검증하거나, 애플리케이션의 인가 로직이 로그인에 쓴 IdP에 따라 갈리기 시작한다면 외부 IdP와 애플리케이션을 갈라놓던 Keycloak의 역할이 제대로 지켜지고 있는지 확인할 필요가 있다.

2. 외부 계정은 IdP와 subject 조합으로 식별한다

이메일 주소는 바뀔 수 있고 다른 계정과 겹칠 가능성도 있어서 외부 계정을 식별하고 연결하는 기준으로 쓰기에 적절하지 않다.

대신 어떤 IdP에서 인증했는지와 그 IdP가 사용자에게 부여한 고유 식별자(subject)를 함께 써서 외부 계정을 식별한다. 예를 들어 Google 사용자는 Google + subject의 조합으로 구분한다.

이메일만 기준으로 계정을 연결하면 사용자가 이메일 주소를 바꿨을 때 기존 계정과의 연결을 찾지 못하거나, 같은 이메일을 가진 다른 계정을 잘못 연결할 수 있다.

3. 이메일 충돌은 별도의 계정 연결 문제로 다룬다

외부 IdP가 전달한 이메일 주소가 기존 계정의 이메일과 같더라도, 이메일이 같다는 사실만으로 두 계정이 같은 사용자의 것이라고 확신할 수 없기 때문에 자동으로 연결하지 않는다.

계정을 연결해야 한다면 기존 계정으로 다시 로그인하게 하거나 추가 인증을 요구하는 등, 사용자가 그 계정의 실제 소유자인지 확인하는 절차를 따로 거친다.

4. mock provider 테스트와 실제 IdP 검증을 구분한다

지금까지 mock provider로 확인한 것은 Keycloak이 외부 IdP의 인증 결과를 정상적으로 받아들이는지와, 필요한 사용자 정보가 올바르게 매핑되는지까지다.

mock provider 테스트만으로는 실제 외부 IdP와의 연동까지 검증할 수 없다. 실제 계정으로 로그인하는 과정과 공개 HTTPS 콜백, 사용자 동의(Consent) 화면, 외부 IdP가 적용하는 도메인 정책 등은 아직 확인하지 않았다. 그래서 실제 외부 IdP를 연결해 전체 로그인 흐름을 따로 검증해야 한다.

적용 조건

• 외부 IdP를 붙일 때
• 계정 연결 규칙을 정할 때
• 검증 범위를 문서로 적을 때
• 브로커를 거치는 흐름과 직접 OIDC 흐름을 비교할 때

예외

• 애플리케이션이 Keycloak 같은 브로커를 거치지 않고 Google 등 외부 IdP와 직접 OIDC 연동을 한다면 이야기가 달라진다. 이때는 애플리케이션이 외부 IdP가 직접 발급한 토큰을 쓰므로, 그 외부 IdP를 신뢰하고 토큰을 검증한다.
• 조직에서 외부 IdP를 하나만 쓴다면 Keycloak 같은 브로커를 따로 두지 않고 애플리케이션이 그 IdP와 직접 연동하는 구조도 고를 수 있다. 이때는 여러 외부 IdP에서 들어온 계정을 하나의 내부 사용자와 어떻게 연결할지 정하는 계정 연결 정책이 대부분 필요 없다.

예시

• Google 로그인을 추가해도 애플리케이션이 고르는 것은 여전히 4가지 구조 중 하나다
• 브로커는 provider alias + upstream subject 조합을 기준으로 외부 계정을 식별한다
• 애플리케이션이 신뢰하는 issuer는 외부 IdP가 아니라 브로커다
• mock OIDC provider로 확인한 것은 브로커와 claim mapping 계약까지다