donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6c53ded9cb70f2d7cf3e66ff50d42f2d151c98b1
llm-wiki/vault/20-evidence/official-docs/keycloak-first-login-flow.md
T

10 KiB
Raw Blame History

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 Login Flow — 외부 IdP 최초 로그인 시 사용자 매핑 정책 official-doc https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/identity-broker/first-login-flow.html raw high
keycloak-patterns
p1b-edge-google-federation
idp-brokering
keycloak
first-login-flow
account-linking
official-doc
keycloak-patterns
feature-keycloak-patterns
feature-keycloak-edge-forwardauth-google-federation
feature-keycloak-first-broker-login-flow
feature-keycloak-account-linking-sub-vs-email
feature-keycloak-account-linking-spa-ux
2026-05-25 2026-05-27

Keycloak First Login Flow — 외부 IdP 최초 로그인 시 사용자 매핑 정책

Layer: raw/official-docs/ — Keycloak Server Admin Guide / "Identity Brokering / First Login Flow" 섹션 (gitbook 미러 verbatim). P1B 토큰 교환 sequence 8단계 (Google ID token claim → Keycloak 사용자 조회/생성) 분기 정책의 1차 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns keycloak-patterns root — IdP federation 시 First Login Flow 가 매핑/링크 정책의 단일 진입점이라는 사실
raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation P1B Edge + Google federation 의 8단계 sequence 에서 step 7-8 (Confirm Link Existing Account vs 자동 link) 분기 결정 근거
raw/branch-notes/feature-keycloak-first-broker-login-flow flow 복제 + Confirm Link Existing Account authenticator 채택 (자동 link 회피) 결정 근거
raw/branch-notes/feature-keycloak-account-linking-sub-vs-email "email 자동 link 는 security hole" 공식 경고 기반 → sub claim 기반 매칭으로 전환 결정
raw/branch-notes/feature-keycloak-account-linking-spa-ux SPA 측 redirect → Confirm Link info page 노출 → SPA 복귀의 UX 시퀀스 설계 근거

컨텍스트 / 왜 저장했는지

P1B 의 토큰 교환 sequence 8단계 (Google ID token claim → Keycloak 사용자 조회/생성) 가 어떻게 분기되는지의 1차 근거. "First Login Flow 에서 Review Profile 활성화 여부 / 자동 링크 vs 수동 confirm" 이라는 P1B 결정 사항의 출처.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§Email collision — first paragraph] "There is not yet an existing Keycloak user account imported and linked for this external user. Usually you just want to register and import the new account into Keycloak database, but what if there is an existing Keycloak account with the same email?"

[§Security warning] "Automatically linking the existing local account to the external identity provider is a potential security hole as you can't always trust the information you get from the external identity provider."

[§Confirm Link Existing Account info page] "On the info page, the user will see that there is an existing Keycloak account with same email. He can review his profile again and use different email or username (flow is restarted and goes back to Review Profile authenticator). Or he can confirm that he wants to link the identity provider account with his existing Keycloak account."

[§Review Profile authenticator] "When On, users will be always presented with the profile page asking for additional information in order to federate their identities. When missing, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider. If Off, the profile page won't be displayed."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
KC-FLF-C1 external IdP user 가 처음 로그인 시 기존 Keycloak account 가 없을 수 있으며, 같은 email 의 기존 account 가 있는 경우의 처리가 정책 결정 사항 [§Email collision — first paragraph] "There is not yet an existing Keycloak user account imported and linked for this external user. Usually you just want to register and import the new account into Keycloak database, but what if there is an existing Keycloak account with the same email?" official-vendor-doc external IdP brokering 활성화 realm 정책의 선택지가 자동/수동/거부 셋뿐이라는 뜻은 아님 — authenticator 조합으로 추가 분기 가능
KC-FLF-C2 external IdP 정보에 기반한 기존 local account 자동 link 는 잠재적 보안 hole (외부 IdP 정보를 항상 신뢰할 수 없기 때문) — 공식 경고 [§Security warning] "Automatically linking the existing local account to the external identity provider is a potential security hole as you can't always trust the information you get from the external identity provider." official-vendor-doc first-login flow 에서 email 기반 자동 link 시나리오 "신뢰할 수 없는" 의 정확한 위협 모델 (email_verified=false / spoofed email / IdP 컴프로마이즈 등) 은 본 인용에 없음
KC-FLF-C3 Confirm Link Existing Account info page 는 사용자에게 (A) profile 재검토 후 다른 email/username 사용, 또는 (B) IdP account 를 기존 Keycloak account 와 link 확인 의 선택지를 제공 [§Confirm Link Existing Account info page] "On the info page, the user will see that there is an existing Keycloak account with same email. He can review his profile again and use different email or username (flow is restarted and goes back to Review Profile authenticator). Or he can confirm that he wants to link the identity provider account with his existing Keycloak account." official-vendor-doc Confirm Link Existing Account authenticator 가 포함된 first-login flow confirm 시 password 재인증 요구 여부는 본 인용에 명시 없음 — 별도 authenticator 결합 필요
KC-FLF-C4 Review Profile authenticator 의 3개 모드: On (항상 표시), missing (mandatory 정보 부재 시만 표시), Off (표시 안 함) [§Review Profile authenticator] "When On, users will be always presented with the profile page asking for additional information in order to federate their identities. When missing, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider. If Off, the profile page won't be displayed." official-vendor-doc Review Profile authenticator 설정 "mandatory information" 의 정확한 목록이 email/first name/last name 외 다른 attribute (e.g., locale) 를 포함하는지는 인용 범위 밖

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • KC-FLF-C1: email collision 자체가 정책 결정 사항이라는 사실
    • KC-FLF-C2: email-only 자동 link 의 security hole 공식 경고 (P1B 의 "수동 confirm" 결정의 1차 근거)
    • KC-FLF-C3: Confirm Link Existing Account info page UX 흐름 (review profile 회귀 vs link 확인)
    • KC-FLF-C4: Review Profile authenticator 의 정확한 3개 모드명 (On/missing/Off)
  • 이 자료가 증명하지 않는 것:
    • "Detect Existing Broker User" authenticator 의 존재 (gitbook 미러 페이지에는 미언급 — keycloak-first-broker-login-flow.md 의 본 명명은 별도 admin guide 페이지에서 유래, 본 자료로 보장 안 됨)
    • Confirm Link 시 password 재인증 vs 단순 confirm 의 정확한 선택 메커니즘 (Reauthentication authenticator 별도)
    • Google sub claim 기반 매칭으로 전환했을 때 첫 로그인 flow 가 어떻게 단순화되는지 (별도 mapper 결정과 결합)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • "Confirm Link Existing Account" 가 default flow 에 포함되는지 vs 별도 추가 필요한지 (Keycloak version 별)
    • P1B 의 ## 결정 사항 에서 "Review Profile = Off + Confirm Link = required" 조합 가능 여부 (UI 시연 필요)
    • Google email_verified=false 계정의 first-login flow 에서 거부 vs 진행의 분기 (별도 validator 결합)

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. P1B 결정 컨텍스트 해석.

  • 분기 트리 (P1B 8단계 상세화):
    1. Google ID token 도착 → sub 로 기존 federated user 조회.
    2. 있으면 → 그대로 Keycloak token 발급 (정상 SSO 재로그인).
    3. 없으면 → email 로 기존 Keycloak local user 조회.
      • 없음 → 신규 생성 (Review Profile 옵션에 따라 한 번 더 확인 페이지).
      • 있음 → Handle Existing Account 서브플로우 진입 (자동 링크 / 사용자 confirm / 재인증 요구).
  • 보안 핵심: 공식 문서가 KC-FLF-C2 로 "automatic linking by email = potential security hole" 명시. P1B 에서 "수동 confirm" 채택이 안전한 기본값.
  • Review Profile: 외부 IdP 가 email/이름을 안 줄 때만 강제 표시 (missing mode). Google 은 email+profile scope 로 모두 제공하므로 Off 도 가능 — UX 결정.
  • 운영 비용: First Login Flow 는 Keycloak Admin Console > Authentication > Flows 에서 커스터마이즈 가능하나, 잘못 건드리면 외부 IdP 전체가 막힐 수 있음 → flow 복제 후 수정 권장.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink