Admin REST API

Keycloak 提供了一个完整的 REST API，用于以编程方式管理服务器的各个方面。Admin REST API 支持与 Admin Console 中相同的操作。

API 基础 URL

https://<keycloak-host>/admin/realms/<realm>

所有 Admin REST API 端点都相对于此基础 URL。

身份验证

所有 API 请求都需要具有管理员权限的有效 access token。获取该 token 有两种方法。

方法 1：用户名和密码

使用管理员用户的凭据进行身份验证：

ACCESS_TOKEN=$(curl -s -X POST \
  "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=<admin-user>" \
  -d "password=<admin-password>" \
  -d "grant_type=password" | jq -r '.access_token')

方法 2：Service Account

使用带有 service account 角色的 confidential client：

在 master Realm（或目标 Realm）中创建一个 confidential client。
启用 Service accounts roles。
将适当的 admin 角色分配给该 service account（例如，realm-admin）。

使用 client_credentials grant 获取 token：

ACCESS_TOKEN=$(curl -s -X POST \
  "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -d "client_id=<service-client-id>" \
  -d "client_secret=<service-client-secret>" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

建议在自动化和 CI/CD 流水线中使用 service account。

使用 Token

在 Authorization header 中包含 access token：

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users"

常见 API 操作

Realms

# List all realms
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms" | jq '.[].realm'

# Get a specific realm
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>"

# Create a realm
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://<keycloak-host>/admin/realms" \
  -d '{"realm": "new-realm", "enabled": true}'

Users

# List users (with pagination)
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users?first=0&max=20"

# Search users
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users?search=john"

# Get user by ID
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users/<user-id>"

# Delete a user
curl -s -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users/<user-id>"

# Get user role mappings
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users/<user-id>/role-mappings"

Clients

# List clients
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients"

# Get client by ID
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients/<client-uuid>"

# Get client secret
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients/<client-uuid>/client-secret"

# Regenerate client secret
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients/<client-uuid>/client-secret"

Roles

# List realm roles
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/roles"

# Create a realm role
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://<keycloak-host>/admin/realms/<realm>/roles" \
  -d '{"name": "my-role", "description": "My custom role"}'

# Assign realm role to user
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://<keycloak-host>/admin/realms/<realm>/users/<user-id>/role-mappings/realm" \
  -d '[{"id": "<role-id>", "name": "my-role"}]'

Groups

# List groups
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/groups"

# Add user to group
curl -s -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users/<user-id>/groups/<group-id>"

Identity Providers

# List identity providers
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/identity-provider/instances"

Events

# Get login events
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/events?first=0&max=100"

# Get admin events
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/admin-events?first=0&max=100"

分页

大多数列表端点都支持通过 first（偏移量）和 max（每页大小）查询参数进行分页：

# Get users 20-39
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users?first=20&max=20"

错误处理

API 返回标准 HTTP 状态码：

Code	含义
`200`	成功
`201`	资源已创建
`204`	成功（无内容）
`400`	错误请求（参数无效）
`401`	未授权（缺少或令牌已过期）
`403`	禁止访问（权限不足）
`404`	未找到资源
`409`	冲突（例如，用户名重复）

完整 API 参考

如需完整的 API 规范，请参阅上游 Keycloak REST API 文档：

Official REST API Reference: https://www.keycloak.org/docs-api/latest/rest-api/index.html

没有运行时 OpenAPI 端点

Keycloak 不会公开运行时 OpenAPI/Swagger 端点。官方 OpenAPI 定义作为静态文件发布在 Keycloak 文档站点上，并按每个发行版进行版本化（例如，/docs-api/26.1.4/rest-api/index.html）。

#Admin REST API

#目录

#API 基础 URL

#身份验证

#方法 1：用户名和密码

#方法 2：Service Account

#使用 Token

#常见 API 操作

#Realms

#Users

#Clients

#Roles

#Groups

#Identity Providers

#Events

#分页

#错误处理

#完整 API 参考