Quarkus集成Keycloak Admin：能否创建仅读指定Realm用户的管理员？

可以实现，而且完全不需要依赖Admin Realm的客户端——核心是在目标业务Realm内创建服务账号并配置精准的只读权限，以下是具体步骤和403问题的排查方案：

一、创建目标Realm的服务账号客户端 #

1. 登录Keycloak控制台，直接进入你需要访问用户数据的目标业务Realm（不要进入master/Admin Realm）
2. 创建新客户端：
   • 客户端类型选择「服务账号」
   • 开启「服务账号启用」选项
3. 配置权限：
   • 进入该客户端的「权限」标签页，开启「授权」功能
   • 添加用户相关的只读权限：比如view-users、query-users，这些权限默认是针对当前Realm的，无需额外跨Realm配置
   • 更简便的方式：直接给该服务账号分配realm-management客户端下的view-users角色（这个角色自带当前Realm的用户只读权限）

二、Quarkus应用配置 #

在application.properties中配置Keycloak Admin客户端参数，注意所有配置都指向目标业务Realm：

# Keycloak基础地址（Keycloak 17+请去掉/auth后缀）
quarkus.keycloak.admin-client.server-url=http://your-keycloak-address/auth
# 目标业务Realm名称
quarkus.keycloak.admin-client.realm=your-target-realm
# 刚才创建的服务账号客户端ID
quarkus.keycloak.admin-client.client-id=your-service-client-id
# 客户端密钥
quarkus.keycloak.admin-client.client-secret=your-client-secret

三、403错误常见排查点 #

1. 权限配置不全：
   • 确认服务账号已拿到view-users和query-users权限，不要漏加query-users（仅view-users可能无法执行列表查询）
   • 权限必须是目标Realm内的权限，不要误配成Admin Realm的角色
2. 端点路径错误：
   • Keycloak 17及以上版本的API端点已移除/auth后缀，server-url需改为http://your-keycloak-address/
3. 令牌受众问题：
   • 检查客户端的「范围」标签页，确保已添加realm-management客户端的权限范围，否则令牌无法访问Admin API
4. 服务账号权限生效问题：
   • 配置完成后重启Keycloak客户端会话，或重新生成服务账号令牌，避免缓存导致权限未更新

四、Quarkus代码示例 #

import io.quarkus.keycloak.admin.client.KeycloakAdminClient;
import org.keycloak.representations.idm.UserRepresentation;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;

@ApplicationScoped
public class UserQueryService {

    private final KeycloakAdminClient keycloakAdminClient;

    // 构造注入（或用@RestClient注解）
    public UserQueryService(KeycloakAdminClient keycloakAdminClient) {
        this.keycloakAdminClient = keycloakAdminClient;
    }

    public List<UserRepresentation> getAllUsersInTargetRealm() {
        // 直接调用Admin API查询当前Realm的用户
        return keycloakAdminClient.users().list();
    }
}

这种方案的优势是完全隔离了Admin Realm和业务Realm的权限，服务账号仅能访问指定Realm的用户数据，符合最小权限原则。

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