索引管理外部角色过滤配置

配置项作用 #

plugins.index_management.filter_by_external_roles 配置项用于控制是否根据用户的后端角色过滤索引管理（ISM）资源的访问。

索引管理包括策略（Policies）、转换（Transforms）、汇总（Rollups）等资源。当启用此配置时，用户只能访问其后端角色与资源存储的后端角色有交集的资源。这为多租户环境提供了基于角色的访问控制。

配置项属性 #

配置路径: plugins.index_management.filter_by_external_roles
数据类型: Boolean（布尔值）
默认值: false
是否可选: 是
作用域: NodeScope（节点级别）
动态更新: 是（可以动态更新，无需重启）

配置项详解 #

工作机制 #

外部角色过滤机制

禁用过滤 (false, 默认):
├── 不检查后端角色
├── 任何认证用户可访问所有资源
├── user 字段仍被存储
└── 适用于单租户环境 ✅


启用过滤 (true):
├── 检查请求用户的后端角色
├── 检查资源的后端角色字段
├── 计算交集
├── 有交集 → 允许访问 ✅
├── 无交集 → 拒绝访问 ❌
└── all_access 角色绕过过滤 ✅


资源类型:
├── ISM Policies (索引策略)
├── Transforms (数据转换)
├── Rollups (数据汇总)
└── 其他索引管理资源

访问控制流程 #

访问控制详细流程

1. 用户请求访问 ISM 资源
   GET _ilm/policy/my-policy


2. 获取用户后端角色
   用户: alice
   后端角色: [tenant-a-admin, team-dev]


3. 读取资源后端角色
   资源: my-policy
   存储角色: [tenant-a-admin, tenant-a-user]


4. 计算交集
   用户角色: [tenant-a-admin, team-dev]
   资源角色: [tenant-a-admin, tenant-a-user]
   交集: [tenant-a-admin]
   有交集 → 允许访问 ✅


5. 无交集情况
   用户: bob
   后端角色: [tenant-b-admin]
   资源角色: [tenant-a-admin, tenant-a-user]
   交集: 无
   无交集 → 拒绝访问 ❌


6. all_access 绕过
   用户: admin
   后端角色: [all_access]
   任何资源 → 允许访问 ✅

角色存储 #

资源中的后端角色存储

创建 ISM 策略:
PUT _ilm/policy/tenant-a-policy
{
  "policy": {
    "description": "Tenant A policy",
    "default_state": "hot",
    "states": [...]
  },
  "seq_no": 0,
  "primary_term": 0,
  "roles": ["tenant-a-admin", "tenant-a-user"]
}


访问控制:
├── 启用过滤后
├── 只有包含这些角色的用户可访问
├── 角色必须至少有一个匹配
└── 实现租户隔离


创建转换:
PUT _transform/tenant-a-transform
{
  "source": {...},
  "dest": {...},
  "roles": ["tenant-a-admin"]
}


同理适用于:
├── Rollups
├── 其他 ISM 资源
└── 统一的访问控制

配置建议 #

单租户环境（默认） #

plugins:
  index_management:
    filter_by_external_roles: false  # 默认值

建议: 单租户环境保持默认值 false。

多租户环境 #

plugins:
  index_management:
    filter_by_external_roles: true  # 启用过滤

建议: 多租户环境启用，实现资源隔离。

开发环境 #

plugins:
  index_management:
    filter_by_external_roles: false  # 简化开发

建议: 开发环境禁用，便于调试。

生产环境（多租户） #

plugins:
  index_management:
    filter_by_external_roles: true  # 启用安全控制

建议: 生产多租户环境必须启用。

代码示例 #

easysearch.yml 基础配置 #

plugins:
  index_management:
    filter_by_external_roles: true

完整多租户配置 #

# 启用安全
xpack:
  security:
    enabled: true

# 启用 ISM 角色过滤
plugins:
  index_management:
    filter_by_external_roles: true
  snapshot_management:
    filter_by_backend_roles: true

动态更新配置 #

// 运行时更新（无需重启）
PUT /_cluster/settings
{
  "transient": {
    "plugins.index_management.filter_by_external_roles": true
  }
}

创建带角色控制的策略 #

PUT _ilm/policy/tenant-a-logs-policy
{
  "policy": {
    "description": "Tenant A logs retention policy",
    "default_state": "hot",
    "states": [
      {
        "name": "hot",
        "actions": [{"rollover": {...}}]
      },
      {
        "name": "warm",
        "actions": [{"replica_count": {...}}]
      }
    ],
    "isms": [
      {"pattern": "tenant-a-logs-*", "priority": 100}
    ]
  },
  "roles": ["tenant-a-admin", "tenant-a-ops"]
}

配置项	作用	默认值
`plugins.index_management.filter_by_external_roles`	ISM 角色过滤	false
`plugins.snapshot_management.filter_by_backend_roles`	快照管理角色过滤	false
`xpack.security.enabled`	安全功能开关	true

多租户场景 #

多租户场景配置

场景 1: SaaS 多租户

租户 A:
├── 用户: alice
├── 后端角色: [tenant-a-admin]
└── 可访问: tenant-a-* 资源


租户 B:
├── 用户: bob
├── 后端角色: [tenant-b-admin]
└── 可访问: tenant-b-* 资源


配置:
plugins:
  index_management:
    filter_by_external_roles: true


效果:
├── alice 不能访问 tenant-b 资源 ✅
├── bob 不能访问 tenant-a 资源 ✅
└── 租户完全隔离


场景 2: 部门隔离

部门 A:
├── 用户: team-a-lead
├── 后端角色: [dept-a-admin]
└── 资源: dept-a-*


部门 B:
├── 用户: team-b-lead
├── 后端角色: [dept-b-admin]
└── 资源: dept-b-*


效果:
├── 部门间完全隔离
├── 各自管理自己的策略
└── 提高安全性

使用场景 #

安全考虑 #

安全配置建议

1. 启用外部认证
   xpack:
     security:
       authc:
         realms:
           ldap:
             my-ldap: {...}


2. 配置角色映射
   security:
     authz:
       roles:
         tenant-a-admin:
           indices: [...]
           roles: ["tenant-a-admin"]


3. 启用 ISM 过滤
   plugins:
     index_management:
       filter_by_external_roles: true


4. 创建带角色的资源
   PUT _ilm/policy/...
   {"roles": ["tenant-a-admin"]}


5. 验证隔离
   ├── 使用不同用户测试
   ├── 验证访问限制
   └── 审计日志

注意事项 #

默认值: 默认值为 false，不启用过滤。
动态更新: 支持动态更新，无需重启。
后端角色: 依赖于外部认证系统的角色。
all_access: 拥有 all_access 角色的用户绕过过滤。
现有资源: 启用后，没有角色的现有资源可能无法访问。
资源创建: 创建资源时应指定 roles 字段。
性能影响: 启用后会有轻微的性能开销。
测试验证: 启用前应充分测试。
审计日志: 配合审计日志监控访问。
快照管理: 同时考虑 snapshot_management 的类似配置。

故障排查 #

常见问题排查

问题 1: 启用后无法访问资源

现象:
403 Forbidden when accessing ISM policies


原因:
├── 用户的角色与资源角色无交集
├── 资源未设置 roles 字段
└── 或 roles 配置错误


解决:
├── 检查用户的后端角色
├── 检查资源的 roles 字段
├── 确保有角色交集
└── 或临时禁用过滤


问题 2: 创建资源时未指定角色

后果:
├── 资源创建成功
├── 但启用过滤后可能无法访问
└── 需要更新资源添加角色


解决:
├── 创建时指定 roles
├── 或更新现有资源
├── 测试访问
└── 文档化角色分配


问题 3: 角色配置错误

检查:
GET /_ilm/policy/my-policy

查看 roles 字段:
{
  "roles": ["tenant-a-admin"]
}


验证用户:
GET /_security/user/alice

查看后端角色:
{
  "username": "alice",
  "backend_roles": ["tenant-a-admin", ...]
}


确保有交集

最佳实践 #

角色过滤最佳实践

1. 多租户部署
   plugins:
     index_management:
       filter_by_external_roles: true

   ├── 启用过滤
   ├── 按租户定义角色
   ├── 资源创建时指定角色
   └── 测试隔离 ✅


2. 资源命名规范
   ├── 租户 A: tenant-a-*
   ├── 租户 B: tenant-b-*
   ├── 配合角色过滤
   └── 双重隔离


3. 角色设计
   ├── 每个租户: tenant-*-admin
   ├── 跨租户: tenant-*-readonly
   ├── 管理员: all_access
   └── 清晰的权限模型


4. 创建资源规范
   PUT _ilm/policy/...
   {
     "policy": {...},
     "roles": ["tenant-a-admin"]
   }

   ├── 始终指定 roles
   ├── 文档化角色分配
   └── 审计变更


5. 测试流程
   ├── 单元测试: 验证权限
   ├── 集成测试: 多租户场景
   ├── 渗透测试: 尝试跨租户
   └── 定期审计

与快照管理的配合 #

统一的访问控制配置

同时启用两个过滤:
plugins:
  index_management:
    filter_by_external_roles: true
  snapshot_management:
    filter_by_backend_roles: true


效果:
├── ISM 策略: 角色过滤
├── 快照仓库: 角色过滤
├── 统一的安全模型
└── 一致的用户体验


最佳实践:
├── 两个都启用
├── 使用相同的角色体系
├── 统一管理
└── 简化运维

标签

Plugin 索引管理角色过滤访问控制