跳转到内容

Keycloak Admin REST API 调用

Keycloak 提供完整的 Admin REST API,几乎覆盖管理控制台的全部能力——Realm、Client、User、Role、Group、认证流、事件等均可通过 HTTP 调用管理。本节讲解认证方式、核心端点、典型 CRUD 实战与 SDK 选型,让你能用脚本/服务把身份管理自动化。

Keycloak 17(Quarkus)起默认上下文路径为 /,API 前缀为 /admin/realms;旧版本(WildFly)前缀为 /auth/admin/realms。下文以 Quarkus 新路径为准,旧版自行补 /auth。

调用 Admin API 需要一个拥有管理权限的 access_token,通过 OAuth 2.0 Password Grant 或 Client Credentials Grant 获取。

方式一:Password Grant(admin-cli,适合脚本)

Section titled “方式一:Password Grant(admin-cli,适合脚本)”
终端窗口
TOKEN=$(curl -s -X POST \
"http://localhost:8080/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=admin-cli" \
-d "username=admin" \
-d "password=${ADMIN_PWD}" \
| jq -r .access_token)

方式二:Client Credentials Grant(适合服务对接)

Section titled “方式二:Client Credentials Grant(适合服务对接)”

先在 master 或目标 Realm 创建一个 confidential Client,赋予 realm-management 中相应角色(如 manage-users、view-realm、manage-clients):

终端窗口
TOKEN=$(curl -s -X POST \
"http://localhost:8080/realms/master/protocol/openid-connect/token" \
-d "grant_type=client_credentials" \
-d "client_id=admin-bot" \
-d "client_secret=${SECRET}" \
| jq -r .access_token)

生产推荐 Client Credentials:用专用服务账号 + 最小角色,而非暴露 admin 用户密码。access_token 默认 5 分钟,请缓存并在过期前刷新。

调用示例:

终端窗口
curl -s "http://localhost:8080/admin/realms/master/users" \
-H "Authorization: Bearer ${TOKEN}"
资源 方法 路径 说明
Realm GET/POST /admin/realms 列出 / 创建 Realm
Realm GET/PUT/DELETE /admin/realms/{realm} 查 / 改 / 删 单个 Realm
Client GET/POST /admin/realms/{realm}/clients 列出 / 创建 Client
Client GET /admin/realms/{realm}/clients/{id}/installation 获取接入配置
User GET/POST /admin/realms/{realm}/users 列出(支持过滤)/ 创建用户
User PUT/DELETE /admin/realms/{realm}/users/{id} 改 / 删 用户
User PUT /admin/realms/{realm}/users/{id}/reset-password 重置密码
Role GET/POST /admin/realms/{realm}/roles Realm 级角色
Role mapping POST /admin/realms/{realm}/users/{id}/role-mappings/realm 给用户授角色
Group GET/POST /admin/realms/{realm}/groups 用户组管理
Events GET /admin/realms/{realm}/events 查询事件审计
Attack DELETE /admin/realms/{realm}/attack-detection/brute-force/users/{id} 清除暴力破解锁定

完整文档见 http://localhost:8080/admin/realms/master/(OpenAPI)或官方 Admin REST API。

详细的 curl 全流程(获取 token → 列出 → 创建 → 解析 Location → 删除)见 用户增删改查端到端。这里补充更贴近生产的片段。

终端窗口
# 1. 创建用户
USER_LOCATION=$(curl -s -i -X POST \
"http://localhost:8080/admin/realms/myrealm/users" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"email": "[email protected]",
"enabled": true,
"emailVerified": true,
"credentials": [
{ "type": "password", "value": "P@ssw0rd!", "temporary": false }
]
}' | grep -i '^location:' | awk '{print $2}' | tr -d '\r')
USER_ID=$(basename "${USER_LOCATION}")
# 2. 查询角色 ID
ROLE_ID=$(curl -s "http://localhost:8080/admin/realms/myrealm/roles/app-admin" \
-H "Authorization: Bearer ${TOKEN}" | jq -r .id)
# 3. 把角色授予用户
curl -s -X POST \
"http://localhost:8080/admin/realms/myrealm/users/${USER_ID}/role-mappings/realm" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d "[{\"id\":\"${ROLE_ID}\",\"name\":\"app-admin\"}]"
终端窗口
# 分页 + 用户名模糊搜索
curl -s "http://localhost:8080/admin/realms/myrealm/users?first=0&max=20&search=ali" \
-H "Authorization: Bearer ${TOKEN}" | jq
# 统计总数
curl -s "http://localhost:8080/admin/realms/myrealm/users/count" \
-H "Authorization: Bearer ${TOKEN}"
终端窗口
# 管理员重置密码
curl -s -X PUT \
"http://localhost:8080/admin/realms/myrealm/users/${USER_ID}/reset-password" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"type":"password","value":"NewP@ss1!","temporary":true}'
# 触发「下次登录必须改密」邮件
curl -s -X PUT \
"http://localhost:8080/admin/realms/myrealm/users/${USER_ID}/execute-actions-email" \
-H "Authorization: Bearer ${TOKEN}" \
-d "actions=UPDATE_PASSWORD"
语言 推荐库 说明
Java keycloak-admin-client(官方,JAX-RS) 与 Keycloak 同源,直接跟随官方 API 变更
Python python-keycloak 社区维护,覆盖常用 Admin/Token 操作
Go github.com/Nerzal/gocloak 社区维护,API 完整
Node.js keycloak-admin(npm) 适合 BFF / 自动化脚本
通用 curl + jq 运维 / CI 脚本
Keycloak kc = KeycloakBuilder.builder()
.serverUrl("http://localhost:8080")
.realm("master")
.clientId("admin-cli")
.username("admin")
.password(ADMIN_PWD)
.build();
UserRepresentation user = new UserRepresentation();
user.setUsername("alice");
user.setEmail("[email protected]");
user.setEnabled(true);
kc.realm("myrealm").users().create(user);
  • 最小权限:为自动化客户端单独建 Client,授予 realm-management 中需要的角色,避免使用 admin 账号。
  • 跨 Realm 管理:管理 master Realm 的 token 可操作任意 Realm;也可在每个 Realm 内建 realm-admin 角色组实现委托管理。
  • 幂等创建:用户名/邮箱唯一约束,创建前先 ?username=xxx 查询,避免 409。
  • 批量操作:Admin API 无原生批量端点,循环调用即可。大批量导入建议编写一次性脚本走 Admin REST API;kc.sh import 接收的是整份 Realm JSON(含 users 段),不能用来导入独立的 users.json。
  • 审计:所有 Admin API 调用默认产生 admin_event,可在 Realm → Events 中开启保存,便于追溯谁在什么时间改了什么。
  • HTTPS:生产必须通过反代终结 TLS,禁止明文传输 token。

Admin REST API 是把 Keycloak 纳入自动化运维和上游用户中心的关键通道。掌握「服务账号 + Client Credentials + 最小角色」的鉴权模式、核心端点与对应 SDK,即可替代绝大多数控制台手工操作。下一节进入安全防护专题。