REST API

安全插件 REST API 允许您以编程方式创建和管理用户、角色、角色映射、操作组和租户。

API 的访问控制

与 UDB-SX 权限类似，您可以使用角色来控制对安全插件 REST API 的访问。在 udbsx.yml 中指定角色：

plugins.security.restapi.roles_enabled: ["<role>", ...]

如果您正在管理需要超级管理员访问权限的专有名称或证书的 API，请在 udbsx.yml 文件中启用 REST API 管理员配置，如下面的设置示例所示：

plugins.security.restapi.admin.enabled: true

这些角色现在可以访问所有 API。要阻止访问某些 API：

plugins.security.restapi.endpoints_disabled.<role>.<endpoint>: ["<method>", ...]

角色还允许您控制对特定 REST API 的访问。您可以将单个或多个集群权限添加到角色中，并在用户映射到该角色时授予他们访问相关 API 的权限。以下集群权限列表包含对应安全 REST API 的端点：

权限	授予的 API	描述
restapi:admin/actiongroups	`/actiongroup` 和 `/actiongroups`	获取、删除、创建和修补操作组（包括批量更新）的权限。
restapi:admin/allowlist	`/allowlist`	将任何端点和 HTTP 请求添加到允许的端点和请求列表的权限。
restapi:admin/internalusers	`/internaluser` 和 `/user`	在集群中添加、检索、修改和删除任何用户的权限。
restapi:admin/nodesdn	`/nodesdn`	从白名单中添加、检索、更新或删除任何专有名称以及启用集群和/或节点间通信的权限。
restapi:admin/roles	`/roles`	在集群中添加、检索、修改和删除任何角色的权限。
restapi:admin/rolesmapping	`/rolesmapping`	添加、检索、修改和删除任何角色映射的权限。
restapi:admin/ssl/certs/info	`/ssl/certs/info`	查看当前传输层和 HTTP 证书的权限。
restapi:admin/ssl/certs/reload	`/ssl/certs/reload`	重新加载传输层和 HTTP 证书的权限。
restapi:admin/tenants	`/tenants`	获取、删除、创建和修补租户的权限。

endpoint 的可能值为：

ACTIONGROUPS
ROLES
ROLESMAPPING
INTERNALUSERS
CONFIG
CACHE
SYSTEMINFO
NODESDN
SSL

method 的可能值为：

GET
PUT
POST
DELETE
PATCH

例如，以下配置授予三个角色访问 REST API 的权限，但随后阻止 test-role 向 _plugins/_security/api/roles 或 _plugins/_security/api/internalusers 发出 PUT、POST、DELETE 或 PATCH 请求：

plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"]
plugins.security.restapi.endpoints_disabled.test-role.ROLES: ["PUT", "POST", "DELETE", "PATCH"]
plugins.security.restapi.endpoints_disabled.test-role.INTERNALUSERS: ["PUT", "POST", "DELETE", "PATCH"]

要对配置 API 使用 PUT 和 PATCH 方法，请在 udbsx.yml 中添加以下行：

plugins.security.unsupported.restapi.allow_securityconfig_modification: true

保留和隐藏资源

您可以将用户、角色、角色映射和操作组标记为保留。将此标志设置为 true 的资源无法使用 REST API 或 UDB-SX Dashboards 进行更改。

要将资源标记为保留，请添加以下标志：

kibana_user:
  reserved: true

同样，您可以将用户、角色、角色映射和操作组标记为隐藏。将此标志设置为 true 的资源不会由 REST API 返回，并且在 UDB-SX Dashboards 中不可见：

kibana_user:
  hidden: true

隐藏资源会自动保留。

要添加或删除这些标志，请修改 config/udbsx-security/internal_users.yml 并运行 plugins/udbsx-security/tools/securityadmin.sh。

账户

获取账户详情

返回当前用户的账户详情。例如，如果您以 admin 用户身份签署请求，则响应将包含该用户的详细信息。

示例请求

GET _plugins/_security/api/account

示例响应

{
  "user_name": "admin",
  "is_reserved": true,
  "is_hidden": false,
  "is_internal_user": true,
  "user_requested_tenant": null,
  "backend_roles": [
    "admin"
  ],
  "custom_attribute_names": [],
  "tenants": {
    "global_tenant": true,
    "admin_tenant": true,
    "admin": true
  },
  "roles": [
    "own_index",
    "all_access"
  ]
}

更改密码

更改当前用户的密码。

端点

PUT _plugins/_security/api/account

示例请求体字段

字段	数据类型	描述	必需
current_password	String	当前密码。	是
password	String	要设置的新密码。	是

示例请求

PUT _plugins/_security/api/account
{
    "current_password": "old-password",
    "password": "new-password"
}

示例响应

{
  "status": "OK",
  "message": "'test_user1' updated."
}

响应体字段

字段	数据类型	描述
status	String	操作状态。
message	String	描述性消息。

操作组

获取操作组

检索一个操作组。

GET _plugins/_security/api/actiongroups/<action-group>

示例请求

GET _plugins/_security/api/actiongroups/write

示例响应

{
  "write": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "indices:data/write*",
      "indices:admin/mapping/put"
    ],
    "type": "index",
    "description": "Allow writing data",
    "static": true
  }
}

获取操作组

检索所有操作组。

示例请求

GET _plugins/_security/api/actiongroups/

示例响应

{
  "data_access": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "indices:data/*",
      "crud"
    ],
    "type": "index",
    "description": "Allow all read/write operations on data",
    "static": true
  },
  "delete": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "indices:data/write/delete*"
    ],
    "type": "index",
    "description": "Allow deleting documents",
    "static": true
  },
  "cluster_manage_pipelines": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "cluster:admin/ingest/pipeline/*"
    ],
    "type": "cluster",
    "description": "Manage pipelines",
    "static": true
  },
  ...
}

创建操作组

创建或替换指定的操作组。

示例请求

PUT _plugins/_security/api/actiongroups/my-test-action-group
{
  "type": "index",
  "allowed_actions": [
    "indices:data/write/index*",
    "indices:data/write/update*",
    "indices:admin/mapping/put",
    "indices:data/write/bulk*",
    "read",
    "write"
  ]
}

示例响应

{
  "status": "CREATED",
  "message": "'my-test-action-group' created."
}

更新操作组

更新操作组的单个属性。

请求

PUT /_plugins/_security/api/actiongroups/my-test-action-group
{
  "type": "index",
  "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"]
}

示例响应

{
  "status": "OK",
  "message": "'my-test-action-group' updated."
}

PATCH 方法暂不支持在UDB-SX 前端使用，但可在后端使用，示例如下：

curl  -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/actiongroups/my-test-action-group" -H 'Content-Type: application/json' -d'
[{
    "op": "replace", "path": "/allowed_actions", "value": ["indices:admin/create", "indices:admin/mapping/put"]
  }
]
'

示例响应

{"status":"OK","message":"'my-test-action-group' updated."}

在一次调用中创建、更新或删除多个操作组。

curl  -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/actiongroups" -H 'Content-Type: application/json' -d'
[
  {  "op": "add", "path": "/CREATE_INDEX", "value": { "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"] }
  },
  {
    "op": "remove", "path": "/CRUD"
  }
]
'

示例响应

{"status":"OK","message":"Resource updated."}

删除操作组

DELETE _plugins/_security/api/actiongroups/<action-group>

请求

DELETE _plugins/_security/api/actiongroups/my-test-action-group

示例响应

{
  "status": "OK",
  "message": "'my-test-action-group' deleted."
}

用户

这些调用允许您创建、更新和删除内部用户。

查询指定用户

GET _plugins/_security/api/internalusers/<用户名>

请求

GET _plugins/_security/api/internalusers/admin

示例响应

{
  "admin": {
    "hash": "",
    "reserved": true,
    "hidden": false,
    "backend_roles": [
      "admin"
    ],
    "attributes": {},
    "description": "Demo admin user",
    "opendistro_security_roles": [],
    "static": false
  }
}

查询所有用户

请求

GET _plugins/_security/api/internalusers/

示例响应

{
  "logstash": {
    "hash": "",
    "reserved": false,
    "hidden": false,
    "backend_roles": [
      "logstash"
    ],
    "attributes": {},
    "description": "Demo logstash user, using external role mapping",
    "opendistro_security_roles": [],
    "static": false
  },
  "snapshotrestore": {
    "hash": "",
    "reserved": false,
    "hidden": false,
    "backend_roles": [
      "snapshotrestore"
    ],
    "attributes": {},
    "description": "Demo snapshotrestore user, using external role mapping",
    "opendistro_security_roles": [],
    "static": false
  },
  "admin": {
    "hash": "",
    "reserved": true,
    "hidden": false,
    "backend_roles": [
      "admin"
    ],
    "attributes": {},
    "description": "Demo admin user",
    "opendistro_security_roles": [],
    "static": false
  },
  ...
}

创建用户

创建或替换指定的用户。您必须指定 password（明文）或 hash（哈希后的用户密码）。如果指定 password，安全插件会在存储之前自动对密码进行哈希处理。

请注意，您提供的 opendistro_security_roles 数组中的任何角色必须已存在，安全插件才能将用户映射到该角色。

请求

PUT _plugins/_security/api/internalusers/test_user
{
  "password": "Jiuyou@123",
  "opendistro_security_roles": ["kibana_user", "own_index"],
  "backend_roles": ["role 1", "role 2"],
  "attributes": {
    "attribute1": "value1",
    "attribute2": "value2"
  }
}

示例响应

{
  "status": "CREATED",
  "message": "'test_user' created."
}

修改用户

修改内部用户的单个属性。PATCH 方法暂不支持在UDB-SX 前端使用，但可在后端使用，示例如下：

请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/internalusers/test_user" -H 'Content-Type: application/json' -d'
[
{
    "op": "replace", "path": "/backend_roles", "value": ["klingons"]
  },
  {
    "op": "replace", "path": "/opendistro_security_roles", "value": ["all_access"]
  },
  {
    "op": "replace", "path": "/attributes", "value": { "newattribute": "newvalue" }
  }
]
'

示例响应

{"status":"OK","message":"'test_user' updated."}

等效 PUT 方法。

请求

PUT /_plugins/_security/api/internalusers/test_user
{
  "opendistro_security_roles": ["all_access"],
  "backend_roles": ["klingons"],
  "attributes": {
    "newattribute": "newvalue"
  }
}

示例响应

{
  "status": "OK",
  "message": "'test_user' updated."
}

在一次调用中创建、更新或删除多个内部用户。

请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/internalusers" -H 'Content-Type: application/json' -d'
[
  {
    "op": "add", "path": "/spock", "value": { "password": "Jiuyou@123", "backend_roles": ["testrole1"] }
  },
  {
    "op": "add", "path": "/worf", "value": { "password": "Jiuyou@321", "backend_roles": ["testrole2"] }
  },
  {
    "op": "remove", "path": "/riker"
  }
]
'

示例响应

{"status":"OK","message":"Resource updated."}v

删除用户

DELETE _plugins/_security/api/internalusers/<用户名>

请求

DELETE _plugins/_security/api/internalusers/test_user

示例响应

{
  "status": "OK",
  "message": "'test_user' deleted."
}

角色

检索所有角色

请求

GET _plugins/_security/api/roles/

示例响应

{
  "observability_read_access": {
    "reserved": true,
    "hidden": false,
    "cluster_permissions": [
      "cluster:admin/opensearch/observability/get"
    ],
    "index_permissions": [],
    "tenant_permissions": [],
    "static": false
  },
  "kibana_user": {
    "reserved": true,
    "hidden": false,
    "description": "Provide the minimum permissions for a kibana user",
    "cluster_permissions": [
      "cluster_composite_ops"
    ],
    "index_permissions": [
      {
        "index_patterns": [
          ".kibana",
          ".kibana-6",
          ".kibana_*",
          ".opensearch_dashboards",
          ".opensearch_dashboards-6",
          ".opensearch_dashboards_*"
        ],
        "fls": [],
        "masked_fields": [],
        "allowed_actions": [
          "read",
          "delete",
          "manage",
          "index"
        ]
      },
  ...
}

检索指定角色

GET _plugins/_security/api/roles/<角色名>

示例请求

GET _plugins/_security/api/roles/own_index

示例响应

{
  "own_index": {
    "reserved": true,
    "hidden": false,
    "description": "Allow all for indices named like the current user",
    "cluster_permissions": [
      "cluster_composite_ops"
    ],
    "index_permissions": [
      {
        "index_patterns": [
          "${user_name}"
        ],
        "fls": [],
        "masked_fields": [],
        "allowed_actions": [
          "indices_all"
        ]
      }
    ],
    "tenant_permissions": [],
    "static": true
  }
}

创建角色

创建或替换指定的角色。

示例请求

PUT _plugins/_security/api/roles/test_role
{
  "cluster_permissions": [
    "cluster_composite_ops",
    "indices_monitor"
  ],
  "index_permissions": [{
    "index_patterns": [
      "movies*"
    ],
    "dls": "",
    "fls": [],
    "masked_fields": [],
    "allowed_actions": [
      "read"
    ]
  }],
  "tenant_permissions": [{
    "tenant_patterns": [
      "human_resources"
    ],
    "allowed_actions": [
      "kibana_all_read"
    ]
  }]
}

示例响应

{
  "status": "CREATED",
  "message": "'test_role' created."
}

修改角色

修改角色的单个属性。PATCH 方法暂不支持在UDB-SX 前端使用，但可在后端使用，示例如下：

示例请求

curl -k -u admin:admin -X PATCH "https://localhost:10200/_plugins/_security/api/roles/test_role" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "op": "add", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"]
    },
    {
      "op": "remove", "path": "/index_permissions/0/dls"
    }
  ]'

示例响应

{"status":"OK","message":"'test_role' updated."}

删除角色

示例请求

DELETE _plugins/_security/api/roles/<role>

示例响应

{
  "status":"OK",
  "message":"role test-role deleted."
}

角色映射

获取角色映射

检索指定角色映射。

GET _plugins/_security/api/rolesmapping/<角色名>

示例请求

GET _plugins/_security/api/rolesmapping/kibana_user

示例响应

{
  "kibana_user": {
    "hosts": [],
    "users": [],
    "reserved": false,
    "hidden": false,
    "backend_roles": [
      "kibanauser"
    ],
    "and_backend_roles": [],
    "description": "Maps kibanauser to kibana_user"
  }
}

检索所有角色映射。

请求

GET _plugins/_security/api/rolesmapping

示例响应

{
  "manage_snapshots": {
    "hosts": [],
    "users": [],
    "reserved": false,
    "hidden": false,
    "backend_roles": [
      "snapshotrestore"
    ],
    "and_backend_roles": []
  },
  "logstash": {
    "hosts": [],
    "users": [],
    "reserved": false,
    "hidden": false,
    "backend_roles": [
      "logstash"
    ],
    "and_backend_roles": []
  },
  "own_index": {
    "hosts": [],
    "users": [
      "*"
    ],
    "reserved": false,
    "hidden": false,
    "backend_roles": [],
    "and_backend_roles": [],
    "description": "Allow full access to an index named like the username"
  },
  ...
}

创建角色映射

创建或替换指定的角色映射。

示例请求

PUT _plugins/_security/api/rolesmapping/<role>
{
  "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
  "hosts" : [ "*.starfleetintranet.com" ],
  "users" : [ "worf" ]
}

为角色名，以下为test-role 示例

示例响应

{
  "status": "CREATED",
  "message": "'test-role' created."
}

修补角色映射

更新角色映射的单个属性。PATCH 方法暂不支持在UDB-SX 前端使用，但可通过curl 在后端使用，示例如下：

示例请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/rolesmapping/test-role" -H 'Content-Type: application/json' -d'
[{
    "op": "replace", "path": "/users", "value": ["myuser"]
  },
  {
    "op": "replace", "path": "/backend_roles", "value": ["mybackendrole"]
  }
]
'

示例响应

{"status":"OK","message":"'test-role' updated."}

在一次调用中创建或更新多个角色映射。

示例请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/rolesmapping" -H 'Content-Type: application/json' -d'
[{
    "op": "add", "path": "/human_resources", "value": { "users": ["user1"], "backend_roles": ["backendrole2"] }
  },
  {
    "op": "add", "path": "/finance", "value": { "users": ["user2"], "backend_roles": ["backendrole2"] }
  }
]
'

示例响应

{"status":"OK","message":"Resource updated."}

删除角色映射

删除指定的角色映射。

示例请求

DELETE _plugins/_security/api/rolesmapping/test-role

示例响应

{
  "status": "OK",
  "message": "'test-role' deleted."
}

白名单

关于白名单的相关操作需要超级管理员权限，超级管理员只能通过证书进行身份验证，而不是密码，所以无法在前端操作。证书位于 udbsx/udbsx-25.0.0/config/certs/ 目录下。

获取白名单

检索当前的 allowlist 配置。

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem  -XGET "https://localhost:10200/_plugins/_security/api/allowlist"

示例响应

{"config":{"enabled":false,"requests":{"/_cluster/settings":["GET"],"/_cat/nodes":["GET"]}}}

创建白名单

创建一个 allowlist 配置。

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPUT "https://localhost:10200/_plugins/_security/api/allowlist" -H 'Content-Type: application/json' -d'
{
  "enabled": true,
  "requests": {
    "/_cat/nodes": ["GET"],
    "/_cat/indices": ["GET"],
    "/_plugins/_security/whoami": ["GET"]
  }
}
'

示例响应

{"status":"OK","message":"'config' updated."}

更新白名单

更新一个 allowlist 配置。

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPATCH "https://localhost:10200/_plugins/_security/api/allowlist" -H 'Content-Type: application/json' -d'
[{
    "op": "add",
    "path": "/config/requests",
    "value": {
      "/_cat/nodes": ["POST"]
    }
  }
]
'

示例响应

{"status":"OK","message":"Resource updated."}

租户

获取租户

检索一个租户。

示例请求

GET _plugins/_security/api/tenants/<tenant>

以 global_tenant 为例

示例响应

{
  "global_tenant": {
    "reserved": true,
    "hidden": false,
    "description": "Global tenant",
    "static": true
  }
}

检索所有租户。

示例请求

GET _plugins/_security/api/tenants/

示例响应

{
  "global_tenant": {
    "reserved": true,
    "hidden": false,
    "description": "Global tenant",
    "static": true
  },
  "admin_tenant": {
    "reserved": false,
    "hidden": false,
    "description": "Demo tenant for admin user",
    "static": false
  }
}

创建租户

创建或替换指定的租户。

示例请求

PUT _plugins/_security/api/tenants/<tenant>
{
  "description": "A tenant for the human resources team."
}

示例响应

{
  "status": "CREATED",
  "message": "'test_tenant' created."
}

修补租户

添加、删除或修改单个租户。PATCH 方法暂不支持在UDB-SX 前端使用，但可通过curl 在后端使用，示例如下：

示例请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/tenants/test_tenant" -H 'Content-Type: application/json' -d'
[{
    "op": "replace", "path": "/description", "value": "An updated description"
  }
]
'

示例响应

{"status":"OK","message":"'test_tenant' updated."}

在一次调用中添加、删除或修改多个租户。

示例请求

curl -k -u admin:admin -XPATCH "https://localhost:10200/_plugins/_security/api/tenants/" -H 'Content-Type: application/json' -d'
[{
    "op": "replace",
    "path": "/test_tenant/description",
    "value": "An updated description"
  },
  {
    "op": "add",
    "path": "/another_tenant",
    "value": {
      "description": "Another description."
    }
  }
]
'

示例响应

{"status":"OK","message":"Resource updated."}

删除租户

删除指定的租户。

示例请求

DELETE _plugins/_security/api/tenants/<tenant>

示例响应

{
  "status": "OK",
  "message": "'test_tenant' deleted."
}

配置

获取配置

以 JSON 格式检索当前的安全插件配置。

示例请求

GET _plugins/_security/api/securityconfig

curl -k --cert ./admin.pem  --key ./admin-key.pem -XGET "https://localhost:10200/_plugins/_security/api/securityconfig"

更新配置

使用 REST API 创建或更新现有配置。此操作很容易破坏您现有的配置，因此我们建议使用 securityadmin.sh，它更安全。有关如何启用此操作的信息，请参阅API 的访问控制。

示例请求

PUT _plugins/_security/api/securityconfig/config
{
  "dynamic": {
    "filtered_alias_mode": "warn",
    "disable_rest_auth": false,
    "disable_intertransport_auth": false,
    "respect_request_indices_options": false,
    "udbsx-dashboards": {
      "multitenancy_enabled": true,
      "server_username": "kibanaserver",
      "index": ".udbsx-dashboards"
    },
    "http": {
      "anonymous_auth_enabled": false
    },
    "authc": {
      "basic_internal_auth_domain": {
        "http_enabled": true,
        "transport_enabled": true,
        "order": 0,
        "http_authenticator": {
          "challenge": true,
          "type": "basic",
          "config": {}
        },
        "authentication_backend": {
          "type": "intern",
          "config": {}
        },
        "description": "Authenticate via HTTP Basic against internal users database"
      }
    },
    "auth_failure_listeners": {},
    "do_not_fail_on_forbidden": false,
    "multi_rolespan_enabled": true,
    "hosts_resolver_mode": "ip-only",
    "do_not_fail_on_forbidden_empty": false
  }
}

示例响应

{
  "status": "OK",
  "message": "'config' updated."
}

修补配置

引入版本 1.0

使用 REST API 更新现有配置。此操作很容易破坏您现有的配置，因此我们建议使用 securityadmin.sh，它更安全。有关如何启用此操作的信息，请参阅API 的访问控制。

在执行此操作之前，您必须首先在 udbsx.yml 中添加以下行：

plugins.security.unsupported.restapi.allow_securityconfig_modification: true

示例请求

PATCH _plugins/_security/api/securityconfig
[
  {
    "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
  }
]

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPATCH "https://localhost:10200/_plugins/_security/api/securityconfig" -H 'Content-Type: application/json' -d'
[{
    "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
  }
]
'

示例响应

{
  "status": "OK",
  "message": "Resource updated."
}

配置升级检查

检查与主机安全插件捆绑的当前配置，并将其与用户下载的 UDB-SX 安全插件版本进行比较。然后，API 会响应指示是否可以执行升级以及可以更新哪些资源。

每个新的 UDB-SX 版本都会对默认安全配置进行更改。此端点可帮助集群操作员确定集群是否缺少默认值或具有过时的默认定义。

示例请求

GET _plugins/_security/api/_upgrade_check

示例响应

{
  "status" : "OK",
  "upgradeAvailable" : true,
  "upgradeActions" : {
    "roles" : {
      "add" : [ "flow_framework_full_access" ]
    }
  }
}

响应体字段

字段	数据类型	描述
`upgradeAvailable`	Boolean	当安全配置有可用升级时，响应为 `true`。
`upgradeActions`	Object list	升级主机安全插件时将修改的安全对象列表。

配置升级

根据最新版本安全插件捆绑的配置，在主机的现有安全配置上添加和更新资源。

这些捆绑的配置文件位于 <udbsx_HOME>/security/config 目录中。升级 UDB-SX 时会更新默认配置文件，而集群配置仅由集群操作员更新。此端点可帮助集群操作员升级缺失的默认值和过时的默认定义。

示例请求

POST _plugins/_security/api/_upgrade_perform
{
  "configs" : [ "roles" ]
}

示例请求体字段

字段	数据类型	描述	必需
`configs`	Array	指定要升级的配置。此字段可以包括以下任意配置的组合：`actiongroups`、`allowlist`、`audit`、`internalusers`、`nodesdn`、`roles`、`rolesmappings`、`tenants`。默认是所有支持的配置。	否

示例响应

{
  "status" : "OK",
  "upgrades" : {
    "roles" : {
      "add" : [ "flow_framework_full_access" ]
    }
  }
}

响应体字段

字段	数据类型	描述
`upgrades`	Object	升级结果的容器，按配置类型（例如 `roles`）组织。每个更改的配置类型将在此对象中表示为一个键。
`roles`	Object	包含由升级修改的基于角色的操作键的对象列表。

专有名称

这些 REST API 允许超级管理员（或具有足够权限访问此 API 的用户）添加、检索、更新或删除白名单中的任何专有名称，以启用集群和/或节点之间的通信。

在使用 REST API 配置白名单之前，必须先在 udbsx.yml 中添加以下行：

plugins.security.nodes_dn_dynamic_config_enabled: true

更新专有名称

在集群或节点的白名单中添加或更新指定的专有名称。

示例请求

PUT _plugins/_security/api/nodesdn/<cluster-name>
{
  "nodes_dn": [
    "CN=cluster3.example.com"
  ]
}

使用超级管理员身份验证：

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPUT "https://localhost:10200/_plugins/_security/api/nodesdn/my-cluster" -H 'Content-Type: application/json' -d'
{
  "nodes_dn": [
    "CN=cluster3.example.com"
  ]
}
'

示例响应

{"status":"CREATED","message":"'my-cluster' created."}

更新所有专有名称

对专有名称列表进行批量更新。

端点

PATCH _plugins/_security/api/nodesdn

示例请求体字段

字段	数据类型	描述	必需
op	string	对操作组执行的操作。可能的值：`remove`、`add`、`replace`、`move`、`copy`、`test`。	是
path	string	资源的路径。	是
value	Array	用于更新的新值。	是

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPATCH "https://localhost:10200/_plugins/_security/api/nodesdn" -H 'Content-Type: application/json' -d'
[{
      "op":"replace",
      "path":"/my-cluster/nodes_dn",
      "value": [
        "CN=Karen Berge,CN=admin,DC=corp,DC=Fabrikam,DC=COM",
        "CN=George Wall,CN=admin,DC=corp,DC=Fabrikam,DC=COM"]
   }
]
'

示例响应

{"status":"OK","message":"Resource updated."}

响应体字段

字段	数据类型	描述
status	string	响应状态。
message	string	响应消息。

获取专有名称

检索白名单中的所有专有名称。

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -XGET "https://localhost:10200/_plugins/_security/api/nodesdn"

示例响应

{
  "cluster1": {
    "nodes_dn": [
      "CN=cluster1.example.com"
    ]
  }
}

要获取特定集群或节点白名单中的专有名称，请在请求路径中包含集群名称。

示例请求

GET _plugins/_security/api/nodesdn/<cluster-name>

curl -k --cert ./admin.pem  --key ./admin-key.pem -XGET "https://localhost:10200/_plugins/_security/api/nodesdn/<cluster-name>"

以 my-cluster 为集群名称为例：

示例响应

{
  "my-cluster":{
    "nodes_dn":[
      "CN=Karen Berge,CN=admin,DC=corp,DC=Fabrikam,DC=COM",
      "CN=George Wall,CN=admin,DC=corp,DC=Fabrikam,DC=COM"
      ]
  }
}

删除专有名称

删除指定集群或节点白名单中的所有专有名称。

示例请求

DELETE _plugins/_security/api/nodesdn/<cluster-name>

curl -k --cert ./admin.pem  --key ./admin-key.pem -XDELETE "https://localhost:10200/_plugins/_security/api/nodesdn/my-cluster"

示例响应

{"status":"OK","message":"'my-cluster' deleted."}

证书

获取证书

检索集群的安全证书。

示例请求

GET _plugins/_security/api/ssl/certs

curl -k --cert ./admin.pem  --key ./admin-key.pem -XGET "https://localhost:10200/_plugins/_security/api/ssl/certs"

示例响应

{
    "http_certificates_list": [
        {
            "issuer_dn": "CN=Unvdb Root CA,O=ShenZhen Unversal DB Company,L=Shenzhen,ST=Guangdong,C=CN",
            "subject_dn": "CN=server.dns.a-record,O=ShenZhen Unversal DB Company,L=Shenzhen,ST=Guangdong,C=CN",
            "san": "[[2, server.dns.a-record]]",
            "not_before": "2025-12-08T11:01:27Z",
            "not_after": "2027-12-08T11:01:27Z"
        }
    ],
    "transport_certificates_list": [
        {
            "issuer_dn": "CN=Unvdb Root CA,O=ShenZhen Unversal DB Company,L=Shenzhen,ST=Guangdong,C=CN",
            "subject_dn": "CN=server.dns.a-record,O=ShenZhen Unversal DB Company,L=Shenzhen,ST=Guangdong,C=CN",
            "san": "[[2, server.dns.a-record]]",
            "not_before": "2025-12-08T11:01:27Z",
            "not_after": "2027-12-08T11:01:27Z"
        }
    ]
}

重新加载传输证书

重新加载传输层通信证书。这些 REST API 允许超级管理员（或具有足够权限访问此 API 的用户）重新加载传输层证书。需要先在配置文件 udbsx.yml 中启用 SSL 证书重新加载功能。因为安全考虑，默认不启用动态证书重载。在 udbsx.yml 中添加以下配置:

plugins.security.ssl_cert_reload_enabled: true

端点

PUT /_plugins/_security/api/ssl/transport/reloadcerts

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -XPUT "https://localhost:10200/_plugins/_security/api/ssl/transport/reloadcerts"

示例响应

{"message":"updated transport certs"}

响应体字段

字段	数据类型	描述
status	String	指示操作状态。可能的值："OK" 或错误消息。
message	String	有关操作的附加信息。

重新加载 HTTP 证书

重新加载 HTTP 层通信证书。这些 REST API 允许超级管理员（或具有足够权限访问此 API 的用户）重新加载 HTTP 层证书。

端点

PUT /_plugins/_security/api/ssl/http/reloadcerts

示例请求

curl -k --cert ./admin.pem  --key ./admin-key.pem -X PUT "https://localhost:10200/_plugins/_security/api/ssl/http/reloadcerts"

示例响应

{"message":"updated http certs"}

响应体字段

字段	数据类型	描述
status	String	API 操作的状态。可能的值："OK"。
message	String	指示 HTTP 证书已更新的消息。

缓存

刷新缓存

刷新安全插件用户、身份验证和授权缓存。

示例请求

DELETE _plugins/_security/api/cache

示例响应

{
  "status": "OK",
  "message": "Cache flushed successfully."
}

健康

健康检查

检查安全插件是否正在运行。如果您在负载均衡器后操作集群，此操作对于确定节点健康状况非常有用，并且不需要签署请求。

示例请求

GET _plugins/_security/health

示例响应

{
  "message": null,
  "mode": "strict",
  "status": "UP"
}

审计日志

安全插件提供以下 API 用于审计日志记录。

启用审计日志

此 API 允许您启用或禁用审计日志记录，定义审计日志记录和合规性的配置，以及更新设置。

您可以在 udbsx/udbsx-25.0.0/config/udbsx-security 目录中的 audit.yml 文件中进行审计日志的初始配置。之后，您可以使用 REST API 或 Dashboards 对配置进行进一步更改。

请求体字段

字段	数据类型	描述
`enabled`	Boolean	启用或禁用审计日志记录。默认值为 `true`。
`audit`	Object	包含审计日志记录配置的字段。
`audit.ignore_users`	Array	从审计中排除的用户。支持通配符模式。示例：`ignore_users: ["test-user", "employee-*"]`
`audit.ignore_requests`	Array	从审计中排除的请求。支持通配符模式。示例：`ignore_requests: ["indices:data/read/*", "SearchRequest"]`
`audit.disabled_rest_categories`	Array	从 REST API 审计中排除的类别。默认类别为 `AUTHENTICATED`、`GRANTED_PRIVILEGES`。
`audit.disabled_transport_categories`	Array	从传输 API 审计中排除的类别。默认类别为 `AUTHENTICATED`、`GRANTED_PRIVILEGES`。
`audit.log_request_body`	Boolean	包含请求的正文（如果可用），适用于 REST 和传输层。默认值为 `true`。
`audit.resolve_indices`	Boolean	记录请求影响的所有索引。解析别名和通配符/日期模式。默认值为 `true`。
`audit.resolve_bulk_requests`	Boolean	记录批量请求中的单个操作。默认值为 `false`。
`audit.exclude_sensitive_headers`	Boolean	从日志中排除敏感头信息。默认值为 `true`。
`audit.enable_transport`	Boolean	启用/禁用传输 API 审计。默认值为 `true`。
`audit.enable_rest`	Boolean	启用/禁用 REST API 审计。默认值为 `true`。
`compliance`	Object	包含合规性配置字段。
`compliance.enabled`	Boolean	启用或禁用合规性。默认值为 `true`。
`compliance.write_log_diffs`	Boolean	仅记录文档更新的差异。默认值为 `false`。
`compliance.read_watched_fields`	Object	用于监控读取事件的索引和字段映射。索引名称和字段均支持通配符模式。
`compliance.read_ignore_users`	Array	读取事件要忽略的用户列表。支持通配符模式。示例：`read_ignore_users: ["test-user", "employee-*"]`
`compliance.write_watched_indices`	Array	写入事件要监控的索引列表。支持通配符模式。示例：`write_watched_indices: ["twitter", "logs-*"]`
`compliance.write_ignore_users`	Array	写入事件要忽略的用户列表。支持通配符模式。示例：`write_ignore_users: ["test-user", "employee-*"]`
`compliance.read_metadata_only`	Boolean	对于读取事件，仅记录文档的元数据。默认值为 `true`。
`compliance.write_metadata_only`	Boolean	对于写入事件，仅记录文档的元数据。默认值为 `true`。
`compliance.external_config`	Boolean	记录节点的外部配置文件。默认值为 `false`。
`compliance.internal_config`	Boolean	记录内部安全更改的更新。默认值为 `true`。

对 _readonly 属性的更改会导致 409 错误，如下方响应所示。

{
  "status" : "error",
  "reason" : "Invalid configuration",
  "invalid_keys" : {
    "keys" : "_readonly,config"
  }
}

示例请求

GET

GET 调用检索审计配置。

GET /_opendistro/_security/api/audit

响应

GET 调用产生的响应类似于以下内容：

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

PUT

PUT 调用更新审计配置。

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

响应

{
  "status": "OK",
  "message": "'config' updated."
}

PATCH

PATCH 调用用于更新审计配置中的指定字段。PATCH 方法需要操作、路径和值来完成有效的请求。

UDB-SX Dashboards 开发工具目前不支持 PATCH 方法。您可以使用 curl、Postman 或其他替代方法来更新配置。

示例：

curl -k -u admin:admin -X PATCH  "https://localhost:10200/_opendistro/_security/api/audit" -H 'Content-Type: application/json' -d'
[
  {
    "op":"add",
    "path":"/config/enabled",
    "value":"true"
  }
]
'

PATCH 请求产生的响应类似于以下内容：

{"status":"OK","message":"Resource updated."}