如何在Keycloak 21.1.1中使用服务访问令牌创建用户？

核心问题定位 #

你遇到的403错误，90%以上是服务账户的权限不足，其次可能是API路径使用错误，先从这两点入手解决。

第一步：配置客户端服务账户权限 #

1. 登录Keycloak控制台，找到目标客户端，切换到「Service Accounts Roles」标签页
2. 在「Client Roles」下拉框选择realm-management
3. 为服务账户添加以下必要角色：
   • manage-users：核心权限，用于创建、修改用户
   • view-users：可选，用于后续查询用户验证结果
   • create-users：部分版本需单独添加该权限
4. 保存配置

第二步：修正API端点路径 #

Keycloak 21.x版本的Admin API已移除/auth前缀，正确的创建用户端点为：

http://<keycloak-host>:<port>/admin/realms/{realm}/users

旧路径/auth/admin/...会导致请求失败，这也是常见的403/404诱因。

第三步：代码示例（Python requests） #

import requests
import json

# 基础配置
KEYCLOAK_HOST = "localhost"
KEYCLOAK_PORT = "8080"
REALM_NAME = "your-realm"
CLIENT_ID = "your-service-client"
CLIENT_SECRET = "your-client-secret"

# 1. 获取服务访问令牌
token_url = f"http://{KEYCLOAK_HOST}:{KEYCLOAK_PORT}/realms/{REALM_NAME}/protocol/openid-connect/token"
token_payload = {
    "grant_type": "client_credentials",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET
}
token_res = requests.post(token_url, data=token_payload)
access_token = token_res.json()["access_token"]

# 2. 发起创建用户请求
create_user_url = f"http://{KEYCLOAK_HOST}:{KEYCLOAK_PORT}/admin/realms/{REALM_NAME}/users"
user_data = {
    "username": "new-test-user",
    "email": "test@example.com",
    "enabled": True,
    "emailVerified": True,
    "credentials": [
        {
            "type": "password",
            "value": "SecurePass123!",
            "temporary": False
        }
    ]
}

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

create_res = requests.post(create_user_url, headers=headers, data=json.dumps(user_data))
print(f"响应状态码: {create_res.status_code}")
print(f"响应内容: {create_res.json()}")

额外排查建议 #

• 解析令牌验证权限：用本地JWT解码工具解析access_token，确认realm_access.roles中包含manage-users等配置的角色
• 检查Admin API访问限制：进入控制台「Realm Settings」→「Security Defenses」，确认「Admin API Access」未限制客户端IP
• 确认客户端类型：目标客户端必须是「Confidential」类型，服务账户功能仅对该类型客户端开放

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