此 API 用于创建或更新 Easysearch 内部用户。
API #
PUT /_security/user/{name}
API 的作用 #
创建新的内部用户或更新已存在的用户配置。此 API 是 Easysearch 安全模块的一部分，用于管理系统用户账户。
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
name | string | 必需 | 用户名 |
查询字符串参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
refresh | string | 可选 | wait_downgrade | 刷新策略wait_for：等待刷新完成false：不刷新 |
请求体参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
password | string | 条件* | - | 用户的明文密码 创建用户时必需（如果未提供 hash） |
hash | string | 条件* | - | 预哈希的密码值 与 password 二选一 |
roles | array | 可选 | [] | 分配给用户的内部角色列表 |
external_roles | array | 可选 | [] | 分配给用户的外部角色列表 如 LDAP 角色 |
attributes | object | 可选 | {} | 用户自定义的键值对属性 |
description | string | 可选 | - | 用户描述信息 |
reserved | boolean | 可选 | false | 是否为保留用户 仅超级管理员可设置 |
hidden | boolean | 可选 | false | 是否为隐藏用户 隐藏用户在列表查询中不显示 |
注意：password 和 hash 必须提供其中一个。
请求示例 #
创建基本用户 #
PUT /_security/user/alice
{
"password": "alice123",
"roles": ["viewer"]
}
创建带完整信息的用户 #
PUT /_security/user/admin
{
"password": "admin123",
"roles": ["security_admin", "system_monitor"],
"external_roles": ["ldap_admins"],
"attributes": {
"department": "IT",
"location": "Beijing"
},
"description": "System administrator"
}
更新现有用户 #
PUT /_security/user/alice
{
"password": "new_password",
"roles": ["editor", "viewer"]
}
创建隐藏用户 #
PUT /_security/user/system_user
{
"password": "secure_password",
"roles": ["system_role"],
"hidden": true,
"reserved": true
}
响应示例 #
成功响应 - 创建用户 #
{
"status": "CREATED",
"message": "User alice created"
}
成功响应 - 更新用户 #
{
"status": "OK",
"message": "User alice updated"
}
错误响应 - 密码不符合要求 #
{
"error": {
"root_cause": [
{
"type": "validation_exception",
"reason": "Password does not meet complexity requirements"
}
],
"type": "validation_exception",
"reason": "Password does not meet complexity requirements"
},
"status": 400
}
密码验证规则 #
密码需要满足以下规则：
- 非空检查：密码不能为空字符串
- 复杂度要求：如果配置了密码正则表达式，密码必须匹配
- 不重复用户名：密码不能与用户名相同（不区分大小写）
用户属性 #
用户属性（attributes）可以存储任意键值对信息，例如：
{
"password": "user123",
"roles": ["viewer"],
"attributes": {
"department": "Engineering",
"team": "Backend",
"location": "Beijing",
"employee_id": "12345"
}
}
权限要求 #
- 创建用户：需要
manage_security权限 - 更新用户：需要
manage_security权限或修改自己的密码 - 保留用户：只有超级管理员可以创建/修改保留用户
注意事项 #
- 此 API 使用 PUT 方法
- 明文密码会在存储时自动转换为哈希值
- 指定的角色必须存在，否则会返回错误
- 保留用户不能被普通用户修改
- 隐藏用户在列表查询中默认不显示
安全建议 #
- 强密码：使用强密码策略
- 最小权限：只授予用户必需的角色
- 定期更换：定期更换用户密码
- 审计日志：记录用户变更操作
- 禁用不使用：删除或禁用不再使用的账户
