Keycloak如何结合角色与用户属性实现分页搜索用户？

针对你的需求，这里提供几种可行的实现方式，覆盖不同场景和Keycloak版本兼容性：

方法一：先属性搜索再过滤角色（小数据量场景适用） #

先通过属性接口获取匹配的用户列表，再过滤出拥有目标角色的用户，最后手动处理分页。适合用户量不大或搜索结果集较小的场景：

// 先查询所有匹配属性的用户（暂时跳过分页，避免漏数据）
List<UserRepresentation> users = realmResource.users().search(
        request.getUserName(),
        request.getFirstName(),
        request.getLastName(),
        request.getEmail(),
        0,
        Integer.MAX_VALUE);

// 获取目标角色的信息
RoleRepresentation targetRole = realmResource.roles().get(request.getRole()).toRepresentation();

// 过滤出拥有该角色的用户
List<UserRepresentation> filteredUsers = users.stream()
        .filter(user -> {
            // 获取用户的所有 Realm 级角色（含直接/间接关联）
            List<RoleRepresentation> userRoles = realmResource.users().get(user.getId()).roles().realmLevel().listAll();
            return userRoles.stream().anyMatch(role -> role.getName().equals(targetRole.getName()));
        })
        .collect(Collectors.toList());

// 手动执行分页逻辑
int start = page * size;
int end = Math.min(start + size, filteredUsers.size());
List<UserRepresentation> paginatedUsers = filteredUsers.subList(start, end);

注意：此方法在用户量较大时性能会下降，因为需要先拉取大量用户再过滤。

方法二：使用Keycloak Admin Client高级查询（推荐） #

方式A：通过UserQueryCriteria构建组合查询 #

较新版本的Keycloak Admin Client（15+）支持直接通过UserQueryCriteria同时指定属性和角色条件：

// 构建包含属性和角色的查询条件
UserQueryCriteria criteria = UserQueryCriteria.create()
        .username(request.getUserName())
        .firstName(request.getFirstName())
        .lastName(request.getLastName())
        .email(request.getEmail())
        .role(request.getRole());

// 执行分页查询
List<UserRepresentation> users = realmResource.users().search(criteria, page * size, size);

方式B：利用带角色ID参数的重载搜索方法 #

如果你的Keycloak版本不支持UserQueryCriteria的角色参数，可以用search的重载方法，通过角色ID过滤的同时结合属性搜索：

// 构建属性查询的q参数（支持多条件组合）
StringBuilder qBuilder = new StringBuilder();
if (StringUtils.isNotBlank(request.getUserName())) qBuilder.append("username:" + request.getUserName() + " ");
if (StringUtils.isNotBlank(request.getFirstName())) qBuilder.append("firstName:" + request.getFirstName() + " ");
if (StringUtils.isNotBlank(request.getLastName())) qBuilder.append("lastName:" + request.getLastName() + " ");
if (StringUtils.isNotBlank(request.getEmail())) qBuilder.append("email:" + request.getEmail() + " ");
String q = qBuilder.toString().trim();

// 获取目标角色的ID
RoleRepresentation role = realmResource.roles().get(request.getRole()).toRepresentation();

// 执行组合查询：属性匹配 + 角色过滤 + 分页
List<UserRepresentation> users = realmResource.users().search(
        q,
        null, null, null, null,
        Collections.singletonList(role.getId()),
        page * size,
        size);

方法三：直接调用Keycloak REST API（灵活扩展场景） #

如果Java API封装无法满足需求，可直接调用Keycloak的REST接口，GET请求示例：

GET /admin/realms/{你的Realm名}/users?username={用户名}&firstName={名}&lastName={姓}&email={邮箱}&roles={角色名}&first={page*size}&max={size}

Java中可以用RestTemplate或OkHttp实现调用，不过优先推荐使用Admin Client API减少重复代码。

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