13 KiB
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 Sync Mode — IMPORT / FORCE / LEGACY / INHERIT Semantics (official) | official-doc | https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker |
|
|
|
2026-07-15 |
Keycloak Identity Provider Sync Mode — IMPORT / FORCE / LEGACY / INHERIT Semantics (official)
Layer:
raw/official-docs/— Keycloak Server Administration Guide, "Identity Broker" chapter. 원문 AsciiDoc source:identity-broker/configuration.adoc(IdP-levelSync Mode필드) +identity-broker/mappers.adoc(mapper-levelSync Mode Override필드). 렌더링된 canonical 페이지(server_admin/index.html#_identity_broker)는 너무 커서 Identity Broker 섹션 이전에 잘리므로, 렌더링을 만드는 upstream AsciiDoc 원본을 GitHub raw 로 직접 발췌했다.
Parent / 활용 branch
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-account-linking-sub-vs-email | D5 (Sync Mode = IMPORT, first login 시점만 attribute 반영) 의 공식 근거. Sync Mode 는 attribute 최신성만 다루고 linking/takeover 안전성(= federated identity key sub)과는 무관하다는 경계를 명시하는 근거이기도 함 |
| raw/branch-notes/feature-keycloak-google-claim-attribute-mapping | D3 (Sync Mode = IMPORT — FORCE 는 사용자가 직접 바꾼 Keycloak attribute 를 매 로그인마다 되돌려 UX 저하) 의 공식 근거. 이전에는 needs-confirmation(raw/official-docs/keycloak-identity-provider-mappers.md#KC-IDP-MAPPER-C5)로만 표시됐던 IMPORT/FORCE/LEGACY/INHERIT verbatim 을 이 문서가 최초로 회수 |
출처 / Source
- 원본 URL (canonical, 렌더링됨 — Identity Broker 섹션 이전에 truncate 되어 실제 fetch 는 아래 두 AsciiDoc 원본으로 수행): https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker
- 실제 fetch 대상 1 (IdP-level
Sync Mode필드): https://raw.githubusercontent.com/keycloak/keycloak/main/docs/documentation/server_admin/topics/identity-broker/configuration.adoc - 실제 fetch 대상 2 (mapper-level
Sync Mode Override필드): https://raw.githubusercontent.com/keycloak/keycloak/main/docs/documentation/server_admin/topics/identity-broker/mappers.adoc - 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
- 발행일: rolling docs (
mainbranch, 확인 시점 기준) - 마지막 확인일: 2026-07-15
왜 저장했는지 / Why archived
raw/branch-notes/feature-keycloak-account-linking-sub-vs-email D5 와 raw/branch-notes/feature-keycloak-google-claim-attribute-mapping D3 는 둘 다 "Sync Mode = IMPORT" 를 결정했지만, 근거 raw 였던 keycloak-identity-provider-mappers.md 는 Sync Mode 옵션의 verbatim 을 회수하지 못해 KC-IDP-MAPPER-C5 를 needs-confirmation 으로 남겼다. 이 문서는 그 gap 을 메우는 verbatim 회수이며, 동시에 Sync Mode 가 attribute 최신성(freshness)만 통제하고 account-linking/takeover 안전성(=federated identity 의 linking key 가 sub 인지 email 인지)과는 별개 축이라는 경계를 명시하기 위해 보관한다.
핵심 인용 / Key quotes (verbatim, 5문장)
[configuration.adoc, "Common Configuration" 표 —
Sync Mode행, line 83] "Strategy to update user information from the identity provider through mappers. When choosing legacy, {project_name} used the current behavior. Import does not update user data and force updates user data when possible."
[mappers.adoc, "Mapping claims and assertions" Procedure step 6, line 115] "Select a value for Sync Mode Override. The mapper updates user information when users log in repeatedly according to this setting."
[mappers.adoc, Procedure step 6.b (
import), line 117] "Select import to import data from when the user was first created in {project_name} during the first login to {project_name} with a particular identity provider."
[mappers.adoc, Procedure step 6.c (
force), line 118] "Select force to update user data at each user login."
[mappers.adoc, Procedure step 6.d (
inherit), line 119] "Select inherit to use the sync mode configured in the identity provider. All other options will override this sync mode."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-SYNCMODE-C1 | IdP-level Sync Mode 필드는 "identity provider 로부터 mapper 를 통해 user 정보를 갱신하는 전략"이며, legacy = 기존 동작 유지, import = user 데이터를 갱신하지 않음, force = 가능할 때 user 데이터를 갱신함 |
[configuration.adoc, line 83] "Strategy to update user information from the identity provider through mappers. When choosing legacy, {project_name} used the current behavior. Import does not update user data and force updates user data when possible." | official-vendor-doc |
IdP 설정 화면의 Sync Mode 필드(모든 mapper 의 default 값) — attribute 최신성(update timing) 결정에만 적용 |
이 quote 는 attribute 값이 언제 갱신되는지만 말한다. federated identity 의 linking key(= Google sub claim)나 account-linking/takeover 안전성에 대해서는 아무것도 규정하지 않는다 — 이 문서 전체에 sub claim 이나 linking key 언급이 없음(§메모 참조) |
| KC-SYNCMODE-C2 | mapper 추가 시 Sync Mode Override 값을 선택하며, 이 설정에 따라 "user 가 반복 로그인할 때" mapper 가 user 정보를 갱신한다 — 즉 Sync Mode 는 mapper 단위로도 override 가능한 필드다 |
[mappers.adoc, line 115] "Select a value for Sync Mode Override. The mapper updates user information when users log in repeatedly according to this setting." | official-vendor-doc |
IdP-level Sync Mode(C1) 와 mapper-level Sync Mode Override(C2~C4) 가 별개 필드로 존재한다는 구조 증거 |
"반복 로그인"의 정확한 트리거(매 요청 vs 매 full 재인증 vs token refresh)는 이 인용 범위 밖. linking key 선택이나 takeover 방지와는 무관 |
| KC-SYNCMODE-C3 | mapper-level Sync Mode Override = import 는 "{project_name} 에 특정 identity provider 로 first login 할 때 user 가 처음 생성된 시점의 데이터를 import" 한다는 뜻 |
[mappers.adoc, line 117] "Select import to import data from when the user was first created in {project_name} during the first login to {project_name} with a particular identity provider." | official-vendor-doc |
mapper 가 attribute 를 첫 로그인 시점에만 채우고 이후 IdP 측 변경을 반영하지 않는다는 결정(예: D5/D3 의 근거) | attribute import 시점만 규정한다. IMPORT 를 선택하는 것이 account takeover 를 방지한다는 취지의 문장이 아니며, 그런 보안적 함의는 이 문서에 없다. linking key 는 sub claim 으로 별도 결정되는 사안 |
| KC-SYNCMODE-C4 | mapper-level Sync Mode Override = force 는 "매 user 로그인마다 user 데이터를 갱신"한다는 뜻 |
[mappers.adoc, line 118] "Select force to update user data at each user login." | official-vendor-doc |
attribute 를 IdP 값으로 항상 최신 유지하고 싶을 때(freshness 우선) 의 옵션 근거 | FORCE 가 "더 안전"하거나 "더 위험"하다는 취지의 문장이 아니다 — 이 인용은 순수하게 갱신 빈도만 말한다. account-linking/takeover 위험은 이 필드가 아니라 linking key(=sub vs email) 선택에서 발생 |
| KC-SYNCMODE-C5 | mapper-level Sync Mode Override = inherit 는 "identity provider 에 설정된 sync mode 를 사용하며, 다른 모든 옵션은 이 sync mode 를 override" 한다는 뜻 — 즉 IdP-level Sync Mode(C1) 가 default 이고, mapper 마다 import/force/legacy 를 명시하면 그 mapper 만 개별적으로 override 된다는 계층 구조를 확정 |
[mappers.adoc, line 119] "Select inherit to use the sync mode configured in the identity provider. All other options will override this sync mode." | official-vendor-doc |
IdP-level Sync Mode 를 default 로 두고 특정 mapper 만 다른 정책을 쓰고 싶을 때의 override 메커니즘 근거 | 같은 IdP 에 여러 mapper 가 서로 다른 override 값을 가질 때의 충돌/우선순위 처리는 이 인용 범위 밖. 이 필드 역시 linking key 선택이나 takeover 방지와 무관 |
Strength 근거
모든 claim 이 official-vendor-doc — Keycloak(Red Hat) 공식 Server Administration Guide 원문(AsciiDoc)에서 직접 self-grep 검증된 verbatim 이며, 3rd-party 재구성이나 tutorial 이 아니다.
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
KC-SYNCMODE-C1~C5: IdP-levelSync Mode4개 값(legacy/import/force/inherit— IdP 레벨에는legacy/import/force3개, mapper 레벨Sync Mode Override에inherit포함 4개)의 attribute 갱신 타이밍 의미와, IdP-level 필드가 default 이고 mapper-level 필드가 이를 override 할 수 있다는 계층 구조.
- 이 자료가 증명하지 않는 것 (명시적 — 모든 claim 의 "Does not prove" 참조):
- account-linking/takeover 안전성: 이 문서 어디에도 federated identity 의 linking key(= Google
subclaim vsemail)에 대한 언급이 없다(§메모의 grep 결과 참조). Sync Mode 는 "이미 linking 된 사용자의 attribute 를 언제 갱신할지"만 다루며, "누구와 linking 할지(어떤 값을 primary key 로 쓸지)"는 전혀 다른 결정이다. raw/branch-notes/feature-keycloak-account-linking-sub-vs-email D1(linking key =sub)의 근거로 이 문서를 사용하면 안 됨 — 그 근거는raw/official-docs/google-openid-connect-oidc.md#GOIDC-C3이다. - Google 브로커링에 대해 특정 Sync Mode 값을 권장하는 문장 없음(§메모 참조) — 값 선택은 조직 정책(org-policy) 사안.
- "force" 선택 시 정확한 갱신 트리거(요청마다 vs 세션 갱신마다) 의 세부 메커니즘.
- 동일 IdP 에 여러 mapper 가 서로 다른
Sync Mode Override를 가질 때 충돌 처리 방식.
- account-linking/takeover 안전성: 이 문서 어디에도 federated identity 의 linking key(= Google
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- Keycloak 25.x Admin UI 캡처로
Sync Mode드롭다운의 실제 라벨(대소문자, 표기)이 이 AsciiDoc 원문과 일치하는지 확인. - FORCE 선택 시
email_verified재평가 타이밍(Trust Email 필드와의 상호작용)은 별도 quote(§메모 Q6 후보) 확인 필요 — 이번 발췌에는 미포함.
- Keycloak 25.x Admin UI 캡처로
메모 / Notes
- Google 브로커링 특정 Sync Mode 권장 문장 없음: 이 두 AsciiDoc 원문(
configuration.adoc,mappers.adoc) 어디에도 "Google" 또는 특정 social provider 에 대해 특정 Sync Mode 값을 권장하는 문장이 없다. Sync Mode 선택은 벤더 가이드가 아니라 조직 정책(운영 팀이 "attribute 최신성 vs 사용자 편집 보존" 트레이드오프를 어떻게 볼지)에 달려 있다. - linking-key 무관성 확인(grep 결과): 두 원문에
\bsub\b(claim 이름으로서) 또는 "federated identity 의 key"를 뜻하는 언급이 없다. "Account Linking Only" 라는 필드가configuration.adoc에 존재하지만, 이는 "이 IdP 를 신규 로그인이 아니라 기존 계정 linking 전용으로 제한"하는 완전히 다른 스위치이며 Sync Mode 와 별개 행(row)이다. 따라서 이 자료를 D1(linking key =sub)의 근거로 쓰면 안 되고, D5/D3(Sync Mode = IMPORT)의 근거로만 써야 한다. - 후속으로 볼 만한 것:
configuration.adoc의Trust Email행에 "if the sync mode is set toFORCE" 문장이 존재 — FORCE 가email_verified재평가에 영향을 준다는 근거가 될 수 있으나, 이번 발췌의 5-quote 상한(3~5개) 내에서는 포함하지 않았다. 필요 시 추가 발췌 대상. raw/official-docs/keycloak-identity-provider-mappers.md의KC-IDP-MAPPER-C5(Sync Modeneeds-confirmation)는 이 문서의 verbatim 회수로official-vendor-doc로 승격 가능 — 단, 그 파일 편집은 본 dispatch 범위 밖(별도 migrate 필요).
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/keycloak-identity-provider-mappers — 동일 "Mapping claims and assertions" 섹션의 mapper 종류 + Sync Mode 를 다루려다 verbatim 회수 실패(
needs-confirmation)했던 이전 raw. 본 문서가 그 gap 을 메움. - raw/official-docs/keycloak-identity-brokering-overview-official — federated identity 모델 개요.
- raw/official-docs/keycloak-first-broker-login-flow — first login 시 mapper/Sync Mode 와 결합되는 분기.
- raw/official-docs/google-openid-connect-oidc — linking key(
sub)의 영구성 근거 (Sync Mode 와는 별개 결정 축).
- raw/official-docs/keycloak-identity-provider-mappers — 동일 "Mapping claims and assertions" 섹션의 mapper 종류 + Sync Mode 를 다루려다 verbatim 회수 실패(
- 인용한 wiki: (미작성)