如何通过Keycloak为GitHub Enterprise所有用户配置主邮箱地址？

1. 调整Keycloak侧SAML断言属性映射 #

• 进入Keycloak对应GitHub Enterprise的客户端配置页，找到「属性映射」（Mapper）配置栏
• 添加两个必填属性映射：
  • 用户名映射：将Keycloak内置的username属性，映射为SAML断言的http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 以及 urn:oid:0.9.2342.19200300.100.1.1 两个标准属性，同时开启「包含在断言中」开关
  • 邮箱映射：将Keycloak内置的email属性，映射为SAML断言的http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 以及 urn:oid:0.9.2342.19200300.100.1.3 两个标准属性，同样开启「包含在断言中」开关
• 可选配置：如果需要强制同步用户名不被截断，可添加自定义属性github_username，值绑定Keycloak的username字段，明确传递给GitHub Enterprise

2. 调整GitHub Enterprise侧SAML配置 #

• 进入GitHub Enterprise 管理控制台 → 「用户管理」→ 「身份验证」→ 「SAML」配置页
• 找到「属性映射」配置区域，做如下修改：
  • 用户名属性字段：填写你在SAML断言中传递的用户名字段名，使用上述标准属性填name即可，若使用自定义github_username则填对应字段名
  • 邮箱属性字段：填写email，对应上述标准邮箱断言属性
• 务必勾选「自动同步SAML属性到用户资料」选项，该选项会在每次用户SAML登录时，自动用断言中的属性覆盖GitHub Enterprise侧的用户资料，是实现自动同步的核心开关
• 可选配置：勾选「禁止用户修改邮箱地址」，避免用户手动修改后和Keycloak存储的信息不一致
• 保存配置后重启GitHub Enterprise服务生效

3. 验证与存量用户处理 #

• 新用户首次登录测试：触发完整SAML登录流程，查看GitHub Enterprise侧生成的用户名、邮箱是否和Keycloak存储的信息完全一致，是否不再弹出手动添加邮箱的通知
• 存量用户处理：对于配置前已存在的用户，可通过GitHub Enterprise内置的ghe-user-sync命令行工具批量同步属性，命令参考：ghe-user-sync --saml --sync-attributes，执行后所有存量用户的资料会和SAML断言的最新属性对齐

注意：如果配置后仍出现邮箱不自动填充的问题，可在Keycloak中开启SAML断言日志，确认邮箱、用户名属性确实被正确包含在返回给GitHub Enterprise的断言中，排除属性名拼写错误导致的同步失败。

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