108 lines
8.0 KiB
Markdown
108 lines
8.0 KiB
Markdown
---
|
|
title: Keycloak — Identity Brokering overview (official)
|
|
source_type: official-doc
|
|
url: https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker
|
|
archive_url:
|
|
status: raw
|
|
confidence: medium
|
|
tags: [broker-endpoint, google-federation, idp-brokering, keycloak, keycloak-patterns, official-doc, oidc, p1b-edge-google-federation, p2b-spa-google-federation, p3b-single-ec2-google]
|
|
related_projects: [keycloak-patterns]
|
|
related_branches: [feature-keycloak-patterns, feature-keycloak-single-ec2-google-federation, feature-keycloak-idp-brokering-google-client, feature-keycloak-first-broker-login-flow, feature-keycloak-google-redirect-uri-policy]
|
|
created: 2026-05-25
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Keycloak — Identity Brokering (공식, 개요)
|
|
|
|
> Layer: `raw/official-docs/` — Keycloak 공식 admin guide 의 Identity Brokering 섹션 발췌. P3B 의 Google federation 결정 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-keycloak-patterns]] | Keycloak 이 외부 IdP (Google 등) 를 broker 로 위임할 수 있다는 공식 근거 — P-pattern 분류의 federation 변형 (P1B/P2B/P3B) 정당화 |
|
|
| [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] | P3B 흐름에서 사용자가 "Google" 버튼 클릭 → Keycloak broker endpoint → Google → callback → Keycloak token 발급 흐름의 공식 정의 |
|
|
| [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]] | Keycloak Admin → Identity Providers → Google 추가 작업의 공식 컨텍스트 |
|
|
| [[raw/branch-notes/feature-keycloak-first-broker-login-flow]] | 외부 IdP 첫 로그인 시 신규 사용자 자동 생성 / 기존 사용자 link 분기의 공식 컨텍스트 |
|
|
| [[raw/branch-notes/feature-keycloak-google-redirect-uri-policy]] | Keycloak 이 표시하는 Redirect URI 를 Google Console Authorized redirect URI 에 등록하는 정책의 출처 |
|
|
|
|
## 컨텍스트
|
|
|
|
P3B = P3A + Google federation. SPA는 여전히 Keycloak에만 redirect (SPA flow 불변). Keycloak 로그인 화면에서 사용자가 "Google" identity provider 선택 → Keycloak이 Google로 redirect → Google 인증 후 callback → Keycloak이 자체 사용자에 매핑 → SPA에 Keycloak token 발급.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
|
|
- 발행일: rolling docs
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Identity Brokering Overview] "Keycloak can be configured to delegate authentication to one or more IDPs. Social login via Facebook or Google is an example of identity provider federation."
|
|
|
|
> [§Identity Brokering — broker endpoint URL, **needs-confirmation**] 공식 admin guide 의 broker endpoint URL 포맷 (`/realms/{realm}/broker/{provider}/endpoint`) 은 2026-05-25 발췌 당시 본 페이지에서 직접 verbatim 회수 실패. Admin UI 표시 / 다수 공식 tutorial 의 관행적 일치 (관행 근거) — 본 raw 문서의 verbatim 발췌로는 보장 안 됨.
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| KC-IDP-BROKER-C1 | Keycloak 은 하나 이상의 외부 IDP 로 인증을 위임 (delegate) 하도록 구성 가능하며 Google/Facebook social login 이 그 예시 | [§Identity Brokering Overview] "Keycloak can be configured to delegate authentication to one or more IDPs. Social login via Facebook or Google is an example of identity provider federation." | `official-vendor-doc` | Keycloak Admin UI 에서 Identity Provider 등록이 가능한 모든 realm | Google 외 다른 IdP (Azure AD, Okta, 사내 OIDC 등) 의 정확한 등록 절차 / claim 처리 디테일은 본 인용 범위 밖 |
|
|
| KC-IDP-BROKER-C2 | broker endpoint URL 포맷 `/realms/{realm}/broker/{provider}/endpoint` 은 본 페이지의 verbatim 발췌로는 확인되지 않음 (운영 관행 / Admin UI 표시 / tutorial 일치로만 알려짐) | (verbatim 부재 — 부재 자체가 claim) | `needs-confirmation` | P3B / P2B 의 Google Redirect URI 등록 작업 | 해당 URL 포맷이 틀렸다는 뜻은 아님. 단지 본 raw 문서의 인용 범위가 직접 보장하지 못함 — Keycloak Admin UI 표시값을 신뢰원으로 사용해야 함 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `KC-IDP-BROKER-C1`: Keycloak 이 외부 IDP 위임 인증을 지원한다는 공식 정의 (Google/Facebook 예시 포함)
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- broker endpoint URL 의 정확한 path 포맷 (`C2` 참조)
|
|
- First Broker Login Flow 의 단계별 동작 (별도 페이지 [[raw/official-docs/keycloak-first-broker-login-flow]] 참조)
|
|
- Identity Provider Mappers 의 동작 (별도 페이지 [[raw/official-docs/keycloak-identity-provider-mappers]] 참조)
|
|
- SPA 에 발급되는 토큰의 `iss` claim 이 Keycloak issuer URL 과 정확히 어떻게 결합되는지
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- P3B 의 `KC_HOSTNAME` + `KC_HTTP_RELATIVE_PATH` 조합에서 broker endpoint URL 의 실제 표시값 (Admin UI 직접 확인 필수)
|
|
- Google Cloud Console 의 Authorized Redirect URI 정책이 해당 URL 의 path component 를 그대로 허용하는지
|
|
|
|
## P3B 함의 (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용이 아니라 P3B 결정 컨텍스트 해석. wiki 추출 시 `wiki/concepts/` 또는 `wiki/projects/` source-summary 로 옮겨야 함.
|
|
|
|
- Keycloak Admin → Realm → Identity Providers → "Google" 추가.
|
|
- Keycloak이 화면에 표시하는 **Redirect URI**를 복사 → Google Cloud Console의 OAuth 2.0 Client → Authorized redirect URIs에 등록.
|
|
- 이 Redirect URI는 `KC_HOSTNAME` + `KC_HTTP_RELATIVE_PATH` 기준으로 구성됨 → 둘이 틀어지면 Redirect URI도 어긋남.
|
|
- 사용자 매핑: Google의 `email` claim 등을 Keycloak 사용자에 mapper로 연결. First-login flow에서 신규 사용자 자동 생성 or 기존 사용자에 link.
|
|
|
|
## 신뢰 경계 (3-leg)
|
|
|
|
```
|
|
Browser (User) ↔ Keycloak (Authorization Server, IdP broker)
|
|
↑
|
|
↓ OIDC (server-to-server는 일부, redirect는 user agent)
|
|
Google (외부 IdP)
|
|
```
|
|
|
|
- SPA는 Google과 직접 통신하지 않음. Google ↔ Keycloak 간 OIDC만 존재 → SPA 코드는 P3A와 동일.
|
|
- Trust 경계: Keycloak이 Google 응답(ID token)을 검증 → 그 후 자체 토큰 발급. SPA 입장에서는 token issuer가 늘 Keycloak.
|
|
|
|
## 메모 / Notes
|
|
|
|
- 2026-05-27 재migration: 본 환경에서 WebFetch 권한 부재로 라이브 페이지 재검증 불가. 기존 author 가 verbatim 으로 발췌한 1문장만 보존, broker endpoint URL 포맷은 명시적으로 `needs-confirmation` 분류 (C2).
|
|
- 후속: Keycloak Admin UI 캡쳐 / 다른 official sub-page (General configuration) 직접 발췌 보강 후 `C2` 를 `official-vendor-doc` 으로 승격 후보.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/keycloak-identity-broker-spi]] — 커스텀 broker SPI 참고
|
|
- [[raw/official-docs/keycloak-identity-provider-mappers]] — claim → attribute/role 매핑
|
|
- [[raw/official-docs/keycloak-first-broker-login-flow]] — 첫 로그인 시 신규/링크 분기
|
|
- [[raw/official-docs/keycloak-hostname-configuration]] — broker endpoint URL 의 hostname 결정
|
|
- [[raw/official-docs/keycloak-reverseproxy-official]] — proxy 환경에서의 endpoint URL 노출
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-keycloak-patterns]]
|
|
- [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]]
|
|
- [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]]
|
|
- [[raw/branch-notes/feature-keycloak-first-broker-login-flow]]
|
|
- [[raw/branch-notes/feature-keycloak-google-redirect-uri-policy]]
|
|
- 인용한 wiki: (미작성)
|