llm-wiki/raw/official-docs/keycloak-identity-provider-trust-email-official.md

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

- 원본 URL (canonical, 렌더링됨 — Identity Broker 섹션 이전에 truncate 되어 실제 fetch 는 아래 AsciiDoc 원본으로 수행): https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker
- 실제 fetch 대상 (AsciiDoc 원본, `Trust Email` 행 포함): https://raw.githubusercontent.com/keycloak/keycloak/main/docs/documentation/server_admin/topics/identity-broker/configuration.adoc
- 아카이브 URL: (미수집 — 렌더링 페이지 자체가 canonical citation 역할)
- 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
- 발행일: rolling docs (`main` branch, 확인 시점 기준 — 특정 릴리즈 태그의 정확한 워딩/줄 번호는 다를 수 있음)
- 마지막 확인일: 2026-07-16

## 왜 저장했는지 / 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 / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/keycloak-identity-provider-sync-mode-official]] — 같은 `configuration.adoc`의 `Sync Mode` 행 verbatim. `Trust Email`과 `FORCE`의 상호작용(KC-TRUSTEMAIL-C3)이 이 문서와 겹치는 지점.
  - [[raw/official-docs/keycloak-identity-brokering-overview-official]] — federated identity 모델 개요.
  - [[raw/official-docs/google-openid-connect-oidc]] — Google이 `email_verified` claim을 제공하는지에 대한 근거(별도 확인 필요).
  - [[raw/official-docs/keycloak-google-idp-setup]] — Google IdP 등록 절차 (Trust Email 필드가 등장하는 admin 화면).
- 인용한 wiki: (미작성)