API

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

API 访问控制

就像 OpenSearch 权限一样，您可以使用角色控制对安全插件 REST API 的访问。在 opensearch.yml 中指定角色。

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

如果您正在使用需要超级管理员访问权限来管理 专有名称 或 证书 的 API，请在您的 opensearch.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"]

要将 PUT 和 PATCH 方法用于配置 API，请将以下行添加到 opensearch.yml：

plugins.security.unsupported.restapi.allow_securityconfig_modification: true

保留和隐藏资源

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

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

kibana_user:
  reserved: true

同样，您可以将用户、角色、角色映射和操作组标记为隐藏。设置此标志为 true 的资源不会通过 REST API 返回，也无法在 OpenSearch Dashboards 中看到

kibana_user:
  hidden: true

隐藏资源会自动保留。

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

账户

获取账户详情

1.0 版引入

返回当前用户的账户详情。例如，如果您以 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": [
    "all_access",
    "own_index"
  ]
}

更改密码

1.0 版引入

更改当前用户的密码。

端点

PUT _plugins/_security/api/account

请求正文字段

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

请求示例

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

示例响应

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

响应正文字段

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

操作组

获取操作组

1.0 版引入

检索一个操作组。

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

请求

GET _plugins/_security/api/actiongroups/custom_action_group

示例响应

{
  "custom_action_group": {
    "reserved": false,
    "hidden": false,
    "allowed_actions": [
      "kibana_all_read",
      "indices:admin/aliases/get",
      "indices:admin/aliases/exists"
    ],
    "description": "My custom action group",
    "static": false
  }
}

获取所有操作组

1.0 版引入

检索所有操作组。

请求

GET _plugins/_security/api/actiongroups/

示例响应

{
  "read": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "indices:data/read*",
      "indices:admin/mappings/fields/get*",
      "indices:admin/resolve/index"
    ],
    "type": "index",
    "description": "Allow all read operations",
    "static": true
  },
  "cluster_all": {
    "reserved": true,
    "hidden": false,
    "allowed_actions": [
      "cluster:*"
    ],
    "type": "cluster",
    "description": "Allow everything on cluster level",
    "static": true
  },
  ...
}

删除操作组

1.0 版引入

请求

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

示例响应

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

创建操作组

1.0 版引入

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

请求

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

示例响应

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

修补操作组

1.0 版引入

更新操作组的单个属性。

请求

PATCH _plugins/_security/api/actiongroups/<action-group>
[
  {
    "op": "replace", "path": "/allowed_actions", "value": ["indices:admin/create", "indices:admin/mapping/put"]
  }
]

示例响应

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

修补操作组

1.0 版引入

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

请求

PATCH _plugins/_security/api/actiongroups
[
  {
    "op": "add", "path": "/CREATE_INDEX", "value": { "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"] }
  },
  {
    "op": "remove", "path": "/CRUD"
  }
]

示例响应

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

用户

这些调用允许您创建、更新和删除内部用户。如果您使用外部认证后端，则可能无需担心内部用户。

获取用户

1.0 版引入

请求

GET _plugins/_security/api/internalusers/<username>

示例响应

{
  "kirk": {
    "hash": "",
    "roles": [ "captains", "starfleet" ],
    "attributes": {
       "attribute1": "value1",
       "attribute2": "value2",
    }
  }
}

获取所有用户

1.0 版引入

请求

GET _plugins/_security/api/internalusers/

示例响应

{
  "kirk": {
    "hash": "",
    "roles": [ "captains", "starfleet" ],
    "attributes": {
       "attribute1": "value1",
       "attribute2": "value2",
    }
  }
}

删除用户

1.0 版引入

请求

DELETE _plugins/_security/api/internalusers/<username>

示例响应

{
  "status":"OK",
  "message":"user kirk deleted."
}

创建用户

1.0 版引入

创建或替换指定的用户。您必须指定 password（纯文本）或 hash（用户的哈希密码）。如果您指定 password，安全插件将在存储之前自动哈希密码。

请注意，您在 opendistro_security_roles 数组中提供的任何角色都必须已存在，安全插件才能将用户映射到该角色。要查看预定义角色，请参阅预定义角色列表。有关如何创建角色的说明，请参阅创建角色。

请求

PUT _plugins/_security/api/internalusers/<username>
{
  "password": "kirkpass",
  "opendistro_security_roles": ["maintenance_staff", "database_manager"],
  "backend_roles": ["role 1", "role 2"],
  "attributes": {
    "attribute1": "value1",
    "attribute2": "value2"
  }
}

示例响应

{
  "status":"CREATED",
  "message":"User kirk created"
}

修补用户

1.0 版引入

更新内部用户的单个属性。

请求

PATCH _plugins/_security/api/internalusers/<username>
[
  {
    "op": "replace", "path": "/backend_roles", "value": ["klingons"]
  },
  {
    "op": "replace", "path": "/opendistro_security_roles", "value": ["ship_manager"]
  },
  {
    "op": "replace", "path": "/attributes", "value": { "newattribute": "newvalue" }
  }
]

示例响应

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

修补用户

1.0 版引入

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

请求

PATCH _plugins/_security/api/internalusers
[
  {
    "op": "add", "path": "/spock", "value": { "password": "testpassword1", "backend_roles": ["testrole1"] }
  },
  {
    "op": "add", "path": "/worf", "value": { "password": "testpassword2", "backend_roles": ["testrole2"] }
  },
  {
    "op": "remove", "path": "/riker"
  }
]

示例响应

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

角色

获取角色

1.0 版引入

检索一个角色。

请求

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

示例响应

{
  "test-role": {
    "reserved": false,
    "hidden": false,
    "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"
      ]
    }],
    "static": false
  }
}

获取所有角色

1.0 版引入

检索所有角色。

请求

GET _plugins/_security/api/roles/

示例响应

{
  "manage_snapshots": {
    "reserved": true,
    "hidden": false,
    "description": "Provide the minimum permissions for managing snapshots",
    "cluster_permissions": [
      "manage_snapshots"
    ],
    "index_permissions": [{
      "index_patterns": [
        "*"
      ],
      "fls": [],
      "masked_fields": [],
      "allowed_actions": [
        "indices:data/write/index",
        "indices:admin/create"
      ]
    }],
    "tenant_permissions": [],
    "static": true
  },
  ...
}

删除角色

1.0 版引入

请求

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

示例响应

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

创建角色

1.0 版引入

创建或替换指定的角色。

请求

PUT _plugins/_security/api/roles/<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": "OK",
  "message": "'test-role' updated."
}

由于与 Unicode 特殊字符相关的词边界，当文本字段类型值包含这些特殊字符之一时，Unicode 标准分析器无法将其作为一个整体值进行索引。因此，包含特殊字符的文本字段值会被标准分析器解析为由特殊字符分隔的多个值，从而有效地将其两侧的不同元素进行分词。

例如，由于字段 "user.id": "User-1" 和 "user.id": "User-2" 中的值包含连字符/减号，此特殊字符将阻止分析器区分 user.id 的两个不同用户，并将其解释为同一个用户。这可能导致文档的意外过滤，并可能危及对其访问的控制。

为避免这种情况，您可以使用自定义分析器或将字段映射为 keyword，后者执行精确匹配搜索。有关后一种选项，请参阅 Keyword 字段类型。

有关字段类型为 text 时应避免的字符列表，请参阅 Word Boundaries。

修补角色

1.0 版引入

更新角色的单个属性。

请求

PATCH _plugins/_security/api/roles/<role>
[
  {
    "op": "replace", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"]
  },
  {
    "op": "remove", "path": "/index_permissions/0/dls"
  }
]

示例响应

{
  "status": "OK",
  "message": "'<role>' updated."
}

修补角色

1.0 版引入

在一次调用中创建、更新或删除多个角色。

请求

PATCH _plugins/_security/api/roles
[
  {
    "op": "replace", "path": "/role1/index_permissions/0/fls", "value": ["myfield*", "~myfield1"]
  },
  {
    "op": "remove", "path": "/role1/index_permissions/0/dls"
  },
  {
    "op": "add", "path": "/role2/cluster_permissions/-", "value": {
      "index_patterns": ["test_index"],
      "allowed_actions": ["indices:data/read/scroll/clear"]
    }
  }
]

您可以使用 - 将新权限插入到权限数组的末尾。

示例响应

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

角色映射

获取角色映射

1.0 版引入

检索一个角色映射。

请求

GET _plugins/_security/api/rolesmapping/<role>

示例响应

{
  "role_starfleet" : {
    "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
    "hosts" : [ "*.starfleetintranet.com" ],
    "users" : [ "worf" ]
  }
}

获取所有角色映射

1.0 版引入

检索所有角色映射。

请求

GET _plugins/_security/api/rolesmapping

示例响应

{
  "role_starfleet" : {
    "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
    "hosts" : [ "*.starfleetintranet.com" ],
    "users" : [ "worf" ]
  }
}

删除角色映射

1.0 版引入

删除指定的角色映射。

请求

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

示例响应

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

创建角色映射

1.0 版引入

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

请求

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

基于主机的角色映射

hosts 参数将源自特定 IP 地址或主机名的请求映射到给定角色。不支持 CIDR 块，但您可以使用通配符模式（glob），例如 192.168.*.* 或 *.example.com。当您希望根据客户端的源地址分配角色时，这非常有用。

要按 IP 地址匹配（例如，"192.168.1.10"），无需额外配置。
要按主机名匹配（例如，"myserver.example.com"），您必须设置集群级别配置参数。
```
opensearch_security.host_resolver_mode: ip-hostname
```
这启用了反向 DNS 查找来解析主机名。有关更多信息，请参阅配置 OpenSearch。

在 hosts 中使用 "*" 将匹配所有客户端 IP 和主机名，这意味着此角色将应用于每个请求，无论用户是谁。如果与 users: ["someuser"] 一起使用，这可能会无意中过度授权访问。除非您有意将此角色授予所有客户端 IP，否则请避免设置 hosts: ["*"]。

示例响应

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

修补角色映射

1.0 版引入

更新角色映射的单个属性。

请求

PATCH _plugins/_security/api/rolesmapping/<role>
[
  {
    "op": "replace", "path": "/users", "value": ["myuser"]
  },
  {
    "op": "replace", "path": "/backend_roles", "value": ["mybackendrole"]
  }
]

示例响应

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

修补角色映射

1.0 版引入

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

请求

PATCH _plugins/_security/api/rolesmapping
[
  {
    "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."
}

允许列表

获取允许列表

检索当前 allowlist 配置。

请求

GET _plugins/_security/api/allowlist

示例响应

{
  "config" : {
    "enabled" : true,
    "requests" : {
      "/_cat/nodes" : [
        "GET"
      ],
      "/_cat/indices" : [
        "GET"
      ],
      "/_plugins/_security/whoami" : [
        "GET"
      ]
    }
  }
}

创建允许列表

创建 allowlist 配置。

请求

PUT _plugins/_security/api/allowlist
{
  "enabled": true,
  "requests": {
    "/_cat/nodes": ["GET"],
    "/_cat/indices": ["GET"],
    "/_plugins/_security/whoami": ["GET"]
  }
}

示例响应

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

更新允许列表

更新 allowlist 配置。

请求

PATCH _plugins/_security/api/allowlist
[
  {
    "op": "add",
    "path": "/config/requests",
    "value": {
      "/_cat/nodes": ["POST"]
    }
  }
]

示例响应

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

租户

获取租户

1.0 版引入

检索一个租户。

请求

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

示例响应

{
  "human_resources": {
    "reserved": false,
    "hidden": false,
    "description": "A tenant for the human resources team.",
    "static": false
  }
}

获取所有租户

1.0 版引入

检索所有租户。

请求

GET _plugins/_security/api/tenants/

示例响应

{
  "global_tenant": {
    "reserved": true,
    "hidden": false,
    "description": "Global tenant",
    "static": true
  },
  "human_resources": {
    "reserved": false,
    "hidden": false,
    "description": "A tenant for the human resources team.",
    "static": false
  }
}

删除租户

1.0 版引入

删除指定的租户。

请求

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

示例响应

{
  "status":"OK",
  "message":"tenant human_resources deleted."
}

创建租户

1.0 版引入

创建或替换指定的租户。

请求

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

示例响应

{
  "status":"CREATED",
  "message":"tenant human_resources created"
}

修补租户

1.0 版引入

添加、删除或修改单个租户。

请求

PATCH _plugins/_security/api/tenants/<tenant>
[
  {
    "op": "replace", "path": "/description", "value": "An updated description"
  }
]

示例响应

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

修补租户

1.0 版引入

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

请求

PATCH _plugins/_security/api/tenants/
[
  {
    "op": "replace",
    "path": "/human_resources/description",
    "value": "An updated description"
  },
  {
    "op": "add",
    "path": "/another_tenant",
    "value": {
      "description": "Another description."
    }
  }
]

示例响应

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

配置

获取配置

1.0 版引入

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

请求

GET _plugins/_security/api/securityconfig

更新配置

1.0 版引入

使用 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,
    "opensearch-dashboards": {
      "multitenancy_enabled": true,
      "server_username": "kibanaserver",
      "index": ".opensearch-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 的访问控制。

在执行此操作之前，您必须首先将以下行添加到 opensearch.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"
  }
]

示例响应

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

配置升级检查

2.14 版本引入

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

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

请求

GET _plugins/_security/api/_upgrade_check

示例响应

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

响应正文字段

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

配置升级

2.14 版本引入

从最新版本安全插件附带的配置中，添加和更新主机现有安全配置上的资源。

这些捆绑的配置文件可以在 <OPENSEARCH_HOME>/security/config 目录中找到。默认配置文件在 OpenSearch 升级时更新，而集群配置仅由集群操作员更新。此端点帮助集群操作员升级缺失的默认值和过时的默认定义。

请求

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

请求正文字段

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

示例响应

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

响应正文字段

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

专有名称

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

在您可以使用 REST API 配置允许列表之前，您必须首先将以下行添加到 opensearch.yml。

plugins.security.nodes_dn_dynamic_config_enabled: true

获取专有名称

检索允许列表中的所有专有名称。

请求

GET _plugins/_security/api/nodesdn

示例响应

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

要从特定集群或节点的允许列表中获取专有名称，请在请求路径中包含集群的名称。

请求

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

示例响应

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

更新专有名称

在集群或节点的允许列表中添加或更新指定的专有名称。

请求

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

示例响应

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

更新所有专有名称

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

端点

PATCH _plugins/_security/api/nodesdn

请求正文字段

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

请求示例

PATCH _plugins/_security/api/nodesdn
[
   {
      "op":"replace",
      "path":"/cluster1/nodes_dn/0",
      "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":"Resources updated."
}

响应正文字段

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

删除专有名称

删除指定集群或节点的允许列表中的所有专有名称。

请求

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

示例响应

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

证书

获取证书

1.0 版引入

检索集群的安全证书。

请求

GET _plugins/_security/api/ssl/certs

示例响应

{
  "http_certificates_list": [
    {
      "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
      "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
      "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
      "not_before": "2018-04-22T03:43:47Z",
      "not_after": "2028-04-19T03:43:47Z"
    }
  ],
  "transport_certificates_list": [
    {
      "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
      "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
      "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
      "not_before": "2018-04-22T03:43:47Z",
      "not_after": "2028-04-19T03:43:47Z"
    }
  ]
}

重新加载传输证书

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

端点

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

请求示例

curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/transport/reloadcerts"

示例响应

{
  "status": "OK",
  "message": "updated transport certs"
}

响应正文字段

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

重新加载 HTTP 证书

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

端点

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

请求示例

curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/http/reloadcerts"

示例响应

{
  "status": "OK",
  "message": "updated http certs"
}

响应正文字段

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

缓存

刷新缓存

1.0 版引入

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

请求

DELETE _plugins/_security/api/cache

示例响应

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

健康

健康检查

1.0 版引入

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

请求

GET _plugins/_security/health

示例响应

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

审计日志

以下 API 可用于安全插件中的审计日志。

启用审计日志

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

有关使用审计日志跟踪 OpenSearch 集群访问的详细信息，以及有关进一步配置的信息，请参阅审计日志。

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

请求正文字段

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

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

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

请求示例

GET

GET 调用检索审计配置。

GET /_opendistro/_security/api/audit

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
  }
}

PATCH

PATCH 调用用于更新审计配置中的指定字段。PATCH 方法需要操作、路径和值才能完成有效请求。有关使用 PATCH 方法的详细信息，请参阅维基百科中以下 Patching resources 的描述。

使用 PATCH 方法还需要用户具有包含用于加密的管理证书的安全配置。要了解有关这些证书的更多信息，请参阅配置管理证书。

curl -X PATCH -k -i --cert <admin_cert file name> --key <admin_cert_key file name> <domain>/_opendistro/_security/api/audit -H 'Content-Type: application/json' -d'[{"op":"add","path":"/config/enabled","value":"true"}]'

OpenSearch Dashboards 开发工具目前不支持 PATCH 方法。您可以使用 curl、Postman 或其他替代过程来使用此方法更新配置。要关注 Dashboards 中 PATCH 方法支持的 GitHub 问题，请参阅问题 #2343。

示例响应

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

{
  "_readonly" : [
    "/audit/exclude_sensitive_headers",
    "/compliance/internal_config",
    "/compliance/external_config"
  ],
  "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" : [ ],
      "disabled_rest_categories" : [
        "AUTHENTICATED",
        "GRANTED_PRIVILEGES"
      ],
      "disabled_transport_categories" : [
        "AUTHENTICATED",
        "GRANTED_PRIVILEGES"
      ],
      "log_request_body" : true,
      "resolve_indices" : true,
      "resolve_bulk_requests" : true,
      "exclude_sensitive_headers" : true,
      "enable_transport" : true,
      "enable_rest" : true
    }
  }
}

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

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

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

HTTP/1.1 200 OK
content-type: application/json; charset=UTF-8
content-length: 45

API 访问控制
保留和隐藏资源
账户
- 获取账户详情
- 更改密码
操作组
用户
角色
角色映射
允许列表
租户
配置
专有名称
证书
- 获取证书
- 重新加载传输证书
缓存
- 刷新缓存
健康
- 健康检查
审计日志
- 启用审计日志

此页面有帮助吗？

✔ 是 ✖ 否

告诉我们原因

剩余 350 字符

有问题？在 OpenSearch 论坛上提问。

想要贡献？编辑此页面或创建问题。