llm-wiki/raw/official-docs/keycloak-identity-broker-spi.md

---
title: Keycloak Identity Broker SPI (커스텀 브로커 — 참고)
source_type: official-doc
url: https://www.keycloak.org/docs/latest/server_development/index.html#_identity_brokering
archive_url:
status: raw
confidence: medium
tags: [keycloak-patterns, p2b-spa-google-federation, idp-brokering, spi, extension]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-internal-spa-direct-google-federation, feature-keycloak-idp-brokering-google-client]
created: 2026-05-25
last_reviewed: 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 함의 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용이 아니라 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}/token` URL 도 본 페이지에서는 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:
  - [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]]
  - [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]]
- 인용한 wiki: (미작성)