donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/official-docs/keycloak-identity-provider-trust-email-official.md
T

12 KiB
Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created
title source_type url archive_url related_branches related_projects tags created
Keycloak Identity Provider — Trust Email Field Semantics (official) official-doc https://raw.githubusercontent.com/keycloak/keycloak/main/docs/documentation/server_admin/topics/identity-broker/configuration.adoc https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker
feature-keycloak-idp-brokering-google-client
keycloak-patterns
official-doc
keycloak-patterns
auth
keycloak
2026-07-16

Keycloak Identity Provider — Trust Email Field Semantics (official)

Layer: raw/official-docs/ — Keycloak Server Administration Guide, "Identity Broker" chapter, "Common Configuration" 표의 Trust Email 행. 원문 AsciiDoc source: identity-broker/configuration.adoc. 렌더링된 canonical 페이지(server_admin/index.html#_identity_broker)는 너무 커서 Identity Broker 섹션 이전에 잘리므로, 렌더링을 만드는 upstream AsciiDoc 원본을 GitHub raw 로 직접 발췌했다 — 형제 raw raw/official-docs/keycloak-identity-provider-sync-mode-official·raw/official-docs/keycloak-first-broker-login-verify-authenticators-official와 동일한 fetch 전략.

Parent / 활용 branch

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-idp-brokering-google-client D6 (trustEmail = false 를 Google OIDC broker 에 유지) 의 공식 근거 — Trust Email 필드가 정확히 무엇을 하는지(ON일 때 realm email 검증을 건너뛴다는 것), 그리고 email_verified claim / Sync Mode FORCE 와의 상호작용을 명시하는 verbatim. 단, 이 자료는 trustEmail 의 default 값은 증명하지 않음(아래 Usage Boundaries 참조) — D6 의 "default=false" 세부 주장은 이 문서만으로는 needs-confirmation 로 남는다

출처 / Source

왜 저장했는지 / Why archived

raw/branch-notes/feature-keycloak-idp-brokering-google-client D6 는 trustEmail = false 유지를 결정했지만, 근거로 인용된 raw(keycloak-google-idp-setup, google-openid-connect-oidc, keycloak-identity-brokering-overview-official)는 등록 절차와 discovery 표준만 다룰 뿐 Trust Email 필드 자체의 의미를 verbatim 으로 담고 있지 않아 D6 가 UNSUPPORTED_DECISION 으로 표시돼 있었다. 이 문서는 그 gap 을 메우는 verbatim 회수이며, 동시에 형제 raw raw/official-docs/keycloak-identity-provider-sync-mode-official의 §메모에서 "후속으로 볼 만한 것"으로 남겨둔 Trust Email 행의 FORCE 상호작용 문장을 회수한다.

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

[configuration.adoc, "Common Configuration" 표 — Trust Email 행, line 56] "When ON, {project_name} trusts email addresses from the identity provider. If the realm requires email validation, users that log in from this identity provider do not need to perform the email verification process."

[configuration.adoc, 같은 행, line 57] "If the target identity provider supports email verification and advertises this information when returning the user profile information, the email of the federated user will be (un)marked as verified."

[configuration.adoc, 같은 행, line 58] "For instance, an OpenID Connect Provider returning a email_verified claim in their ID Tokens."

[configuration.adoc, 같은 행, line 59-60 — AsciiDoc soft-wrap: 원문은 두 물리적 줄에 걸쳐 있으나 렌더링 시 한 문장으로 이어짐] "Note that this setting will set the email as verified when the user is federated for the first time and on subsequent logins through the broker if the sync mode is set to FORCE."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
KC-TRUSTEMAIL-C1 Trust Email 이 ON 이면 Keycloak 은 identity provider 가 제공한 email 주소를 신뢰하며, realm 이 email 검증을 요구하더라도 이 IdP 로 로그인한 사용자는 Keycloak 자체의 email 검증 절차를 수행할 필요가 없다 [configuration.adoc, line 56] "When ON, {project_name} trusts email addresses from the identity provider. If the realm requires email validation, users that log in from this identity provider do not need to perform the email verification process." official-vendor-doc Trust Email 필드가 ON 일 때 realm email-verification 절차를 broker 로그인 사용자에게 건너뛰게 하는 동작 이 자료는 Trust Email 의 default 값(ON/OFF 중 무엇이 기본인지)을 말하지 않는다. ON 이 보안상 권장/비권장인지에 대한 문장도 없다
KC-TRUSTEMAIL-C2 target identity provider 가 email 검증 여부를 지원하고 user profile 정보 반환 시 이를 advertise 하면(예: OpenID Connect Provider 가 ID Token 에 email_verified claim 을 포함), federated user 의 email 은 그 정보에 따라 verified/unverified 로 (un)mark 된다 [configuration.adoc, line 57] "If the target identity provider supports email verification and advertises this information when returning the user profile information, the email of the federated user will be (un)marked as verified." + [configuration.adoc, line 58] "For instance, an OpenID Connect Provider returning a email_verified claim in their ID Tokens." official-vendor-doc Trust Email ON 상태에서 IdP 가 email_verified 같은 claim 을 제공할 때 Keycloak 이 그 값을 그대로 verified 상태에 반영하는 메커니즘 Google 이 실제로 email_verified claim 을 항상/조건부로 제공하는지는 이 문서 범위 밖(별도 raw/official-docs/google-openid-connect-oidc 확인 필요). IdP 가 email 검증 정보를 전혀 advertise 하지 않을 때의 fallback 동작(예: 항상 verified 로 처리하는지)은 이 인용에 명시되지 않음
KC-TRUSTEMAIL-C3 이 설정(Trust Email)은 사용자가 최초로 federate 될 때 email 을 verified 로 설정하며, sync mode 가 FORCE 로 설정된 경우 이후 broker 를 통한 로그인마다 다시 verified 로 설정한다 [configuration.adoc, line 59-60] "Note that this setting will set the email as verified when the user is federated for the first time and on subsequent logins through the broker if the sync mode is set to FORCE." official-vendor-doc Trust Email + Sync Mode = FORCE 조합에서 매 로그인마다 email verified 상태가 재평가/재설정된다는 근거 Sync Mode 가 IMPORT/LEGACY 일 때 첫 로그인 이후 email verified 상태가 재평가되는지 여부는 이 문장이 직접 명시하지 않는다(FORCE 케이스만 명시적으로 언급됨 — 대조 추론은 이 자료만으로 확정 불가)

Strength 근거

모든 claim 이 official-vendor-doc — Keycloak(Red Hat) 공식 Server Administration Guide 원문(AsciiDoc)에서 직접 self-grep 검증된 verbatim이며, 3rd-party 재구성이나 tutorial이 아니다.

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • KC-TRUSTEMAIL-C1: Trust Email ON 일 때 realm email-verification 절차를 broker 로그인 사용자에게 건너뛰게 하는 동작.
    • KC-TRUSTEMAIL-C2: IdP 가 email 검증 여부를 advertise(예: email_verified claim)할 때 Keycloak 이 그 정보로 federated user 의 email verified 상태를 (un)mark 하는 메커니즘.
    • KC-TRUSTEMAIL-C3: Trust Email + Sync Mode FORCE 조합에서 첫 federation 뿐 아니라 이후 로그인마다도 email verified 상태가 재설정된다는 것.
  • 이 자료가 증명하지 않는 것 (명시적 — grep 확인 완료):
    • trustEmail 의 default 값: 본 문서(configuration.adoc)에서 "default"라는 단어가 등장하는 유일한 문장은 line 6 — "{project_name} creates identity providers for each realm and enables them for every application by default" (identity provider 자체의 기본 활성화에 대한 문장이며 Trust Email 필드와 무관). Trust Email 행(line 55-60) 안에는 "default"라는 단어가 전혀 없다. 이 자료는 trustEmail의 기본값(default)을 명시하지 않는다 — 기본값 확정은 Keycloak Admin UI(25.x/26.x) 신규 IdP 생성 폼 캡처가 필요하며 이 문서로 대체 불가. 따라서 D6의 "default=false" 하위 주장은 이 raw 회수 이후에도 여전히 needs-confirmation.
    • Trust Email = ON이 보안 관점에서 권장/비권장이라는 평가 문장 없음 — account-takeover 위험 서술은 이 문서에 없음(그 분석은 별도 raw/branch-notes/feature-keycloak-account-linking-sub-vs-email 영역).
    • Sync Mode가 IMPORT/LEGACY일 때 email verified 상태의 재평가 여부에 대한 명시적 문장 없음 (FORCE 케이스만 명시).
    • Google IdP가 실제로 email_verified claim을 제공하는지 여부 — 이는 Google 측 OIDC 문서(raw/official-docs/google-openid-connect-oidc)의 범위.
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • Keycloak 25.x/26.x Admin UI에서 신규 Google IdP 생성 폼의 Trust Email 토글 기본 상태(체크/언체크) 캡처.
    • Google이 email_verified claim을 모든 계정 유형(Workspace vs 개인 Gmail)에 대해 일관되게 제공하는지 검증.

메모 / Notes

  • 버전 caveat: 발췌 대상은 main(rolling) 브랜치의 AsciiDoc 원본이다. 특정 배포 릴리즈 태그(예: 25.0.x, 26.x)에서는 워딩이나 줄 번호가 다를 수 있다 — 형제 raw raw/official-docs/keycloak-identity-provider-sync-mode-official·raw/official-docs/keycloak-first-broker-login-verify-authenticators-official가 동일하게 갖고 있는 caveat.
  • line 59-60은 AsciiDoc 소스가 한 문장을 두 물리적 줄로 소프트-랩(soft-wrap)한 것이며, 렌더링 시 공백 하나로 이어지는 한 문장이다. self-grep은 원본 두 줄을 각각 검증했고, 두 줄을 정규화(줄바꿈→공백)해 이어붙인 결과도 재검증했다(§ 검증 섹션 참조).
  • 후속으로 볼 만한 것: Verify essential claim / Essential claim 행(line 66-70)도 IdP claim 기반 검증 메커니즘을 다루지만, Trust Email과는 다른 목적(essential claim 존재 여부 검증)이라 이번 발췌 범위에 포함하지 않았다.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink