本地配置（YAML） #

config/security/ 目录下包含 Easysearch 安全模块的本地 YAML 配置文件。这些文件在 bin/initialize.sh 初始化时自动加载到安全索引中，也可以手动编辑后重新加载。

通过本地 YAML 配置文件可以管理默认的内置用户或隐藏的保留资源，例如 admin 管理员用户。除内置资源外，通过 INFINI Console 或 REST API 来创建其他用户、角色、映射和权限组通常更方便。

配置文件概览 #

文件	用途	编辑方式
`user.yml`	内置用户定义	手动编辑或 API
`role.yml`	角色定义	手动编辑或 API
`role_mapping.yml`	角色映射	手动编辑或 API
`privilege.yml`	权限组（Action Group）	手动编辑或 API
`config.yml`	认证后端配置	需重新加载生效
`nodes_dn.yml`	节点 DN 白名单	手动编辑或 API
`whitelist.yml`	API 白名单	手动编辑或 API
`audit.yml`	审计日志配置	手动编辑或 API

user.yml #

此文件是内置用户配置文件，用于定义系统的初始用户账户及其相关配置（如密码哈希、角色分配等）。

admin 用户是 Easysearch 系统中的默认超级管理员用户。

配置文件里面的密码不能是明文，必须使用 Hash 之后的密码，通过命令 ./bin/hash_password.sh -p <new-password> 可以生成一个密码哈希。

默认配置 #

---
_meta:
  type: "user"
  config_version: 2

admin:
  hash: "$2y$12$GNHStWSkQzhP9LnUbCVv2O2aFx67vXcFHcQvqC.vaE4AR66xAk0zG"
  reserved: true
  external_roles:
    - "admin"
  description: "Default admin user"

字段说明 #

字段	说明
`hash`	bcrypt 密码哈希（使用 `bin/hash_password.sh` 生成）
`reserved`	是否为内置用户（`true` 不可通过 API 删除）
`hidden`	是否在用户列表中隐藏
`external_roles`	外部角色列表（用于角色映射）
`attributes`	自定义用户属性（用于细粒度权限控制）
`description`	用户描述信息
`static`	是否为静态用户（`true` 仅通过文件管理）

修改密码 #

使用密码哈希工具生成新的 bcrypt 哈希：

# 生成密码哈希
$ES_HOME/bin/hash_password.sh -p newpassword

或使用 API 修改（需要已认证）：

# 修改用户密码
curl -k -u admin:oldpassword -X PUT "https://localhost:9200/_security/account" \
  -H "Content-Type: application/json" \
  -d '{"password": "newpassword"}'

role.yml #

定义不同用户角色的权限。replication_leader 和 replication_follower 用于跨集群复制，security 用于允许通过 REST API 管理安全设置。

⚠️ 警告！ 以下角色已被弃用，将在未来的版本中删除，请勿使用：
security_rest_api_access
cross_cluster_replication_leader_full_access
cross_cluster_replication_follower_full_access

默认配置 #

---
_meta:
  type: "role"
  config_version: 2

replication_leader:
  reserved: true
  description: "Grants read access to leader indices for cross-cluster replication."
  indices:
    - names:
        - "*"
      privileges:
        - "indices:admin/plugins/replication/index/setup/validate"
        - "indices:data/read/plugins/replication/changes"
        - "indices:data/read/plugins/replication/file_chunk"

replication_follower:
  reserved: true
  description: "Grants manage replication permissions on follower indices."
  cluster:
    - "cluster:admin/plugins/replication/autofollow/update"
  indices:
    - names:
        - "*"
      privileges:
        - "indices:admin/plugins/replication/index/setup/validate"
        - "indices:data/write/plugins/replication/changes"
        - "indices:admin/plugins/replication/index/start"
        - "indices:admin/plugins/replication/index/pause"
        - "indices:admin/plugins/replication/index/resume"
        - "indices:admin/plugins/replication/index/stop"
        - "indices:admin/plugins/replication/index/update"
        - "indices:admin/plugins/replication/index/status_check"

security:
  reserved: true
  description: "Grants access to the security REST API."

字段说明 #

字段	说明
`cluster`	集群级权限列表（如 `cluster:monitor/`、`cluster:admin/` 等）
`indices`	索引级权限列表，每项包含 `names`（索引模式）和 `privileges`（允许的操作）
`reserved`	是否为内置角色
`hidden`	是否在角色列表中隐藏
`description`	角色描述信息
`static`	是否为静态角色（仅通过文件管理）

索引权限项字段 #

字段	说明
`names`	索引名称模式列表，支持通配符 `*`
`privileges`	允许的操作列表，可以是具体权限或权限集合名称
`query`	文档级安全（DLS），限制可见文档的查询条件
`field_security`	字段级安全（FLS），限制可见的字段列表
`field_mask`	字段脱敏，对指定字段进行脱敏处理

自定义角色示例 #

logs_reader:
  reserved: false
  description: "Custom role for reading log indices."
  cluster:
    - "cluster:monitor/health"
  indices:
    - names:
        - "logs-*"
      privileges:
        - "read"
        - "search"

常见权限 #

集群权限：

cluster:* — 所有集群操作
cluster:monitor/* — 监控操作
cluster:admin/* — 管理操作

索引权限：

indices:admin/* — 索引管理
indices:data/write/* — 写入操作
indices:data/read/* — 读取操作

权限集合名称（在 privileges 中可直接使用）：

read — 所有读取操作
write — 所有写入操作
search — 搜索操作
get — 获取单个文档
index — 索引文档
crud — 增删改查组合
manage — 索引管理
indices_all — 所有索引操作

完整权限列表参见权限列表。

role_mapping.yml #

将用户（users）、外部组/角色（external_roles）以及主机（hosts）映射到 Easysearch 的安全角色。

各角色的权限定义在 role.yml，此文件仅决定"谁拥有哪些角色"。每个角色条目下，只要当前主体命中 users、external_roles 或 hosts 中的任意一项，即会获得该角色。

提示示例文件中包含一条已弃用的映射（all_access）。请勿再使用此条目，未来版本会移除。

默认配置 #

---
_meta:
  type: "role_mapping"
  config_version: 2

superuser:
  reserved: false
  external_roles:
    - "admin"
  description: "Maps admin to superuser"

字段说明 #

字段	说明
`external_roles`	外部角色名称列表（LDAP 组、SAML 角色等）
`users`	直接映射的用户名列表
`and_external_roles`	多个外部角色的 AND 条件（必须同时属于所有列出的角色）
`hosts`	客户端主机名/IP 列表
`description`	映射描述信息

使用场景 #

LDAP：映射 LDAP 组的 DN 到 Easysearch 角色
SAML：映射 SAML 属性中的角色值
本地用户：将 user.yml 中用户的 external_roles 映射到角色

自定义映射示例 #

data_team:
  reserved: false
  external_roles:
    - "cn=data-team,ou=groups,dc=example,dc=com"
  users:
    - "analyst@example.com"
  description: "Maps data team LDAP group and specific users to data_team role"

privilege.yml #

定义自定义权限组（Action Group），在角色中复用。系统已内置多个常用权限组（如 read、write、search 等），此文件用于定义额外的自定义权限组。

默认配置 #

除了元数据之外，该文件默认为空，因为安全模块已内置了常用权限集合：

---
_meta:
  type: "privilege"
  config_version: 2

自定义权限组示例 #

SEARCH_ROLE:
  reserved: false
  allowed_actions:
    - "indices:data/read/search*"
    - "indices:data/read/get*"

WRITE_ROLE:
  reserved: false
  allowed_actions:
    - "indices:data/write/index*"
    - "indices:data/write/update*"

在角色中使用 #

在 role.yml 的 privileges 中引用权限组名称：

logs_writer:
  indices:
    - names:
        - "logs-*"
      privileges:
        - "SEARCH_ROLE"
        - "WRITE_ROLE"

config.yml #

配置认证方式（Basic Auth、LDAP、SAML 等）和授权后端。详细说明请参见认证后端配置。

默认配置 #

---
_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    http:
      anonymous_auth_enabled: false
      # xff:
      #   enabled: false
      #   internalProxies: '192\.168\.0\.10|192\.168\.0\.11' # regex pattern

    authc:
      basic_internal_auth_domain:
        description: "Authenticate via HTTP Basic against internal users database"
        http_enabled: true
        transport_enabled: true
        order: 4
        http_authenticator:
          type: basic
          challenge: true
        authentication_backend:
          type: internal

    authz:
      basic_authz:
        http_enabled: true
        transport_enabled: true
        authorization_backend:
          type: noop

关键部分 #

配置块	说明
`http`	HTTP 层设置，包括匿名认证和 XFF 代理配置
`authc`	认证域配置，支持 `basic`、`proxy`、`kerberos`、`clientcert`、`jwt` 等类型
`authz`	授权后端配置，支持 `noop`、`ldap` 等类型

nodes_dn.yml #

定义允许加入集群的节点证书 DN（Distinguished Name）列表，与 easysearch.yml 中的 security.nodes_dn 作用相同，用于节点间 TLS 认证。

默认配置 #

---
_meta:
  type: "nodesdn"
  config_version: 2

# Define nodesdn mapping name and corresponding values
# cluster1:
#   nodes_dn:
#     - CN=*.example.com

默认文件为空，表示不做额外的节点 DN 限制。

whitelist.yml #

限制非超级管理员用户可以访问的 API 端点。

默认配置 #

---
_meta:
  type: "whitelist"
  config_version: 2

config:
  enabled: false
  requests:
    /_cluster/settings:
      - GET
    /_cat/nodes:
      - GET

字段说明 #

字段	说明
`enabled`	是否启用白名单功能。`false` 表示关闭白名单，所有 API 均可访问
`requests`	白名单规则，键为 API 路径，值为允许的 HTTP 方法列表

注意：白名单仅对非超级管理员用户生效。超级管理员（通过 admin 证书认证）始终可以访问所有 API。

audit.yml #

配置安全审计日志的记录范围和行为。

默认配置 #

---
_meta:
  type: "audit"
  config_version: 2

config:
  enabled: true
  audit:
    enable_rest: true
    disabled_rest_categories:
      - AUTHENTICATED
      - GRANTED_PRIVILEGES
    enable_transport: true
    disabled_transport_categories:
      - AUTHENTICATED
      - GRANTED_PRIVILEGES
    ignore_users: []
    ignore_requests: []
    resolve_bulk_requests: false
    log_request_body: true
    resolve_indices: true
    exclude_sensitive_headers: true
  compliance:
    enabled: true
    internal_config: true
    external_config: false
    read_metadata_only: true
    read_watched_fields: {}
    read_ignore_users: []
    write_metadata_only: true
    write_log_diffs: false
    write_watched_indices: []
    write_ignore_users: []

审计配置字段 #

字段	说明
`enabled`	是否启用审计日志
`enable_rest`	是否审计 REST API 请求
`enable_transport`	是否审计传输层请求
`disabled_rest_categories`	REST 层排除的审计类别
`disabled_transport_categories`	传输层排除的审计类别
`include_users`	仅审计指定用户列表（可选，支持通配符）
`ignore_users`	排除审计的用户列表（支持通配符）
`ignore_requests`	排除审计的请求列表（支持通配符）
`resolve_bulk_requests`	是否记录 bulk 请求中的每个操作
`log_request_body`	是否记录请求体
`resolve_indices`	是否解析请求涉及的索引（含别名与通配符）
`exclude_sensitive_headers`	是否排除敏感 HTTP 头（如 Authorization）

合规性配置字段 #

字段	说明
`enabled`	是否启用合规审计
`internal_config`	是否记录安全配置的内部变更
`external_config`	是否记录外部配置文件的变更
`read_metadata_only`	读取事件是否仅记录元数据
`read_watched_fields`	监控读取的索引和字段
`read_ignore_users`	读取审计忽略用户列表
`write_metadata_only`	写入事件是否仅记录元数据
`write_log_diffs`	是否记录文档更新的差异
`write_watched_indices`	监控写入的索引列表
`write_ignore_users`	写入审计忽略用户列表

修改配置文件 #

方式 1：手动编辑（需重新加载） #

修改 config/security/ 目录下的 YAML 文件后，需要重新初始化安全索引使配置生效：

# 编辑配置
vi config/security/config.yml

# 重新加载安全配置（以管理员身份删除安全索引后重启）
curl -XDELETE -k --cert admin.crt --key admin.key 'https://localhost:9200/.security'
# 然后重启 Easysearch 服务

也可以使用初始化脚本：

bin/initialize.sh

方式 2：使用 API（即时生效） #

大多数配置可以通过安全 REST API 修改，即时生效：

# 获取现有角色
curl -k -u admin:password "https://localhost:9200/_security/role/my_role"

# 创建或修改角色
curl -k -u admin:password -X PUT "https://localhost:9200/_security/role/my_role" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster": ["cluster:monitor/health"],
    "indices": [{
      "names": ["logs-*"],
      "privileges": ["read", "search"]
    }]
  }'

# 创建用户
curl -k -u admin:password -X PUT "https://localhost:9200/_security/user/newuser" \
  -H "Content-Type: application/json" \
  -d '{"password": "StrongPass123!", "external_roles": ["admin"]}'

注意任何对本地配置文件的修改（如 user.yml、role.yml、role_mapping.yml），修改后必须以管理员身份删除 .security 索引，然后重启服务才能生效：
curl -XDELETE -k --cert admin.crt --key admin.key 'https://localhost:9200/.security'

文件权限 #

安全配置文件包含敏感信息（如密码哈希），应该限制访问权限：

# 只有 Easysearch 进程用户可以读取
chmod 600 config/security/*.yml

# 配置目录权限
chmod 700 config/security/

本地配置（YAML） #

相关指南（先读这些） #

配置文件概览 #

user.yml #

默认配置 #

字段说明 #

修改密码 #

role.yml #

默认配置 #

字段说明 #

索引权限项字段 #

自定义角色示例 #

常见权限 #

role_mapping.yml #

默认配置 #

字段说明 #

使用场景 #

自定义映射示例 #

privilege.yml #

默认配置 #

自定义权限组示例 #

在角色中使用 #

config.yml #

默认配置 #

关键部分 #

nodes_dn.yml #

默认配置 #

whitelist.yml #

默认配置 #

字段说明 #

audit.yml #

默认配置 #

审计配置字段 #

合规性配置字段 #

修改配置文件 #

方式 1：手动编辑（需重新加载） #

方式 2：使用 API（即时生效） #

文件权限 #