✅ 目标

你想要：

• 用户通过 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）