使用Service Access Token在Keycloak 21.1.1创建用户的方法求助

核心问题排查（403错误的常见原因） #

你的403错误大概率是服务账户权限不足或API路径错误导致的，先按以下步骤确认配置：

步骤1：配置服务客户端权限 #

1. 登录Keycloak控制台，进入目标Realm → 「客户端」→ 选中你的服务客户端
2. 开启Service Account Enabled（必须勾选，否则无法获取服务令牌）
3. 切换到「Service Account Roles」标签页：
   • 在「Client Roles」下拉框中选择realm-management
   • 添加以下角色（创建用户必备）：
     • manage-users（包含创建、修改用户的权限）
     • view-users（可选，用于后续查询用户）

步骤2：获取有效的Service Access Token #

确保请求令牌的端点和参数正确：

• 请求方法：POST
• 端点（WildFly版本Keycloak 21.1.1）：/auth/realms/{realm}/protocol/openid-connect/token
  如果是Quarkus版本部署，去掉/auth前缀：/realms/{realm}/protocol/openid-connect/token
• 请求参数（form-data格式）：

  grant_type=client_credentials
  client_id=你的服务客户端ID
  client_secret=你的服务客户端密钥
  

• 解码返回的access_token（用jwt.io），确认realm_access.roles中包含manage-users

步骤3：调用创建用户的Admin API #

正确的API端点

• WildFly版本：/auth/admin/realms/{realm}/users
• Quarkus版本：/admin/realms/{realm}/users（注意无/auth前缀）

请求示例

• 请求方法：POST
• 请求头：

  Authorization: Bearer {你的Service Access Token}
  Content-Type: application/json
  

• 请求体（JSON格式）：

  {
    "username": "new-test-user",
    "email": "test@example.com",
    "enabled": true,
    "credentials": [
      {
        "type": "password",
        "value": "StrongPass123!",
        "temporary": false
      }
    ],
    "firstName": "Test",
    "lastName": "User"
  }
  

完整代码示例（Python） #

import requests

# 替换为你的Keycloak配置
KEYCLOAK_SERVER = "http://your-keycloak:8080"
REALM = "your-target-realm"
CLIENT_ID = "your-service-client-id"
CLIENT_SECRET = "your-client-secret"

# 1. 获取服务令牌
token_endpoint = f"{KEYCLOAK_SERVER}/auth/realms/{REALM}/protocol/openid-connect/token"
token_payload = {
    "grant_type": "client_credentials",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET
}
token_res = requests.post(token_endpoint, data=token_payload)
token_res.raise_for_status()
access_token = token_res.json()["access_token"]

# 2. 创建用户
create_user_endpoint = f"{KEYCLOAK_SERVER}/auth/admin/realms/{REALM}/users"
user_data = {
    "username": "new-user-001",
    "email": "new-user@example.com",
    "enabled": True,
    "credentials": [
        {
            "type": "password",
            "value": "SecurePass456!",
            "temporary": False
        }
    ],
    "firstName": "New",
    "lastName": "User"
}
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}
create_res = requests.post(create_user_endpoint, json=user_data, headers=headers)
create_res.raise_for_status()
print(f"用户创建成功，状态码：{create_res.status_code}")

额外排查建议 #

1. 若仍返回403，检查令牌的realm_access.roles是否包含manage-users
2. 确认Keycloak部署版本：Quarkus版本的API路径无/auth前缀，容易混淆
3. 检查Realm的「安全防御」设置，是否限制了Admin API的访问IP
4. 确保服务客户端没有被设置为「仅机密客户端」之外的类型（需为机密客户端）

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