如何通过Keycloak REST API为各用户属性创建Protocol Mapper

你找到的ProtocolMappers Resource接口、以及对应的ProtocolMapperRepresentation数据结构，完全是官方提供的正确实现，不存在接口找错的问题。
你觉得字段对不上的核心原因是：Keycloak对所有类型的Protocol Mapper采用了通用的序列化设计——管理界面上所有你看到的具体配置项，全部存储在ProtocolMapperRepresentation的config这个Map类型字段中，没有为不同类型的Mapper单独定义独立的结构化字段。这种设计是因为内置、自定义的Mapper种类太多、配置差异极大，用通用键值对存储是合理的架构选择，不是接口设计有缺失。

1. 前置准备
   先获取拥有目标Realmmanage-clients权限的管理员Access Token，作为后续接口调用的鉴权凭证。
2. 定位创建接口
   创建Mapper的REST接口完整路径为：
   POST /admin/realms/{你的目标Realm名称}/clients/{目标客户端的内部UUID}/protocol-mappers/models
   注意路径里的客户端标识是客户端的系统内部UUID，不是界面上展示的客户端ID字符串，如果不知道UUID，可以先调用GET /admin/realms/{Realm名}/clients?clientId={你的客户端ID}查询拿到对应值。
3. 构造请求体（ProtocolMapperRepresentation结构）
   请求体是标准JSON，核心字段说明：
   • name：Mapper在管理界面展示的名称，自定义即可，和你截图里填的名称保持一致就行
   • protocol：对应协议类型，一般填openid-connect（OIDC协议）或saml（SAML协议），和所属客户端的协议类型对齐
   • protocolMapper：决定Mapper逻辑类型的标识字符串，这个值是固定的内置标识——比如选用户属性Mapper就填oidc-usermodel-property-mapper、硬编码Claim就填oidc-hardcoded-claim-mapper、组成员映射就填oidc-group-membership-mapper。不需要硬背所有标识，只要在管理界面上选一次对应类型的Mapper，抓一次浏览器的保存请求，就能拿到准确值。
   • config：你之前疑惑的Map类型字段，所有管理界面上你看到的配置值，都是这个Map的键值对，1:1完全对应。举个例子，配置用户email属性映射到各token的请求体片段：

     {
       "name": "email-mapper",
       "protocol": "openid-connect",
       "protocolMapper": "oidc-usermodel-property-mapper",
       "config": {
         "user.attribute": "email",
         "claim.name": "email",
         "json.type.label": "String",
         "access.token.claim": "true",
         "id.token.claim": "true",
         "userinfo.token.claim": "true"
       }
     }
     

     这个config里的每个键，和管理界面上你看到的配置项是完全对应的，最稳妥的配置方式就是在管理界面上把所有值填对，点保存时抓一次浏览器网络请求，把提交的config字段原封不动复用到你的REST API请求里，不需要自己盲猜键名。

• config字段是纯字符串键值对，哪怕是true/false这类开关值，也要写成字符串格式的"true"/"false"，直接传JSON布尔值会触发格式校验失败
• 不要把protocolMapper的值随便填成自定义字符串，填错内置标识会导致创建出的Mapper没有实际映射逻辑
• 如果创建后发现管理界面上看不到配置生效，优先检查config里的键名是不是和官方内置的标识完全一致，没有拼写错误

注：内容的提问来源于stack exchange，提问作者Saturnian