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-broker-login-verify-authenticators-official.md
T

14 KiB
Raw Blame History

title, source_type, status, confidence, url, archive_url, related_branches, related_projects, tags, created, last_reviewed
title source_type status confidence url archive_url related_branches related_projects tags created last_reviewed
official-doc / Keycloak First Broker Login — Verify Existing Account Authenticators (Email default vs Re-authentication fallback) official-doc raw high https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker_first_login
feature-keycloak-account-linking-sub-vs-email
feature-keycloak-first-broker-login-flow
keycloak-patterns
official-doc
keycloak-patterns
auth
security
keycloak
2026-07-15 2026-07-15

Keycloak First Broker Login — Verify Existing Account Authenticators (Email default vs Re-authentication fallback)

Layer: raw/official-docs/ — Keycloak Server Administration Guide, "First login flow" 섹션 중 Handle Existing Account 서브플로우의 Verify Existing Account By Email / Verify Existing Account By Re-authentication authenticator 발췌. keycloak/keycloak 저장소 main 브랜치의 원본 AsciiDoc 소스(docs/documentation/server_admin/topics/identity-broker/first-login-flow.adoc)를 직접 fetch — 렌더된 canonical 페이지가 truncate 되는 문제를 우회. 정정 대상: 기존 사용자 가정("account linking 시 기본값은 password 재인증")은 부정확하다. 원문은 email 확인이 SMTP 설정 시 기본값이고, 재인증은 email authenticator 를 쓸 수 없을 때의 fallback 이다.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-first-broker-login-flow First Broker Login Flow 구성 owner — D1(AutoLink 미사용, WARNING KC-FBLVERIFY-C4 + OOTB 충돌감지 key=email/username KC-FBLVERIFY-C5), D2(Verify Existing Account By Email = SMTP 시 ALTERNATIVE 기본 / Re-authentication = fallback KC-FBLVERIFY-C1~C3). 정정의 canonical 위치.
raw/branch-notes/feature-keycloak-account-linking-sub-vs-email D2 (기존 Keycloak local 계정에 Google federated identity 추가 link 시 재인증 필수 여부) 의 authenticator-level 정정 근거 — "Verify Existing Account by Re-authentication REQUIRED" 라는 원래 노트 표현은 OOTB 기본값과 다름. SMTP 설정 realm 에서는 Verify Existing Account By Email 이 ALTERNATIVE 기본값이며, password 재인증을 강제하려면 관리자가 email authenticator 를 명시적으로 비활성화해야 한다.

출처 / Source

왜 저장했는지 / Why archived

기존 branch-note (D2)가 "기존 계정에 identity 를 link 할 때 password 재인증이 REQUIRED" 라고 기술했는데, 원문을 직접 fetch 해 보니 재인증이 기본값이 아니다 — SMTP 가 설정된 realm 에서는 email 확인(Verify Existing Account By Email, ALTERNATIVE)이 기본 경로이고, password 재인증(Verify Existing Account By Re-authentication)은 email authenticator 를 쓸 수 없을 때만 실행되는 fallback 이다. 이 정정이 D2 의 근거 정확도에 직접 영향을 준다.

핵심 인용 / Key quotes (verbatim, 5문장)

[§Default first login flow authenticators — Verify Existing Account By Email] "This authenticator is ALTERNATIVE by default. {project_name} uses this authenticator if the realm has an SMTP setup configured."

[§Default first login flow authenticators — Verify Existing Account By Email] "Disable this authenticator if you do not want to confirm linking by email, but want users to reauthenticate with their password."

[§Default first login flow authenticators — Verify Existing Account By Re-authentication] "Use this authenticator if the email authenticator is not available. For example, you have not configured SMTP for your realm."

[§Automatically link existing first login flow — WARNING admonition] "The AutoLink authenticator is dangerous in a generic environment where users can register themselves using arbitrary usernames or email addresses. Do not use this authenticator unless you are carefully curating user registration and assigning usernames and email addresses."

[§Default first login flow authenticators — Create User If Unique] "This authenticator checks if there is already an existing {project_name} account with the same email or username like the account from the identity provider."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
KC-FBLVERIFY-C1 "Verify Existing Account By Email" authenticator 는 ALTERNATIVE 등급이 기본값이며, realm 에 SMTP 설정이 있으면 Keycloak 이 이 authenticator 를 사용한다 — 즉 SMTP 가 설정된 realm 의 OOTB 기본 경로는 email 확인이지 password 재인증이 아니다 [§Verify Existing Account By Email] "This authenticator is ALTERNATIVE by default. {project_name} uses this authenticator if the realm has an SMTP setup configured." official-vendor-doc Default First Broker Login flow, SMTP 가 구성된 realm 특정 realm 이 실제로 SMTP 를 구성했는지는 배포 환경별 사실이며 이 인용으로 보장 안 됨. 관리자가 flow 를 재구성해 이 기본값을 바꿨을 가능성도 이 인용 범위 밖
KC-FBLVERIFY-C2 email 로 linking 을 확인하지 않고 password 재인증을 강제하려면, 관리자가 이 authenticator("Verify Existing Account By Email")를 명시적으로 비활성화해야 한다 [§Verify Existing Account By Email] "Disable this authenticator if you do not want to confirm linking by email, but want users to reauthenticate with their password." official-vendor-doc 관리자가 password 재인증 강제를 원하는 경우 비활성화 후 재인증 authenticator 의 정확한 UI/세션 동작까지는 이 인용으로 보장 안 됨 — "email authenticator 를 못 쓰게 되면 re-auth 로 넘어간다"는 KC-FBLVERIFY-C3 과 결합해야 전체 그림이 완성됨
KC-FBLVERIFY-C3 "Verify Existing Account By Re-authentication" 은 email authenticator 를 쓸 수 없을 때(예: realm 에 SMTP 미설정)만 쓰는 authenticator — 즉 fallback 이지 기본값이 아니다 [§Verify Existing Account By Re-authentication] "Use this authenticator if the email authenticator is not available. For example, you have not configured SMTP for your realm." official-vendor-doc SMTP 미설정 realm, 또는 email authenticator 가 비활성화된 realm SMTP 가 설정된 realm 에서 재인증이 기본값이라는 주장을 지지하지 않음 — 오히려 그 반대(KC-FBLVERIFY-C1)가 기본값
KC-FBLVERIFY-C4 AutoLink 계열 authenticator("Automatically Set Existing User")는 사용자가 임의 username/email 로 자체 등록 가능한 일반적인 환경에서 위험하며, 등록을 엄격히 curating 하는 경우가 아니면 사용하지 말아야 한다 (공식 WARNING) [§Automatically link existing first login flow, WARNING] "The AutoLink authenticator is dangerous in a generic environment where users can register themselves using arbitrary usernames or email addresses. Do not use this authenticator unless you are carefully curating user registration and assigning usernames and email addresses." official-vendor-doc "Automatically Set Existing User" 를 포함하는 커스텀 first-login flow 를 고려하는 모든 realm Google federation + sub 기반 매칭 조합에서 AutoLink 를 쓸 때의 구체적 위협 모델까지는 다루지 않음 — 본 branch 의 threat-model 해석은 별도
KC-FBLVERIFY-C5 "Create User If Unique" authenticator 는 IdP 로부터 받은 계정과 같은 email 또는 username 을 가진 기존 계정이 있는지 확인한다 — 즉 OOTB 충돌 감지(collision detection) key 는 email/username 이며 IdP sub 가 아니다 [§Create User If Unique] "This authenticator checks if there is already an existing {project_name} account with the same email or username like the account from the identity provider." official-vendor-doc Default First Broker Login flow 의 "Handle Existing Account" 진입 여부를 결정하는 첫 단계 이 인용은 sub 기반 매칭이 OOTB 로 존재한다는 것을 증명하지 않는다 — 오히려 반대로, OOTB 매칭 key 가 email/username 임을 직접 보여준다. sub 기반 매칭으로 전환하려면 커스텀 authenticator/mapper 구성이 필요하다는 것은 본 인용 범위 밖(별도 근거 필요)

Strength 허용값

  • official-standard — RFC, 표준 사양, 언어/프로토콜 표준
  • official-vendor-doc — Spring, Keycloak, AWS, Google 등 공식 벤더 문서
  • official-reference — 공식 reference/API 문서
  • company-case-study — 대기업/실무 기술 블로그의 특정 사례
  • engineering-blog — 개인/팀 블로그의 엔지니어링 해설
  • tutorial — 튜토리얼/가이드. 일반화 금지
  • needs-confirmation — 원문만으로는 적용 판단 불가

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • KC-FBLVERIFY-C1~C3: Default First Broker Login flow 의 두 "Verify Existing Account" authenticator 각각의 정확한 트리거 조건과 우선순위 — SMTP 설정 시 email 확인이 ALTERNATIVE 기본값, 재인증은 email authenticator 를 쓸 수 없을 때의 fallback. 재인증을 강제하려면 관리자가 email authenticator 를 disable 해야 함.
    • KC-FBLVERIFY-C4: AutoLink authenticator 사용에 대한 공식 WARNING 존재.
    • KC-FBLVERIFY-C5: "Create User If Unique" 의 OOTB collision-detection key 가 email 또는 username 이라는 사실.
  • 이 자료가 증명하지 않는 것:
    • Keycloak OOTB First Broker Login flow 의 collision matching 이 IdP sub claim 기반이라는 것 — 정반대: KC-FBLVERIFY-C5 는 매칭 key 가 email/username 임을 직접 보여준다. sub 기반 매칭을 원하면 커스텀 authenticator 또는 IdP mapper 구성이 필요하며, 그 구현 방법은 이 자료 범위 밖.
    • 특정 realm 이 실제로 SMTP 를 구성했는지 여부 (배포별 사실).
    • email_verified=false 인 계정에 대한 이 authenticator 들의 구체적 거부/허용 동작 (trustEmail 설정과의 상호작용은 별도 문서 — 예: raw/official-docs/keycloak-identity-provider-mappers.md).
    • 특정 릴리스 태그(예: 26.x GA)에서 이 authenticator 명칭·기본값이 동일하게 유지되는지 — 아래 "버전 caveat" 참조.
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • 실제 배포 realm 의 SMTP 설정 여부 확인 (Admin Console > Realm Settings > Email).
    • D2 재작성 시, "재인증 REQUIRED" 대신 "SMTP 설정 시 email 확인이 기본, 재인증을 강제하려면 email authenticator 를 명시적으로 disable" 로 문구 수정 필요.
    • sub 기반 matching 을 OOTB collision detection 위에 어떻게 얹을지 (커스텀 authenticator 또는 mapper) 는 별도 조사 필요 — 이 자료는 "OOTB 는 email/username 이다"까지만 증명.

버전 caveat / Version note

본 자료는 2026-07-15 시점 keycloak/keycloak 저장소 main 브랜치(rolling, 미출시 문서 포함 가능)의 AsciiDoc 소스를 직접 fetch 한 것이다. 렌더된 canonical URL(www.keycloak.org/docs/latest/...)은 "latest" 별칭이라 시점에 따라 다른 릴리스를 가리킬 수 있고, 본문이 truncate 되어 WebFetch 로는 verbatim 확보가 불가능했다 (별도 raw AsciiDoc fetch 로 우회). 특정 릴리스(예: 26.0, 26.1 GA 태그)에 이 authenticator 명칭·기본 등급(ALTERNATIVE)이 동일한지는 재확인 필요 — 프로덕션에 적용 전 실제 배포 버전의 admin guide 또는 Admin Console 화면에서 재검증할 것.

메모 / Notes

  • 기존 raw/official-docs/keycloak-first-broker-login-flow (KC-FBL prefix) 의 C2~C4 인용은 문서 자체가 "needs-confirmation — paraphrase 가능성 배제 못함"으로 표시되어 있음. 본 문서는 그 문서와 달리 gitbook 미러가 아닌 GitHub main 브랜치 원본 AsciiDoc 을 직접 curl 하여 self-grep 100% 통과한 verbatim quote 만 담았다 — Verify Existing Account authenticator 관련 사실은 본 문서를 우선 근거로 사용할 것.
  • raw/official-docs/keycloak-first-login-flow (KC-FLF prefix) 는 email collision 자체와 Confirm Link Existing Account info page, Review Profile 모드를 다루지만 Verify Existing Account By Email/Re-authentication 의 정확한 트리거 조건(SMTP 유무)은 다루지 않는다 — 본 문서가 그 공백을 메운다.
  • "Disabling automatic user creation" 섹션(원문 §)에 따르면 Create User If Unique + Confirm Link Existing Account 를 모두 DISABLED 로 설정하면 Keycloak 이 내부적으로 어떤 계정이 대응하는지 판단할 수 없게 되어 Verify Existing Account By Re-authentication 이 username 과 password 를 모두 요구한다는 보조 설명이 있음(본 raw 의 5개 핵심 인용에는 미포함, 필요 시 추가 발췌 가능).

Related / 관련

Reference in New Issue View Git Blame Copy Permalink