编程创建Keycloak客户端并分配realm-management的view-users角色

我之前也碰到过一模一样的问题！你已经成功创建了客户端，但角色分配没生效，核心原因是你需要给客户端的服务账户用户分配角色，而不是直接给客户端分配，而且要明确是realm-management客户端下的角色。下面是完整的解决方案：

关键前提 #

你已经开启了serviceAccountsEnabled(true)，这意味着这个客户端的权限是通过它对应的服务账户用户来实现的，所有角色都要分配给这个用户，而不是客户端本身。

完整步骤及代码 #

1. 获取新创建客户端的真实ID #

注意：你创建客户端时设置的setId("my-client")可能不会被Keycloak采纳，它会自动生成一个唯一ID，所以必须通过clientId查询获取真实的客户端对象：

// 创建客户端后，查询获取实际的客户端
List<ClientRepresentation> clients = keycloakAdmin.realm("my-realm")
    .clients()
    .findByClientId("my-client");
if (clients.isEmpty()) {
    throw new RuntimeException("Failed to find created client");
}
ClientRepresentation targetClient = clients.get(0);
String targetClientId = targetClient.getId();

2. 获取realm-management客户端的view-users角色 #

view-users是属于realm-management这个客户端的角色，不是Realm级别的角色，所以要从该客户端下获取：

// 获取realm-management客户端
ClientRepresentation realmMgmtClient = keycloakAdmin.realm("my-realm")
    .clients()
    .findByClientId("realm-management")
    .get(0);
String realmMgmtClientId = realmMgmtClient.getId();

// 获取view-users角色
RoleRepresentation viewUsersRole = keycloakAdmin.realm("my-realm")
    .clients()
    .get(realmMgmtClientId)
    .roles()
    .get("view-users")
    .toRepresentation();

3. 给客户端的服务账户分配角色 #

找到客户端对应的服务账户用户，然后将view-users角色分配给它：

// 获取目标客户端的服务账户用户
UserRepresentation serviceAccount = keycloakAdmin.realm("my-realm")
    .clients()
    .get(targetClientId)
    .getServiceAccountUser()
    .toRepresentation();
String serviceAccountUserId = serviceAccount.getId();

// 分配角色：指定为realm-management客户端下的角色
keycloakAdmin.realm("my-realm")
    .users()
    .get(serviceAccountUserId)
    .roles()
    .clientLevel(realmMgmtClientId)
    .add(Collections.singletonList(viewUsersRole));

常见错误点排查 #

• 错误地给客户端本身分配角色：客户端只是一个身份，权限载体是它的服务账户用户，必须给用户分配角色
• 混淆Realm角色和客户端角色：view-users是realm-management客户端的私有角色，不能用realmLevel()方法分配，必须用clientLevel(realmMgmtClientId)
• 使用自定义的客户端ID而非Keycloak生成的ID：创建客户端时的setId不一定生效，必须通过查询获取真实ID

把这些步骤整合到你的代码里，应该就能成功让新客户端拥有列出用户的权限了！

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