UDB-SX安全性入门

演示配置是 UDB-SX 安全功能最便捷的入门方式。UDB-SX 捆绑了多个实用脚本，包括 install_demo_configuration.sh（Windows 系统为 install_demo_configuration.bat）。

该脚本位于 plugins/udbsx-security/tools 目录下，执行以下操作：

为传输层和 REST 层创建用于 TLS 加密的演示证书。
配置演示用户、角色和角色映射。
配置安全插件，使用内部数据库进行身份验证和授权。
在 udbsx.yml 文件中更新启动集群所需的基础配置。

此配置中的某些部分（如演示证书和默认密码）绝不能用于生产环境。在投入生产前，需将演示配置中的这些部分替换为自定义信息。

设置演示配置

运行 install_demo_configuration.sh 脚本前，必须创建一个名为 OPENSEARCH_INITIAL_ADMIN_PASSWORD 的环境变量，并设置一个强密码。该密码将用作管理员用户登录 UDB-SX 的凭证。可使用在线工具 Zxcvbn 测试密码强度。完成后，即可执行 install_demo_configuration.sh 并按照终端提示输入必要信息。

脚本执行完成后，可启动 UDB-SX 并运行以下命令测试配置：

curl -k -XGET -u admin:<密码> https://<udbsx-ip>:10200

你应会看到类似以下的输出：

{
  "name" : "node-2",
  "cluster_name" : "my-cluster",
  "cluster_uuid" : "0cKj6ZV8QX2mu4vxZhmZRw",
  "version" : {
    "distribution" : "udbsx",
    "number" : "25.0.0",
    "build_type" : "tar",
    "build_hash" : "a750b67b75705819b9ade21dcc9dea8486d73668",
    "build_date" : "2025-11-10T01:58:52.285989629Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.1",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The UDB-SX Project: https://www.unvdb.com/"
}

设置 UDB-SX Dashboards

要快速启动 UDB-SX Dashboards，可在 udbsx_dashboards.yml 中添加以下配置：

udbsx.hosts: [https://localhost:10200]
udbsx.ssl.verificationMode: none
udbsx.username: kibanaserver
udbsx.password: kibanaserver
udbsx.requestHeadersWhitelist: [authorization, securitytenant]

udbsx_security.multitenancy.enabled: true
udbsx_security.multitenancy.tenants.preferred: [Private, Global]
udbsx_security.readonly_mode.roles: [kibana_read_only]
# 若运行未启用 https 的 udbsx-dashboards，需启用此设置
udbsx_security.cookie.secure: false

可根据 UDB-SX 和 UDB-SX Dashboards 的安装方式，启动二进制文件或对应的服务。

若使用二进制文件启动，需在 yarn start 命令后添加 --no-base-path 参数，以设置无基础路径的 URL。若不设置，系统将自动添加随机的三字母基础路径。

启动 UDB-SX Dashboards 后，应会看到以下两条日志：

[info][listening] Server running at http://0.0.0.0:6601
[info][server][OpenSearchDashboards][http] http server running at http://0.0.0.0:6601

现在，可在浏览器中通过 http://localhost:6601 访问 UDB-SX Dashboards。使用用户名 admin 和在 OPENSEARCH_INITIAL_ADMIN_PASSWORD 环境变量中配置的密码登录。

添加用户

添加用户、角色及其他安全相关配置有三种方式：

更新相应的配置文件（添加/更新/删除用户需修改 internal_users.yml）
使用 API
使用 UDB-SX Dashboards 界面

安全配置文件位于 config/udbsx-security 目录下。

可通过在 internal_users.yml 文件中添加以下配置，创建 UDB-SX Dashboards 用户：

test-user:
  hash: "$2y$12$CkxFoTAJKsZaWv/m8VoZ6ePG3DBeBTAvoo4xA2P21VCS9w2RYumsG"
  backend_roles:
  - "test-backend-role"
  - "kibanauser"
  description: "测试用户"

hash 字符串通过 plugins/udbsx-security/tools/ 目录下的 hash.sh 脚本生成。本示例中使用的是字符串 secretpassword 的哈希值。

注意内置后端角色 kibanauser 的使用，该角色为用户提供浏览 UDB-SX Dashboards 所需的权限。

创建角色

roles.yml 中的角色采用以下结构：

<rolename>:
  cluster_permissions:
    - <cluster permission>
  index_permissions:
    - index_patterns:
      - <index pattern>
      allowed_actions:
        - <index permissions>

通过此结构，可配置新角色以授予对特定索引的访问权限，例如以下示例中的角色配置：

human_resources:
  index_permissions:
    - index_patterns:
      - "humanresources"
      allowed_actions:
        - "READ"

本示例中未列出集群权限，因为这些权限由内置角色 kibana_user 提供，而该角色已通过 kibanauser 后端角色完成映射。

将用户映射到角色

用户登录 UDB-SX 时，需映射到相应角色以获取正确权限。此映射通过 roles_mapping.yml 文件实现，文件结构如下：

<role_name>:
  users:
    - <username>
    - ...
  backend_roles:
    - <rolename>

要将新创建的用户 test-user 映射到 human_resources 角色，可在 roles_mapping.yml 文件中添加以下配置：

human_resources:
  backend_roles:
    - test-backend-role

另一个示例：roles_mappings.yml 文件中包含已映射到 kibana_user 角色的后端角色 kibanauser：

kibana_user:
  reserved: false
  backend_roles:
  - "kibanauser"
  description: "Maps kibanauser to kibana_user"

将配置上传到安全索引

配置用户、角色或其他安全相关设置的最后一步，是将配置上传到 UDB-SX 安全索引。仅更新文件而不上传，不会改变已运行的 UDB-SX 集群的配置。

要上传配置，可使用 install_demo_configuration.sh 执行过程中生成的管理员证书，运行以下命令：

./plugins/udbsx-security/tools/securityadmin.sh -cd "config/udbsx-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv