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

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 Identity Provider Mappers (claim → attribute/role)	official-doc	https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers		raw	medium	keycloak-patterns p2b-spa-google-federation idp-brokering claim-mapping mappers	keycloak-patterns	feature-keycloak-internal-spa-direct-google-federation feature-keycloak-google-claim-attribute-mapping feature-keycloak-idp-mappers-claim-to-role	2026-05-25	2026-05-27

Keycloak Identity Provider Mappers

Layer: raw/official-docs/ — Keycloak Server Administration Guide, "Mapping claims and assertions" 섹션 발췌. P2B 의 Google claim → Keycloak user/role 매핑 정책 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation	P2B 에서 Google claim 을 Keycloak user model 로 옮기는 매커니즘이 mapper 라는 공식 근거
raw/branch-notes/feature-keycloak-google-claim-attribute-mapping	email, name, picture, hd 등 Google claim 을 Keycloak user attribute 로 import 하는 mapper 채택 근거
raw/branch-notes/feature-keycloak-idp-mappers-claim-to-role	hd=mycompany.com 같은 claim 값 분기로 role 자동 부여하는 Advanced Claim to Role mapper 채택 근거

컨텍스트

P2B 에서 Google 로그인 사용자에게 Keycloak 자체 user/role 을 어떻게 만들/부여할지 결정. 공식 문서가 직접 정의하는 mapper 메커니즘 + sync mode 정책이 출처.

출처 / Source

• 원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers
• 아카이브 URL: (미수집)
• 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
• 발행일: rolling docs
• 마지막 확인일: 2026-05-27
• 주의: mapper 종류 세부 표 / Sync Mode 옵션의 verbatim 발췌는 본 페이지에서 부분적으로만 회수됨 → 일부 항목은 needs-confirmation.

핵심 인용 / Key quotes (verbatim)

[§Mapping claims and assertions] "When doing IDP federation you can map incoming tokens and assertions to user and session attributes."

[§Mapping claims and assertions] "This helps you propagate identity information from the external IDP to your client requesting authentication."

[§Identity provider mappers — purpose] "Identity provider mappers ... enable translation of external credentials into Keycloak's user model."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-IDP-MAPPER-C1	IDP federation 시 incoming token / assertion 을 Keycloak user attribute 와 session attribute 로 mapping 가능	[§Mapping claims and assertions] "When doing IDP federation you can map incoming tokens and assertions to user and session attributes."	official-vendor-doc	모든 외부 IDP federation (OIDC / SAML)	session attribute 와 user attribute 의 lifetime 차이 / 우선순위는 본 인용에 없음
KC-IDP-MAPPER-C2	mapping 의 목적은 외부 IDP 의 identity 정보를 Keycloak client (요청 측 application) 로 전파 (propagate) 하기 위함	[§Mapping claims and assertions] "This helps you propagate identity information from the external IDP to your client requesting authentication."	official-vendor-doc	Keycloak client 가 외부 IDP claim 을 access token / ID token 에서 받아야 하는 경우	어떤 claim 이 자동으로 전파되는지 / 어떤 것이 명시적 mapper 가 필요한지 default 동작은 본 인용 범위 밖
KC-IDP-MAPPER-C3	Identity provider mapper 의 핵심 기능은 external credential 을 Keycloak 의 user model 로 translation	[§Identity provider mappers — purpose] "Identity provider mappers ... enable translation of external credentials into Keycloak's user model."	official-vendor-doc	OIDC / SAML 외부 IDP credential	translation 의 정확한 conflict 해소 정책 (동일 attribute 가 mapper 와 local 양쪽에 있을 때) 은 본 인용에 없음
KC-IDP-MAPPER-C4	구체적 mapper 종류 목록 (Attribute Importer, Hardcoded Attribute, Hardcoded Role, Username Template Importer, Advanced Claim to Role 등) 은 본 페이지의 verbatim 발췌로 확인되지 않음 — Keycloak Admin UI / 다른 sub-page 일치로만 알려짐	(verbatim 부재 — 부재 자체가 claim)	needs-confirmation	mapper 선택 결정 (어떤 mapper 를 쓸지)	해당 mapper 들이 존재하지 않는다는 뜻은 아님. Admin UI / 코드 직접 확인 필요
KC-IDP-MAPPER-C5	Sync Mode 옵션 (IMPORT / FORCE / LEGACY / INHERIT) 의 의미 / default 값은 본 페이지의 verbatim 발췌로 확인되지 않음	(verbatim 부재 — 부재 자체가 claim)	needs-confirmation	Sync Mode 결정 (Google 측 attribute 변경 반영 정책)	Sync Mode 옵션이 존재하지 않는다는 뜻은 아님. Admin UI 직접 확인 필요

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • KC-IDP-MAPPER-C1 ~ C3: mapper 의 일반적 목적 (claim → attribute/session/user model translation, propagate to client)
• 이 자료가 증명하지 않는 것:
  • KC-IDP-MAPPER-C4: 구체적 mapper 종류와 각 mapper 의 정확한 동작
  • KC-IDP-MAPPER-C5: Sync Mode 옵션의 의미 / default
  • Google hd claim 의 표준 의미 / 보장 수준 (Google 측 문서)
  • picture URL 의 expiry 정책 (Google 측 문서)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • P2B 에서 email / email_verified / name / picture / hd 각 mapper 의 실제 설정 화면값 (Admin UI 캡쳐)
  • hd != mycompany.com 사용자를 거부하는 정확한 메커니즘 (mapper vs First Broker Login Flow)
  • Sync Mode = FORCE 채택 시 Google 측 이름 변경의 실제 반영 시점 (token refresh vs full re-login)

P2B 운영 메모 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아니라 P2B 운영 결정. wiki 추출 시 wiki/concepts/ 또는 wiki/projects/ 로 옮겨야 함.

Mapper 종류 (Keycloak 4.x ~ 26.x, 일반적으로 알려진 목록 — needs-confirmation)

• Attribute Importer — 외부 IdP claim → Keycloak user attribute로 복사. 가장 흔함.
• Hardcoded Attribute — 외부 IdP 통해 들어온 user에게 고정 attribute 부여.
• Hardcoded Role — 외부 IdP 통해 들어온 user에게 고정 role 부여.
• Username Template Importer — username 형식 강제 (예: ${ALIAS}.${CLAIM.sub}).
• Advanced Claim to Role — 특정 claim 값일 때만 role 부여 (예: hd=mycompany.com일 때 admin role).
• Advanced Attribute to Role — Advanced Claim to Role의 attribute 버전.
• Claim to Role — 단순 claim → role 매핑.
• External Group to Role — 외부 IdP group claim → Keycloak role.

Sync Mode (needs-confirmation)

• IMPORT — 첫 로그인 시에만 import, 이후 변경 무시.
• FORCE — 매 로그인마다 외부 IdP claim 값으로 덮어쓰기.
• LEGACY — 4.0 이전 동작 (호환용).
• INHERIT — IdP 기본값 사용.

P2B 패턴에서 필요한 매핑 예시

Google claim	Keycloak target	Mapper
sub	federated identity (자동)	(built-in)
email	user.email	Attribute Importer
email_verified	user.attributes.emailVerified	Attribute Importer
name	user.firstName + lastName 또는 attribute	Attribute Importer
picture	user.attributes.picture	Attribute Importer
hd == mycompany.com	role internal-employee	Advanced Claim to Role
hd != mycompany.com	(거부)	First Broker Login Flow 커스텀

P2B 운영 결정 포인트

• Sync Mode 결정: FORCE면 Google에서 이름 변경 시 즉시 반영 (보통 권장). IMPORT면 첫 로그인 이후 Keycloak 내부 변경이 우선.
• picture URL: Google profile picture URL은 OAuth scope 만료 시 깨질 수 있음. CDN 캐싱 정책 필요.

메모 / Notes

• 2026-05-27 재migration: WebFetch 권한 부재로 mapper 종류 표 / Sync Mode 옵션의 verbatim 재검증 불가. 기존 author 의 3건 verbatim 발췌만 보존, mapper 목록·Sync Mode 는 명시적으로 needs-confirmation (C4, C5).
• 후속: Admin UI 캡쳐 / 다른 sub-page 직접 발췌 보강 후 C4 C5 를 official-vendor-doc 으로 승격.

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/keycloak-identity-brokering-overview-official — broker 전반 개요
  • raw/official-docs/keycloak-identity-broker-spi — SPI 확장 (built-in + mapper 로 충분한지 결정)
  • raw/official-docs/keycloak-first-broker-login-flow — first-login 시 mapper 와 결합되는 분기
• 인용하는 branch:
  • raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation
  • raw/branch-notes/feature-keycloak-google-claim-attribute-mapping
  • raw/branch-notes/feature-keycloak-idp-mappers-claim-to-role
• 인용한 wiki: (미작성)