86 lines
5.8 KiB
Markdown
86 lines
5.8 KiB
Markdown
---
|
|
id: 1a00a640-8987-4075-a9e4-7ec023cdffbb
|
|
kind: REFERENCE
|
|
slug: external-idp-federation-application-boundary
|
|
title: 외부 IdP 연동과 Application 인증 구조의 경계
|
|
topic: oauth-oidc-auth-boundary
|
|
topicName: OAuth/OIDC 인증 경계
|
|
project: KeyCloak Patterns
|
|
status: 게시 중
|
|
version: 27
|
|
verifiedOn: 2026-08-30
|
|
studio: "https://hyeonworks.com/studio/documents/1a00a640-8987-4075-a9e4-7ec023cdffbb/edit"
|
|
public: "https://hyeonworks.com/references/external-idp-federation-application-boundary"
|
|
sourceRevision: keycloak-patterns-lab@2026-08
|
|
source:
|
|
- 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은 그 결과를 검증해 realm 사용자와 연결한 뒤 자신이 발급한 Authorization Code를 애플리케이션에 전달한다.
|
|
|
|
Google 같은 외부 IdP가 추가돼도 애플리케이션이 상대하는 OAuth 경계는 Keycloak이다. 토큰을 브라우저가 받을지 서버가 관리할지와 Resource Server를 누가 호출할지는 기존 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이 발급한 것이다.
|
|
|
|
로그인 화면에서 IdP를 고르는 일과 외부 계정을 Keycloak 사용자에 연결하는 일은 broker 경계 안에 있다. Resource Server가 Google token과 Keycloak token을 따로 검증하거나 애플리케이션 인가가 로그인 IdP에 따라 갈리기 시작하면 이 경계가 애플리케이션까지 확장된 것이다.
|
|
|
|
### 2. 외부 계정은 IdP와 subject 조합으로 식별한다
|
|
|
|
이메일 주소는 바뀔 수 있고 다른 계정과 겹칠 가능성도 있어서 외부 계정을 식별하고 연결하는 기준으로 쓰기에 적절하지 않다.
|
|
|
|
대신 어떤 IdP에서 인증했는지와 그 IdP가 사용자에게 부여한 고유 식별자(subject)를 함께 써서 외부 계정을 식별한다. 예를 들어 Google 사용자는 Google + subject의 조합으로 구분한다.
|
|
|
|
이메일만 기준으로 계정을 연결하면 사용자가 이메일 주소를 바꿨을 때 기존 계정과의 연결을 찾지 못하거나, 같은 이메일을 가진 다른 계정을 잘못 연결할 수 있다.
|
|
|
|
### 3. 이메일 충돌은 별도의 계정 연결 문제로 다룬다
|
|
|
|
외부 IdP가 전달한 이메일이 기존 계정과 같아도 자동으로 연결하지 않는다. 같은 이메일이라는 사실만으로 두 계정의 소유자가 같다고 확인할 수 없기 때문이다.
|
|
|
|
계정 연결에는 기존 계정 재로그인이나 추가 인증처럼 기존 계정의 소유권을 확인하는 절차가 별도로 필요하다.
|
|
|
|
### 4. mock provider 테스트와 실제 IdP 검증을 구분한다
|
|
|
|
현재 확인 범위는 mock provider를 이용한 broker 동작과 claim mapping 계약까지다.
|
|
|
|
실제 계정 로그인, 공개 HTTPS callback, 사용자 동의(Consent), 외부 IdP의 도메인 정책은 확인하지 않았다. 따라서 mock provider 검증 결과를 실제 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 계약까지다
|