Keycloak配置：将Azure AD邮箱映射至自动创建的用户

确认声明映射的目标字段准确性 #

• 先检查身份提供商配置里的映射规则：你需要把preferred_username或upn明确映射到用户资料的**邮箱（email）**字段，别误映射到用户名等其他字段。不同系统对邮箱字段的标识可能不同，比如email、mail或userPrincipalName，要对应到系统实际接收的字段名。

验证Azure AD的声明输出配置 #

• 确保Azure AD应用注册里，preferred_username和upn是包含在**ID令牌（ID Token）**中的（不是仅在访问令牌）。解码ID令牌确认这两个声明的内容是有效的邮箱格式（比如user@domain.com）——如果upn是内部账号格式而非邮箱，优先用preferred_username，它通常对应用户的邮箱地址。

检查自动创建用户的认证流规则 #

• 很多系统的自动用户创建逻辑需要手动开启“从声明填充邮箱”的选项，或者在认证流的用户属性映射环节绑定对应规则。比如在IAM系统的属性映射面板里，添加规则：邮箱 = preferred_username（或upn），并确保规则处于启用状态。
• 排查是否有默认逻辑覆盖邮箱字段：部分系统默认会留空邮箱，除非明确配置映射规则，哪怕声明存在也不会自动填充。

排查目标系统的字段限制 #

• 检查目标系统的邮箱字段是否有格式校验，比如是否严格要求xxx@xxx.xxx格式。如果preferred_username或upn格式不符合，系统会丢弃该值，导致邮箱为空。
• 确认目标系统是否允许通过声明自动填充邮箱：有些系统的邮箱字段需要手动验证，自动创建时不会导入声明值，这种情况需要修改系统配置，开启自动填充权限。

测试验证 #

• 修改配置后，退出当前登录，用新的Azure AD账号重新登录触发自动创建流程，查看用户邮箱字段是否填充。
• 若仍未解决，开启系统认证日志，查看ID令牌声明是否被正确接收，以及映射过程中是否有错误提示。

内容的提问来源于stack exchange，提问作者One Developer