? 目標

你想要：

• 用戶通過 IdP 登錄（SAML 或 OAuth2）
• Keycloak 自動將 IdP 返回的屬性（如：email、name、role 等）映射到用戶賬戶中
• 并把這些屬性加入到用戶登錄返回的 Access Token 中，供業務系統解析使用

---

? 實現步驟

---

🎯 一、確保 Identity Provider 映射到用戶屬性

1. 登錄 Keycloak 管理后臺
2. 進入 Realm → Identity Providers → 點擊你配置的 IdP（如 azure-ad 或 my-oauth-idp）
3. 切換到 Mappers 標簽頁
4. 創建一組屬性映射，例如：

Mapper Name	Mapper Type	Attribute/Claim	User Attribute
email	Attribute Importer（SAML） 或 Claim to User Attribute（OIDC）	email 或對應 claim	email
name	...	name	firstName
roles	...	roles	realmRoles 或自定義屬性

? 這一步確保用戶登錄時，這些 IdP 屬性會被“寫入”到 Keycloak 用戶模型中。

---

🎯 二、將用戶屬性添加到 Token 中（重點）

你要修改客戶端（client）下的 Token Mapper：

1. 進入你的 Realm → Clients（客戶端）
2. 找到你的業務系統的 client（比如 my-web-app）
3. 點擊進入 → 切換到 Client Scopes 或 Client Settings → 找到 Mappers 或 Client Scopes
4. 添加或修改如下 Mapper：

? 示例：添加自定義屬性到 Token

字段	值
Name	email-into-token
Mapper Type	User Property
Property	email
Token Claim Name	email
Claim JSON Type	String
Add to ID token	?
Add to access token	?
Add to userinfo	?（用于 OIDC userinfo 接口）

你可以多添加幾個：

• username
• firstName
• lastName
• custom-attribute（自定義屬性）

---

? 三、在項目中解析 Token

拿到用戶登錄的 Access Token 后，你的服務只要解析 JWT，就可以直接拿到這些字段：

{"sub": "xxxxx","email": "user@example.com","name": "張三","preferred_username": "zhangsan",...
}

---

📝 注意事項

• 對于 SAML IdP，一定要先把屬性導入成 Keycloak 用戶字段，才能寫入 Token
• 對于 OAuth2/OIDC IdP，可以直接從 claim 映射
• Token 的大小有限，別加太多字段
• 如果想加角色信息，選擇 Mapper Type 為 User Realm Role 或 User Client Role

---

🎁 Bonus：快速調試令牌內容

登錄成功后，你可以訪問：

https://<keycloak-host>/realms/<realm-name>/protocol/openid-connect/token

或在開發工具中解碼 JWT（推薦用 jwt.io）