Keycloak创建客户端级角色时出现找不到客户端的404错误求助

问题背景 #

尝试通过keycloak-admin-client创建客户端级角色失败，改用Postman调用API仍无法成功。已确认目标客户端存在，操作用户拥有管理员权限，且Keycloak配置正常（可成功创建新用户），但创建角色接口始终返回404错误。

相关代码 #

public int createClient(String clientId) {
    ClientRepresentation clientRepresentation = new ClientRepresentation();
    clientRepresentation.setClientId(clientId);
    clientRepresentation.setPublicClient(false);
    clientRepresentation.setEnabled(true);
    clientRepresentation.setServiceAccountsEnabled(true);

    Response response = clientsManager.create(clientRepresentation);
    int statusCode = response.getStatus();
    log.info("HTTP Status of client creation = {}", statusCode);

    if (statusCode == 201) fillClientWithRoles(clientId);
    return statusCode;
}

public void fillClientWithRoles(String clientId) {
    ClientResource clientResource = clientsManager.get(clientId);
    log.info("client: {}", clientResource);
    for (ClientRole role : ClientRole.values()) {
        RoleRepresentation roleRepresentation = new RoleRepresentation();
        roleRepresentation.setName(role.name());
        roleRepresentation.setClientRole(true);
        roleRepresentation.setComposite(false);

        clientResource.roles().create(roleRepresentation);
    }
}

错误日志 #

2024-05-28T14:53:08.288+03:00 ERROR 14920 --- [portal-ms] [io-60005-exec-1] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: jakarta.ws.rs.NotFoundException: HTTP 404 Not Found] with root cause

jakarta.ws.rs.NotFoundException: HTTP 404 Not Found
    at org.jboss.resteasy.client.jaxrs.internal.ClientInvocation.handleErrorStatus(ClientInvocation.java:242) ~[resteasy-client-6.2.9.Final.jar:6.2.9.Final]
    at org.jboss.resteasy.client.jaxrs.internal.proxy.extractors.DefaultEntityExtractorFactory$3.extractEntity(DefaultEntityExtractorFactory.java:41) ~[resteasy-client-6.2.9.Final.jar:6.2.9.Final]
    at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invokeSync(ClientInvoker.java:136) ~[resteasy-client-6.2.9.Final.jar:6.2.9.Final]
    at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invoke(ClientInvoker.java:103) ~[resteasy-client-6.2.9.Final.jar:6.2.9.Final]
    at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientProxy.invoke(ClientProxy.java:102) ~[resteasy-client-6.2.9.Final.jar:6.2.9.Final]
    at jdk.proxy2/jdk.proxy2.$Proxy192.create(Unknown Source) ~[na:na]
    at ru.gnivc.portalservice.service.KeycloakService.fillClientWithRoles(KeycloakService.java:124) ~[classes/:na]
    at ru.gnivc.portalservice.service.KeycloakService.createClient(KeycloakService.java:109) ~[classes/:na]
    at ru.gnivc.portalservice.service.CompanyService.createCompany(CompanyService.java:27) ~[classes/:na]
    at ru.gnivc.portalservice.controller.CompanyController.createCompany(CompanyController.java:22) ~[classes/:na]

排查与解决方法 #

1. 客户端ID与内部UUID混淆 #

keycloak-admin-client的clientsManager.get()方法若传入业务自定义的clientId，部分Keycloak版本无法正确定位客户端——Keycloak内部通过UUID作为客户端的唯一标识。创建客户端后，需从响应中提取UUID用于后续操作：

public int createClient(String clientId) {
    ClientRepresentation clientRepresentation = new ClientRepresentation();
    clientRepresentation.setClientId(clientId);
    clientRepresentation.setPublicClient(false);
    clientRepresentation.setEnabled(true);
    clientRepresentation.setServiceAccountsEnabled(true);

    Response response = clientsManager.create(clientRepresentation);
    int statusCode = response.getStatus();
    log.info("HTTP Status of client creation = {}", statusCode);

    if (statusCode == 201) {
        // 从响应头获取客户端UUID
        String clientLocation = response.getHeaderString("Location");
        String clientUuid = clientLocation.substring(clientLocation.lastIndexOf('/') + 1);
        fillClientWithRoles(clientUuid);
    }
    return statusCode;
}

2. 权限缺失 #

即使用户拥有管理员角色，也可能缺少manage-clients或manage-client-roles权限。检查用户所属角色的权限列表，确保包含这两项权限，或直接为用户添加该权限。

3. 版本不兼容 #

确保keycloak-admin-client依赖版本与Keycloak服务器版本完全一致。版本不匹配会导致API路径、请求格式不一致，引发404错误。

4. Postman请求路径验证 #

若Postman也失败，检查请求URL是否正确。创建客户端角色的标准路径为：
POST {Keycloak地址}/admin/realms/{你的Realm}/clients/{客户端UUID}/roles
注意路径中使用客户端UUID而非业务clientId，且路径拼写无误。

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