6.8 KiB
id, kind, slug, title, topic, project, status, version, verifiedOn, studio, public
| id | kind | slug | title | topic | project | status | version | verifiedOn | studio | public |
|---|---|---|---|---|---|---|---|---|---|---|
| 1a00a640-8987-4075-a9e4-7ec023cdffbb | REFERENCE | external-idp-federation-application-boundary | 외부 IdP 연동과 Application 인증 구조의 경계 | 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 |
외부 IdP 연동과 Application 인증 구조의 경계
Google 로그인을 추가한다고 해서 새로운 다섯 번째 인증 구조가 생기는 것은 아니다. 사용자가 Google에서 인증을 마치면 Keycloak이 그 인증 결과를 받아 사용자를 확인하고, 애플리케이션에는 자신의 Authorization Code를 발급한다.
그 이후의 흐름은 기존과 같다. 애플리케이션은 여전히 Keycloak을 기준으로 인증을 처리하고, Token을 브라우저에서 관리할지 서버에서 관리할지에 따라 앞에서 구분한 네 가지 구조 중 하나를 사용한다.
관계
- 외부 IdP와의 연동이라도 별도의 인증 방식이 아니다. 이 기준을 프로젝트 결정으로 굳힌 기록이다.
- SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계 브로커가 만든 authorization code를 애플리케이션이 받는 흐름이다.
- Authorization Code Flow의 Endpoint와 Credential 이동 기준 외부 IdP가 있어도 애플리케이션 쪽 endpoint 이동은 그대로다.
목적
Google은 Keycloak 앞에서 실제 사용자 인증을 담당하는 외부 IdP다. 사용자가 Keycloak 로그인 화면에서 Google을 선택하면 브라우저는 Google로 이동해 인증을 진행한다. 인증이 완료되면 Keycloak이 그 결과를 확인하고 자신의 사용자 정보와 연결한 뒤, 애플리케이션에는 Keycloak이 발급한 Authorization Code를 전달한다.
따라서 Google과 같은 외부 IdP를 추가하더라도 애플리케이션의 인증 구조가 달라지는 것은 아니다. Token을 브라우저가 직접 받을지 서버에서 관리할지, 그리고 브라우저와 서버 중 어느 계층이 Resource Server의 API를 호출할지는 기존 SPA, Mediator, BFF, OAuth2-Proxy 구조 중 어떤 방식을 선택했는지에 따라 결정된다.
규칙
1. 외부 IdP 인증과 애플리케이션 인증 구조를 나눈다
외부 IdP는 Keycloak 앞에서 사용자 인증을 담당한다. 애플리케이션이 선택하는 SPA, Mediator, BFF, OAuth2-Proxy 구조는 Keycloak에서 인증이 끝난 이후 Token과 API 호출을 어떻게 처리할지를 정한다.
Google에서 인증이 완료되면 그 결과는 먼저 Keycloak이 검증한다. 이후 애플리케이션은 Google이 아니라 Keycloak이 발급한 Authorization Code와 Token을 사용한다. Resource Server 역시 Keycloak이 발급한 Token을 검증한다. 따라서 Google 로그인을 추가하더라도 애플리케이션의 OAuth 처리 방식은 기존 SPA, Mediator, BFF, OAuth2-Proxy 구조를 그대로 따른다.
로그인 화면에서 Google이나 다른 Provider를 선택하게 하거나, Provider별 계정을 Keycloak 사용자와 어떻게 연결할지를 별도로 처리하는 것은 자연스럽다. 하지만 Resource Server가 Google과 Keycloak의 Token을 각각 다르게 검증하거나, 애플리케이션의 인가 로직이 로그인에 사용한 Provider에 따라 달라지기 시작한다면 외부 IdP와 애플리케이션 사이를 분리하던 Keycloak의 역할이 제대로 유지되고 있는지 확인할 필요가 있다.
2. 외부 계정은 provider와 subject 조합으로 식별한다
이메일 주소는 변경될 수 있고 다른 계정과 중복될 가능성도 있기 때문에 외부 계정을 식별하고 연결하는 기준으로 사용하기에는 적절하지 않다.
대신 어떤 Provider에서 인증했는지와 해당 Provider가 사용자에게 부여한 고유 식별자(subject)를 함께 사용해 외부 계정을 식별한다.
예를 들어 Google 사용자는 Google + subject의 조합으로 구분한다.
이메일만을 기준으로 계정을 연결하면 사용자가 이메일 주소를 변경했을 때 기존 계정과의 연결을 찾지 못하거나, 동일한 이메일을 가진 다른 계정을 잘못 연결할 수 있다.
3. email 충돌은 별도의 계정 연결 문제로 다룬다
외부 IdP에서 전달받은 이메일 주소가 기존 계정의 이메일과 같더라도 두 계정을 자동으로 연결하지 않는다. 이메일이 같다는 사실만으로 두 계정이 같은 사용자의 것이라고 확신할 수 없기 때문이다.
계정을 연결해야 한다면 기존 계정으로 다시 로그인하거나 추가 인증을 요구하는 등, 사용자가 해당 계정의 실제 소유자임을 확인하는 별도의 절차를 거친다.
4. mock provider 테스트와 실제 IdP 검증을 구분한다
현재는 Mock Provider를 사용해 Keycloak이 외부 IdP의 인증 결과를 정상적으로 받아들이는지와 필요한 사용자 정보가 올바르게 매핑되는지까지 확인했다.
하지만 Mock Provider 테스트만으로 실제 외부 IdP와의 연동까지 검증할 수는 없다. 실제 계정으로 로그인하는 과정과 공개 HTTPS Callback, 사용자 동의(Consent) 화면, 외부 IdP가 적용하는 도메인 정책 등은 아직 확인하지 않았다. 그래서 실제 외부 IdP를 연결해 전체 로그인 흐름을 별도로 검증해야 한다.
적용 조건
- 외부 IdP를 붙일 때
- 계정 연결 규칙을 정할 때
- 검증 범위를 문서로 적을 때
- 브로커를 거치는 흐름과 직접 OIDC 흐름을 비교할 때
예외
-
애플리케이션이 Keycloak과 같은 브로커를 거치지 않고 Google 등의 외부 IdP와 직접 OIDC 연동을 한다면 상황이 달라진다. 이 경우 애플리케이션은 외부 IdP가 직접 발급한 Token을 사용하므로, 해당 외부 IdP를 신뢰하고 Token을 검증하게 된다.
-
조직에서 하나의 외부 IdP만 사용한다면 Keycloak과 같은 별도의 브로커를 두지 않고 애플리케이션이 해당 IdP와 직접 연동하는 구조도 선택할 수 있다.
이 경우 여러 외부 IdP에서 들어온 계정을 하나의 내부 사용자와 어떻게 연결할지 결정하는 계정 연결 정책은 대부분 필요 없다.
예시
- Google 로그인을 추가해도 애플리케이션이 고르는 것은 여전히 4가지 구조 중 하나다
- 브로커는
provider alias + upstream subject조합을 기준으로 외부 계정을 식별한다. - 애플리케이션이 신뢰하는 issuer는 외부 IdP가 아니라 브로커다
- mock OIDC provider로 확인한 것은 브로커와 claim mapping 계약까지다