Keycloak Spring Boot非管理员跨Realm获取外域用户列表实现方法

默认无权限，手动完成最小授权后即可实现。
你对角色权限范围的判断大方向正确，先纠正一个细节：Keycloak默认的用户列表查看角色是view-users，属于每个Realm下realm-management客户端的内置客户端角色，默认仅对角色所属Realm生效——也就是说internal域下的用户哪怕绑定了本域realm-management的view-users角色，默认也只能查询internal域的用户列表，无法访问external域的任何资源，Keycloak默认Realm之间是完全逻辑隔离的。

要实现跨Realm访问，不需要给用户开全局管理员权限，仅需在external域完成以下授权配置：

• 登录Keycloak管理控制台，切换到external域
• 进入「客户端」页面，找到realm-management客户端，切换到「角色」标签，定位到内置的view-users角色
• 打开该角色的「用户映射」页，选择身份来源为internal域，选中需要授权的非管理员用户完成绑定即可
• 如果两个Realm已经配置了跨Realm身份联邦，也可以直接给internal域的对应用户组做角色映射，无需逐个用户授权

Keycloak的鉴权逻辑本身不校验用户归属的Realm，仅校验请求携带的Token是否拥有当前访问Realm对应资源的权限，只要Token中带了external域realm-management的view-users角色，不管用户实际属于哪个Realm，都可以调用对应用户查询接口。

前提是已经完成上述跨Realm角色授权，项目中直接使用官方Keycloak Admin Client实现即可，无需手动封装HTTP请求，步骤如下：

1. 引入和Keycloak服务端版本完全一致的Admin Client依赖，版本不一致大概率会出现接口序列化兼容问题：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>替换为实际部署的Keycloak版本号</version>
</dependency>

2. 核心业务代码，直接透传internal域登录用户的Access Token初始化客户端，禁止在代码中硬编码管理员账号密码：

import org.keycloak.admin.client.Keycloak;
import org.keycloak.admin.client.KeycloakBuilder;
import org.keycloak.representations.idm.UserRepresentation;
import java.util.List;

public List<UserRepresentation> loadExternalRealmUsers(String currentUserAccessToken) {
    // 初始化指向external域的客户端实例，用try-with-resource自动关闭连接
    try (Keycloak keycloakClient = KeycloakBuilder.builder()
            .serverUrl("Keycloak服务根地址，例：http://127.0.0.1:8080")
            .realm("external") // 指定目标访问的Realm
            .authorization(currentUserAccessToken) // 传入当前登录非管理员用户的有效Token
            .build()) {
        
        // 调用用户查询接口，可按需传入分页、搜索筛选条件
        return keycloakClient.realm("external")
                .users()
                .list(0, 100); // 示例：查询前100条用户数据
    }
}

3. 常见避坑点：

• 如果调用时报403错误，先检查Token的aud（受众）字段是否包含external域的realm-management客户端，未包含的话需要在internal域的客户端配置中添加对应受众映射，确保签发的Token携带目标服务的受众声明
• 授权时仅给目标用户绑定view-users角色即可，不要追加多余角色，避免权限溢出
• 如果项目接入了Spring Security OAuth2资源服务器配置，可以直接从SecurityContext中取出当前用户的Access Token，无需前端额外传参

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