获取 Easysearch 中的安全角色配置信息。
API 格式 #
GET /_security/role
GET /_security/role/{name}
API 作用 #
该 API 用于检索安全角色的配置信息：
- GET /_security/role：获取所有角色
- GET /_security/role/{name}：获取指定角色
API 参数 #
路径参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
{name} | String | 否 | - | 要查询的角色名称。如未指定，返回所有角色 |
查询参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
name | String | 否 | 所有角色 | 逗号分隔的角色名称列表 |
请求示例 #
获取所有角色 #
GET /_security/role
获取指定角色 #
GET /_security/role/admin
获取多个角色 #
GET /_security/role?name=admin,user,developer
响应示例 #
获取所有角色响应 #
{
"admin": {
"cluster": ["*"],
"indices": [
{
"names": ["*"],
"privileges": ["*"],
"query": null,
"field_security": [],
"field_mask": []
}
],
"description": "管理员角色",
"reserved": false,
"hidden": false,
"static": false
},
"data_analyst": {
"cluster": ["cluster:monitor/health"],
"indices": [
{
"names": ["logs-*", "metrics-*"],
"privileges": ["READ_UT"],
"query": null,
"field_security": ["timestamp", "message", "level"],
"field_mask": []
}
],
"description": "数据分析师角色",
"reserved": false,
"hidden": false,
"static": false
},
"kibana_user": {
"cluster": ["cluster:monitor/health"],
"indices": [
{
"names": [".kibana*"],
"privileges": ["ALL"]
}
],
"description": "Kibana 用户角色",
"reserved": false,
"hidden": false,
"static": false
}
}
获取指定角色响应 #
{
"admin": {
"cluster": ["cluster:monitor*", "cluster:all"],
"indices": [
{
"names": ["sf", "pub"],
"privileges": ["SECURITY_CRUD"],
"query": null,
"field_security": [],
"field_mask": []
}
],
"description": "管理员角色",
"reserved": false,
"hidden": false,
"static": false
}
}
错误响应 - 权限不足 #
403 Forbidden
{
"error": "Authentication required"
}
错误响应 - 角色不存在（非超级管理员） #
404 Not Found
{
"status": 404,
"error": "role 'hidden_role' not found"
}
响应字段说明 #
顶层字段 #
| 字段 | 类型 | 描述 |
|---|---|---|
{role_name} | Object | 以角色名称为键的角色配置对象 |
角色配置字段 #
| 字段 | 类型 | 描述 |
|---|---|---|
cluster | String[] | 集群级别的权限列表 |
indices | Object[] | 索引级别的权限配置数组 |
description | String | 角色的描述信息 |
reserved | Boolean | 是否为保留角色（系统角色） |
hidden | Boolean | 是否为隐藏角色 |
static | Boolean | 是否为静态角色（不可修改） |
indices 数组元素字段 #
| 字段 | 类型 | 描述 |
|---|---|---|
names | String[] | 索引模式列表 |
privileges | String[] | 权限列表 |
query | String/null | 文档级安全查询 |
field_security | String[] | 可访问的字段列表 |
field_mask | String[] | 需要隐藏的字段列表 |
访问控制行为 #
| 用户类型 | 可见角色 |
|---|---|
| 超级管理员 | 所有角色，包括隐藏角色 |
| 普通用户 | 仅非隐藏角色 |
| 未认证用户 | 返回 403 Forbidden |
常见集群权限 #
| 权限 | 描述 |
|---|---|
"*" | 所有权限 |
"cluster:monitor*" | 所有集群监控权限 |
"cluster:monitor/health" | 监控集群健康状态 |
"cluster:monitor/nodes/info" | 获取节点信息 |
"cluster:all" | 所有集群权限 |
常见索引权限 #
| 权限 | 描述 |
|---|---|
"*" 或 "ALL" | 所有索引权限 |
"READ_UT" | 读取、查看和索引映射 |
"CRUD_UT" | 创建、读取、更新、删除 |
"SECURITY_CRUD" | 安全相关的 CRUD 操作 |
"indices:data/read/search" | 搜索权限 |
注意事项 #
- 需要认证：该 API 需要通过证书进行身份验证
- 隐藏角色：只有超级管理员可以查看隐藏角色
- 安全索引：使用该 API 前必须初始化
.security索引 - 空结果：如果安全配置未初始化，会返回 500 错误
相关操作 #
- PUT /_security/role/{name}：创建或更新角色
- DELETE /_security/role/{name}：删除角色
- PATCH /_security/role/{name}：部分更新角色
- GET /_security/user：查询用户信息
实现细节 #
- 处理器：
RolesApiAction.java - 继承：继承自
PatchableResourceApiAction和AbstractApiAction - 实际处理：在
AbstractApiAction.handleGet方法中（第 237-266 行） - 配置加载：从安全索引加载角色配置
- 过滤逻辑：为非超级管理员用户过滤隐藏角色
