127 lines
9.1 KiB
Markdown
127 lines
9.1 KiB
Markdown
---
|
|
title: Keycloak Identity Provider Mappers (claim → attribute/role)
|
|
source_type: official-doc
|
|
url: https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers
|
|
archive_url:
|
|
status: raw
|
|
confidence: medium
|
|
tags: [keycloak-patterns, p2b-spa-google-federation, idp-brokering, claim-mapping, mappers]
|
|
related_projects: [keycloak-patterns]
|
|
related_branches: [feature-keycloak-internal-spa-direct-google-federation, feature-keycloak-google-claim-attribute-mapping, feature-keycloak-idp-mappers-claim-to-role]
|
|
created: 2026-05-25
|
|
last_reviewed: 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: (미작성)
|