Keycloak admin CLI创建identity provider mapper类转换异常问题

使用Keycloak管理客户端kcadm创建身份提供商（IDP）映射器时，通过JSON文件导入配置可正常完成创建。在脚本化场景下尝试直接通过-s命令参数传递所有配置项，执行以下命令时触发类转换异常：

kcadm create identity-provider/instances/oidc/mappers -r quarkus \
    -s name=Test_CLI \
    -s identityProviderMapper=oidc-role-idp-mapper \
    -s identityProviderAlias=oidc \
    -s config.syncMode=FORCE \
    -s config.claim=roles \ 
    -s config.role=calculate \ 
    -s config.claim.value=CALC

报错信息如下：

class com.fasterxml.jackson.databind.node.TextNode cannot be cast to class
com.fasterxml.jackson.databind.node.ObjectNode 
(com.fasterxml.jackson.databind.node.TextNode and
 com.fasterxml.jackson.databind.node.ObjectNode are in unnamed module of loader 'app')

经排查，异常由参数-s config.claim.value=CALC导致，移除该参数后命令可正常执行。

该现象不是Keycloak的已知Bug，是kcadm参数解析规则与传参写法不匹配导致的用法问题。

• kcadm的-s参数默认将点号.识别为JSON对象的嵌套层级分隔符，会按点分割的路径逐层构建JSON结构
• 原写法中config.claim.value=CALC会被解析为三层嵌套结构：config对象 -> claim对象 -> value属性
• 但同命令中已经通过-s config.claim=roles将config下的claim节点设置为字符串类型（TextNode），后续解析config.claim.value时，程序会尝试将字符串类型的claim节点转换为对象节点（ObjectNode）以追加子属性，直接触发类型转换异常
• 实际上oidc-role-idp-mapper的config配置中，claim和claim.value是config对象下两个平级的配置键，claim.value是完整的键名（本身包含点号），并非claim的子属性，这和JSON文件导入时的平级结构完全一致。

方式1：使用方括号语法标识带点的完整键名 #

对于本身包含点号、不希望点被解析为层级分隔符的配置键，使用config[键名]=值的写法，解析器会将方括号内的整体识别为config Map的完整键名，不会拆分嵌套。修正后命令如下：

kcadm create identity-provider/instances/oidc/mappers -r quarkus \
    -s name=Test_CLI \
    -s identityProviderMapper=oidc-role-idp-mapper \
    -s identityProviderAlias=oidc \
    -s config.syncMode=FORCE \
    -s config.claim=roles \
    -s config.role=calculate \
    -s 'config[claim.value]=CALC'

方式2：直接传递JSON格式请求体 #

如果配置项较多、存在多个带特殊字符的键，可直接通过-b参数传递完整JSON请求体，完全规避路径解析问题，写法和JSON文件导入的结构完全一致：

kcadm create identity-provider/instances/oidc/mappers -r quarkus \
    -b '{
        "name": "Test_CLI",
        "identityProviderMapper": "oidc-role-idp-mapper",
        "identityProviderAlias": "oidc",
        "config": {
            "syncMode": "FORCE",
            "claim": "roles",
            "role": "calculate",
            "claim.value": "CALC"
        }
    }'

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