---
title: Keycloak First Broker Login Flow & Account Linking (공식 문서)
source_type: official-doc
url: https://www.keycloak.org/docs/latest/server_admin/index.html#_first_broker_login_flow
archive_url:
status: raw
confidence: medium
tags: [keycloak-patterns, p2b-spa-google-federation, idp-brokering, account-linking, first-broker-login]
related_projects: [keycloak-patterns]
related_branches: [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]
created: 2026-05-25
last_reviewed: 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: (미작성)