Keycloak Admin Rest API如何通过多个用户名批量查询用户

适用场景 #

需要一次性查询多个用户名对应的用户信息，等价于SQL中的username IN ('user1','user2','user3')查询逻辑。

方案1：多值username参数（推荐，适配Keycloak 15+版本） #

Keycloak新版本的用户查询接口原生支持传入多个username参数，接口会自动按OR逻辑匹配所有符合条件的用户。

请求示例 #

curl -X GET 'https://<你的Keycloak服务地址>/admin/realms/<你的目标Realm名称>/users?username=user1&username=user2&username=user3' \
-H "Authorization: Bearer <你的管理员权限Access Token>"

注意事项 #

• 接口默认最多返回100条结果，若需要查询的用户名数量超过100，需要额外添加max参数调整返回上限，例如&max=500
• 单次传入的用户名数量不要超过1000，避免URL过长被网关或服务器拦截

方案2：q参数查询（兼容全版本Keycloak） #

如果你的Keycloak版本较低不支持多值username参数，可以使用通用查询参数q实现多用户名匹配，多个查询条件用空格分隔即代表OR逻辑。

请求示例 #

curl -X GET 'https://<你的Keycloak服务地址>/admin/realms/<你的目标Realm名称>/users?q=username:user1 username:user2 username:user3' \
-H "Authorization: Bearer <你的管理员权限Access Token>"

注意事项 #

• 若用户名包含空格、特殊字符，需要先做URL编码再传入q参数，避免查询异常

前置依赖说明 #

调用上述接口前，需要先获取对应Realm的view-users权限的Access Token，可通过admin-cli客户端使用密码授权模式获取，示例如下：

curl -X POST 'https://<你的Keycloak服务地址>/realms/master/protocol/openid-connect/token' \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&client_id=admin-cli&username=<管理员用户名>&password=<管理员密码>"

内容的提问来源于stack exchange，提问作者venkat.s