添加声明式用户配置文件后Quarkus Keycloak Admin Client返回400 Bad Request的原因及预定义用户属性实现方案

咱们先来分析下你遇到的400 Bad Request问题：

你添加的声明式用户配置文件（declarative-user-profile）里，kc.user.profile.config的值是一个嵌套的转义JSON字符串，这种写法很容易出现转义错误——比如多写/漏写了反斜杠，导致Keycloak在解析这个配置时出现语法问题，进而让Admin Client的调用触发内部错误，返回400。另外，这种复杂的嵌套配置和你已有的用户属性定义可能也存在隐性冲突，加重了解析失败的概率。

接下来给你两个靠谱的解决方案，既能解决400问题，又能实现预定义用户属性的需求：

方案一：简化Realm配置文件中的属性定义 #

如果只是要预定义phoneNumber、profilePic这类用户属性，完全不需要写这么复杂的组件配置。你可以把声明式配置简化，确保转义正确，比如：

{
  "realm": "quarkus",
  "enabled": true,
  "components": {
    "org.keycloak.userprofile.UserProfileProvider": [
      {
        "providerId": "declarative-user-profile",
        "config": {
          "kc.user.profile.config": [
            "{\"attributes\":[{\"name\":\"phoneNumber\",\"displayName\":\"Phone Number\",\"multivalued\":false,\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}},{\"name\":\"profilePic\",\"displayName\":\"Profile Picture\",\"multivalued\":false,\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}},{\"name\":\"authType\",\"displayName\":\"Auth Type\",\"multivalued\":false,\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\"]}}]}"
          ]
        }
      }
    ]
  },
  // 保留你原来的groups、users、clients等配置...
}

小提示：可以用在线JSON转义工具把正常的JSON转换成字符串，避免手动转义出错。

方案二：在测试代码中动态配置用户属性 #

这种方式更灵活，也能避免Realm配置文件的复杂嵌套问题。你可以在测试启动后，通过Keycloak Admin Client动态添加用户属性定义：

@QuarkusTest
public class KeycloakAttributeTest {

    @Inject
    Keycloak keycloakAdminClient;

    @BeforeAll
    void setupCustomAttributes() {
        // 目标Realm
        RealmResource realm = keycloakAdminClient.realm("quarkus");
        
        // 构建自定义属性的元数据
        List<AttributeMetadata> customAttributes = new ArrayList<>();
        
        customAttributes.add(AttributeMetadata.builder()
                .name("phoneNumber")
                .displayName("Phone Number")
                .multivalued(false)
                .permissions(AttributePermissions.builder()
                        .view(List.of("admin", "user"))
                        .edit(List.of("admin", "user"))
                        .build())
                .build());
                
        customAttributes.add(AttributeMetadata.builder()
                .name("profilePic")
                .displayName("Profile Picture")
                .multivalued(false)
                .permissions(AttributePermissions.builder()
                        .view(List.of("admin", "user"))
                        .edit(List.of("admin", "user"))
                        .build())
                .build());
                
        customAttributes.add(AttributeMetadata.builder()
                .name("authType")
                .displayName("Auth Type")
                .multivalued(false)
                .permissions(AttributePermissions.builder()
                        .view(List.of("admin", "user"))
                        .edit(List.of("admin"))
                        .build())
                .build());

        // 更新用户配置文件
        DeclarativeUserProfileConfig profileConfig = new DeclarativeUserProfileConfig();
        profileConfig.setAttributes(customAttributes);
        realm.userProfile().update(profileConfig);
    }

    // 你的测试用例写在这里...
}

总结 #

你遇到的400错误核心原因是Realm配置文件中嵌套的转义JSON存在语法问题，导致Keycloak解析失败。建议优先选择方案二（动态配置），它更易于维护和调试；如果一定要用Realm配置文件，务必确保嵌套JSON的转义完全正确。

备注：内容来源于stack exchange，提问作者Kambei