通过Bash调用Keycloak REST API创建资源时遇401未授权错误

核心原因 #

你遇到的401问题本质是API请求的权限上下文不匹配：初始获取的Token是针对master realm的管理员权限，但操作新realm资源时需要确保请求路径正确，且使用的Token具备跨realm管理权限——而master realm的默认管理员本身就拥有所有realm的管理权限，不需要在新realm创建独立管理员，不存在所谓的"矛盾"。

具体排查步骤 #

1. 校验API请求路径 #

操作新realm的资源时，API路径必须明确指定目标realm，而非使用master的路径：

• 创建realm的路径：/admin/realms（全局realm管理接口）
• 创建新realm下的client路径：/admin/realms/{你的新realm名称}/clients
• 创建新realm下的用户路径：/admin/realms/{你的新realm名称}/users

如果你的脚本里创建client时仍使用/admin/realms/master/clients这类路径，必然会返回401（因为你要在master里创建client，但可能token权限没问题，但你实际要操作的是新realm）。

2. 验证master管理员Token的权限 #

解码你的Token（可以用本地工具或jwt.io离线解析），检查以下字段：

• iss：值应为http://你的keycloak地址/auth/realms/master，确认是master realm颁发的Token
• realm_access.roles：必须包含realm-admin角色，这个角色赋予了管理员管理所有realm的权限

如果没有realm-admin角色，说明你获取Token时的参数有误：

• 获取Token必须使用master realm的admin-cli客户端，grant_type为password，用户名是master realm的管理员账号（默认是admin），密码是安装Keycloak时设置的管理员密码。

3. 检查请求头细节 #

确保创建client/user的请求携带正确的头信息：

• 必须包含Authorization: Bearer {你的master Token}
• 必须包含Content-Type: application/json（Keycloak API要求POST/PUT请求必须指定这个头）

4. 查看Keycloak日志定位具体原因 #

通过Kubernetes命令查看Keycloak容器日志：

kubectl logs -f <你的keycloak pod名称>

日志里会给出401的具体原因，比如：

• Token已过期
• Token的受众（aud）不匹配
• 请求路径中的realm名称拼写错误（Keycloak的realm名称大小写敏感）

修正后的脚本示例 #

# 1. 获取master realm的管理员Token
export KEYCLOAK_URL="http://keycloak-local:8080/auth"
export MASTER_ADMIN_USER="admin"
export MASTER_ADMIN_PWD="your-admin-password"
export NEW_REALM="my-dev-realm"

export TOKEN=$(curl -s -X POST "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=${MASTER_ADMIN_USER}" \
  -d "password=${MASTER_ADMIN_PWD}" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" | jq -r '.access_token')

# 2. 创建新realm
curl -s -X POST "${KEYCLOAK_URL}/admin/realms" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "'"${NEW_REALM}"'",
    "enabled": true,
    "displayName": "Dev Realm"
  }'

# 3. 在新realm创建第一个client
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/clients" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "backend-service",
    "enabled": true,
    "publicClient": false,
    "secret": "backend-secret-123"
  }'

# 4. 在新realm创建用户
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/users" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "dev-user-1",
    "enabled": true,
    "credentials": [{"type": "password", "value": "user-pwd-123", "temporary": false}]
  }'

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