6.9 KiB
6.9 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Keycloak Identity Broker SPI (커스텀 브로커 — 참고) | official-doc | https://www.keycloak.org/docs/latest/server_development/index.html#_identity_brokering | raw | medium |
|
|
|
2026-05-25 | 2026-05-27 |
Keycloak Identity Broker SPI
Layer:
raw/official-docs/— Keycloak Server Developer Guide 의 Identity Brokering APIs 발췌. 커스텀 IdentityProvider 구현이 필요한지 결정하는 참고 자료.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation | P2B 의 Google federation 구현 시 built-in Google provider + Identity Provider Mappers 로 충분하므로 SPI 커스텀 구현은 도입하지 않는다는 결정 근거 |
| raw/branch-notes/feature-keycloak-idp-brokering-google-client | built-in provider 의 한계가 드러날 때 SPI 확장이 가능하다는 backup 옵션의 출처 |
컨텍스트
P2B 학습 단계에서 Google 같은 표준 IdP 는 Keycloak built-in provider 로 충분. SPI 커스텀 구현은 사내 OIDC IdP / 비표준 claim 처리 / audit hook 등 특수 use case 에만 필요. 본 raw 는 "왜 SPI 를 도입하지 않는가" 의 근거.
출처 / Source
- 원본 URL: https://www.keycloak.org/docs/latest/server_development/index.html#_identity_brokering
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — Server Developer Guide
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27
- 주의: 본 가이드는 "consume identity brokering features" 중심이며, 커스텀
IdentityProvider/IdentityProviderFactory구현 가이드는 본 페이지에서 직접 verbatim 회수되지 않음 → 세부 인터페이스는needs-confirmation.
핵심 인용 / Key quotes (verbatim)
[§SPI 일반 구현 패턴] "To implement an SPI you need to implement its ProviderFactory and Provider interfaces. You also need to create a service configuration file."
[§Identity Brokering APIs] "Identity Brokering APIs - retrieve external IDP tokens and implement client-initiated account linking."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-BROKER-SPI-C1 | Keycloak 의 모든 SPI 는 ProviderFactory + Provider 인터페이스 구현 + META-INF/services/ service configuration file 등록의 동일 골격을 따른다 |
[§SPI 일반 구현 패턴] "To implement an SPI you need to implement its ProviderFactory and Provider interfaces. You also need to create a service configuration file." | official-vendor-doc |
Keycloak SPI 전반 (Identity Provider, Authenticator, User Storage 등) | Identity Broker SPI 의 구체적 인터페이스 이름 (IdentityProvider, IdentityProviderFactory) 이 본 인용에서 직접 명시되었다는 뜻은 아님 — 일반론 |
| KC-BROKER-SPI-C2 | Identity Brokering APIs 는 외부 IDP token 회수 + client-initiated account linking 두 가지 기능을 제공 | [§Identity Brokering APIs] "Identity Brokering APIs - retrieve external IDP tokens and implement client-initiated account linking." | official-vendor-doc |
백엔드가 외부 IDP token (예: Google access token) 을 필요로 하는 경우 + 사용자가 명시적으로 계정 link 를 시작하는 경우 | 토큰 회수 endpoint 의 정확한 URL 포맷 / 권한 요구사항 / refresh 정책은 본 인용 범위 밖 |
| KC-BROKER-SPI-C3 | 구체적 인터페이스명 (org.keycloak.broker.provider.IdentityProvider, IdentityProviderFactory) 과 service file 경로 (META-INF/services/org.keycloak.broker.provider.IdentityProviderFactory) 는 본 페이지의 verbatim 발췌에서 직접 확인되지 않음 (운영 관행 / Keycloak 소스 코드 / 다른 페이지 일치로만 알려짐) |
(verbatim 부재 — 부재 자체가 claim) | needs-confirmation |
커스텀 Identity Provider SPI 구현 시 클래스/파일 명명 | 해당 클래스명이 틀렸다는 뜻은 아님. Keycloak 소스 트리에서 직접 확인 필요 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
KC-BROKER-SPI-C1: SPI 일반 구현 골격 (3-step: Factory + Provider + service file)KC-BROKER-SPI-C2: Identity Brokering APIs 의 2가지 기능 (token 회수 + account linking)
- 이 자료가 증명하지 않는 것:
KC-BROKER-SPI-C3: 구체적 클래스 / 파일 경로- 외부 token 회수 endpoint URL (
/auth/realms/{realm}/broker/{provider}/token) 의 verbatim 출처 - 어떤 use case 에서 built-in provider 가 부족하고 SPI 가 필수가 되는지의 명시적 기준
- account linking 의 권한 요구사항 / token requirements
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- P2B 의 Google federation 에서 built-in provider 만으로 모든 요구 (Hosted Domain
hd분기, audit 등) 가 충족되는지 — 충족된다면 본 문서 결론 ("SPI 불필요") 그대로 적용 - 외부 token 회수 endpoint 의 정확한 URL 과 권한 (Keycloak Admin UI / 다른 official sub-page 직접 확인 필요)
- P2B 의 Google federation 에서 built-in provider 만으로 모든 요구 (Hosted Domain
P2B 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아니라 P2B 결정 컨텍스트 해석. wiki 추출 시
wiki/concepts/또는wiki/projects/source-summary 로 옮겨야 함.
P2B 에서 SPI 커스텀 구현은 대부분 필요 없음. Google 은 built-in social provider 로 제공됨. SPI 는 다음 같은 경우에만:
- Google 외 사내 OIDC IdP 추가 (built-in 에 없는 경우)
- 표준 OIDC 를 벗어난 커스텀 토큰 흐름 (예: 비표준 claim 처리, 추가 검증 로직)
- audit logging 후크 삽입
P2B 학습 단계에선 built-in Google provider + Identity Provider Mappers 로 충분.
메모 / Notes
- 2026-05-27 재migration: WebFetch 권한 부재로 라이브 페이지 재검증 불가. 기존 author 의 2건 verbatim 발췌 보존, 클래스/파일 경로는 명시적으로
needs-confirmation(C3). /auth/realms/{realm}/broker/{provider}/tokenURL 도 본 페이지에서는 verbatim 확인 안 됨 — 별도 sub-page 확인 후 보강 권고.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/keycloak-identity-brokering-overview-official — admin 측 overview
- raw/official-docs/keycloak-identity-provider-mappers — built-in provider + mapper 조합으로 SPI 회피
- 인용하는 branch:
- 인용한 wiki: (미작성)