llm-wiki/vault/20-evidence/official-docs/keycloak-first-broker-login-flow.md

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 First Broker Login Flow & Account Linking (공식 문서)	official-doc	https://www.keycloak.org/docs/latest/server_admin/index.html#_first_broker_login_flow		raw	medium	keycloak-patterns p2b-spa-google-federation idp-brokering account-linking first-broker-login	keycloak-patterns	feature-keycloak-patterns feature-keycloak-first-broker-login-flow feature-keycloak-internal-spa-direct-google-federation feature-keycloak-account-linking-spa-ux feature-keycloak-account-linking-sub-vs-email	2026-05-25	2026-05-27

Keycloak First Broker Login Flow

Layer: raw/official-docs/ — Keycloak Server Administration Guide 의 "First Broker Login Flow" 섹션 발췌. 외부 IdP (예: Google) 로 처음 로그인하는 사용자에 대한 user 생성 / 매칭 / link 정책 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns	keycloak-patterns root 에서 P2B (SPA + Google federation) 변형의 first-login authenticator 선택 근거
raw/branch-notes/feature-keycloak-first-broker-login-flow	first broker login flow 의 authenticator 구성 (Automatically Link / Detect Existing Broker User / Create User If Unique) 결정 근거
raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation	P2B 변형에서 Google federation 첫 로그인 UX 정책 결정 근거
raw/branch-notes/feature-keycloak-account-linking-spa-ux	SPA 측에서 first-broker-login confirm 화면이 노출될 때의 redirect/return UX 설계 근거
raw/branch-notes/feature-keycloak-account-linking-sub-vs-email	Google sub vs email 기반 매칭 정책 결정 (이메일 hijack 방어) 근거

컨텍스트 / 무엇인가

외부 IdP (Google 등) 를 통해 사용자가 처음 로그인할 때 Keycloak 이 실행하는 인증 플로우. 결정해야 할 사항:

1. 외부 IdP 의 사용자 정보로 새 Keycloak user 를 자동 생성 할 것인가?
2. 같은 email/username 을 가진 기존 Keycloak user 가 있다면 자동 link 할 것인가, 사용자 확인을 받을 것인가?
3. mapping 이 안 맞으면 거부할 것인가?

출처 / Source

• 원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html#_first_broker_login_flow
• 페이지 구조: Keycloak admin guide single-page (Table of Contents 에 "First login flow" 섹션 존재 확인)
• 아카이브 URL: (미수집)
• 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
• 발행일: rolling docs (현재 26.x)
• 마지막 확인일: 2026-05-27
• 재확인 한계: 2026-05-27 WebFetch 로 main page 호출 시 본 섹션 본문이 응답 truncation 으로 캡처 불가. Table of Contents 만 확인됨 — 섹션 존재 자체는 검증, 본문 verbatim 은 별도 재수집 필요.

핵심 인용 / Key quotes (verbatim — needs-confirmation)

2026-05-25 user 수집 시점의 인용. 2026-05-27 재검증 시 main page truncation 으로 verbatim 일치 확인 불가. 본 인용들은 needs-confirmation 상태 — 향후 별도 sub-page / PDF / archive 로 재확인 필요.

[§First login flow — 2026-05-25 capture] "Automatically link existing first login flow allows Keycloak to match incoming federated identities to existing local users using mapped attributes (typically email)."

[§First login flow — 2026-05-25 capture] "Detect existing user first login flow functionality to search the user database for matches before account creation, enabling seamless linking when email addresses correspond."

[§First login flow — 2026-05-25 capture] "Organizations can customize this behavior per Identity Provider using Identity provider mappers to control which attributes trigger account linking."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-FBL-C1	Keycloak 은 "First login flow" 라는 별도 authentication flow 를 제공하며, 외부 IdP 로 첫 로그인 시 이 flow 가 실행됨 (TOC 섹션 존재로 확인)	(구조 인용 — TOC 의 "First login flow" 섹션 + sub-section: Default first login flow authenticators / Automatically link existing first login flow / Disabling automatic user creation / Detect existing user first login flow / Override existing broker link)	official-vendor-doc	외부 IdP brokering 을 활성화한 Keycloak realm	각 sub-section 본문의 구체적 동작은 본 인용으로 보장 안 됨 — 별도 재확인 필요
KC-FBL-C2	"Automatically link existing" first login flow 는 매핑된 attribute (typically email) 로 federated identity 를 기존 local user 와 매칭한다 (2026-05-25 quote, 재검증 보류)	[§First login flow] "Automatically link existing first login flow allows Keycloak to match incoming federated identities to existing local users using mapped attributes (typically email)."	needs-confirmation	first-broker-login 시 email-based account linking 정책	email-based linking 의 정확한 fallback 동작 (대소문자 / verified 여부 등) 은 본 인용에 없음
KC-FBL-C3	"Detect existing user" first login flow 는 account 생성 전 user DB 를 search 하여 매칭 user 가 있으면 link 한다 (2026-05-25 quote, 재검증 보류)	[§First login flow] "Detect existing user first login flow functionality to search the user database for matches before account creation, enabling seamless linking when email addresses correspond."	needs-confirmation	Detect Existing Broker User authenticator 사용 시	"seamless" 가 user confirmation 없이 자동인지, 명시적 prompt 가 있는지는 본 인용으로 결정 불가
KC-FBL-C4	Identity provider mapper 로 IdP 별로 account linking 트리거 attribute 를 customize 가능 (2026-05-25 quote, 재검증 보류)	[§First login flow] "Organizations can customize this behavior per Identity Provider using Identity provider mappers to control which attributes trigger account linking."	needs-confirmation	identity provider mapper 활용 시나리오	mapper 종류별 정확한 동작 / mapping 우선순위는 본 인용에 없음 — keycloak-identity-provider-mappers.md 참조

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • KC-FBL-C1: Keycloak 에 "First login flow" 라는 명명된 authentication flow 가 존재한다는 사실 (TOC 검증)
  • C2~C4 의 본문 인용은 2026-05-25 user 수집본 — 재검증 필요 (needs-confirmation)
• 이 자료가 증명하지 않는 것:
  • email_verified=false 인 Google 계정의 정확한 거부 메커니즘 (별도 RFC / Google OIDC 문서 + Keycloak validator 설정 결합)
  • 같은 email 의 기존 local user (password 가입) 와 자동 link 시 hijack 위험에 대한 공식 경고 (본 인용 범위 외)
  • 자동 link 와 manual confirmation 의 정확한 토글 위치 (admin UI screenshot 없이는 verbatim 인용 불가)
  • Google hd (hosted domain) claim 기반 도메인 제한 — Google OIDC mapper 측 책임, 본 인용 범위 외
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • 본 raw 의 C2~C4 인용을 Keycloak 공식 docs sub-page / PDF 에서 verbatim 재확인 (현재 sandbox 환경의 main-page WebFetch 로는 불가)
  • "Detect Existing Broker User" vs "Automatically Set Existing User" authenticator 의 정확한 차이 (UI vs 자동)
  • Google IdP 측 mapper 의 sub claim 사용 시 first-login flow 의 매칭 키 변경 효과 — raw/branch-notes/feature-keycloak-account-linking-sub-vs-email 에서 결정

설정 옵션 (요약, 2026-05-25 수집 시점 — needs-confirmation)

옵션	동작
Automatic linking (기본)	email/username 일치 시 자동 link
Manual confirmation	관리자 또는 사용자가 명시적으로 link 승인해야 함
Disable auto-create	새 user 자동 생성 금지. 매칭 안 되면 로그인 거부

P2B 운영 결정 포인트 (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. P2B 결정 컨텍스트 해석. wiki 추출 시 별도 처리.

• Google email_verified=true 만 허용? Google 에서 email_verified=false 계정도 받으면 email 기반 link 가 위조 위험.
• Account Linking 정책: 같은 email 의 기존 Keycloak local user (예: username/password 로 가입한 사용자) 가 있을 때:
  • 자동 link (편하지만 hijack 위험 — 누군가 같은 email 로 Google 가입 후 Keycloak 계정 탈취 가능)
  • 비밀번호 확인 후 link (안전)
  • 거부 (가장 안전, 사용자 경험 나쁨)
• Hosted Domain 제한 (Google hd claim): 기업 도메인만 받기.

메모 / Notes

• 2026-05-27 재검증: WebFetch 가 single-page admin guide 의 일부만 캡처 — 본 섹션 본문 verbatim 재확인 불가. 향후 다음 중 하나로 재수집:
  1. Keycloak release tag 별 GitHub source (adoc 파일)
  2. archive.org 스냅샷
  3. PDF distribution
• C2~C4 의 quote 문장 voice 는 Keycloak 공식 docs 의 전형적 어조와 다소 차이 — paraphrase 가능성도 배제 못함. 재검증 필수.

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/keycloak-identity-brokering-overview-official
  • raw/official-docs/keycloak-identity-provider-mappers
  • raw/official-docs/keycloak-identity-broker-spi
• 인용하는 branch:
  • raw/branch-notes/feature-keycloak-first-broker-login-flow
  • raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation
  • raw/branch-notes/feature-keycloak-account-linking-spa-ux
  • raw/branch-notes/feature-keycloak-account-linking-sub-vs-email
• 인용하는 wiki: (미작성)