安全API
edit安全API
edit要使用安全API，您必须在elasticsearch.yml文件中将xpack.security.enabled设置为true。
使用以下API来执行安全活动。
应用程序权限
edit使用以下API来添加、更新、检索和删除应用程序权限：
角色映射
edit使用以下API来添加、删除、更新和检索角色映射：
角色
edit使用以下API在本地领域中添加、删除、更新和检索角色：
令牌
edit使用以下API来创建和使无效的承载令牌，以便在不要求基本身份验证的情况下进行访问：
API 密钥
edit使用以下API来创建和更新通过REST接口访问的API密钥，而无需基本身份验证：
使用以下API来创建和更新用于基于API密钥的远程集群访问的跨集群API密钥：
使用以下API来检索和失效所有类型的API密钥：
用户
edit使用以下API在原生领域中添加、删除、更新或检索用户：
服务账户
edit使用以下API来列出服务账户和管理服务令牌：
OpenID Connect
edit使用以下API在自定义Web应用程序（而非Kibana）中对用户进行OpenID Connect身份验证领域的身份验证
SAML
edit使用以下API在自定义Web应用程序（而非Kibana）中对用户进行SAML身份验证时，针对SAML身份验证领域进行用户认证。
注册
edit使用以下API，使新节点能够加入已启用安全性的现有集群，或使Kibana实例能够配置自身以与安全的Elasticsearch集群通信。
用户资料
edit使用以下API来检索和管理用户资料。
认证 API
edit使您能够提交带有基本认证头的请求，以验证用户并检索有关已验证用户的信息。
请求
editGET /_security/_authenticate
描述
edit成功的调用返回一个JSON结构，显示用户信息，如用户名、分配给用户的角色、任何分配的元数据，以及关于对用户进行身份验证和授权的领域的信息。
响应代码
edit如果用户无法通过身份验证，此API将返回401状态码。
示例
edit要验证用户，请向 /_security/_authenticate 端点提交一个 GET 请求：
GET /_security/_authenticate
以下示例输出提供了关于“rdeniro”用户的信息：
{
"username": "rdeniro",
"roles": [
"admin"
],
"full_name": null,
"email": null,
"metadata": { },
"enabled": true,
"authentication_realm": {
"name" : "file",
"type" : "file"
},
"lookup_realm": {
"name" : "file",
"type" : "file"
},
"authentication_type": "realm"
}
更改密码 API
edit更改本机领域和内置用户的密码。
前提条件
edit-
每个用户都可以更改自己的密码。拥有
manage_security权限的用户可以更改其他用户的密码。
路径参数
edit-
username - (可选，字符串) 你要更改密码的用户。如果你不指定此参数，则更改当前用户的密码。
请求体
edit-
password -
(字符串) 新的密码值。密码必须至少6个字符长。
需要提供
password或password_hash中的一个。 -
password_hash -
(字符串) 新密码值的哈希。这必须使用与配置用于密码存储的相同哈希算法生成。更多详情，请参阅用户缓存和密码哈希算法中关于
xpack.security.authc.password_hashing.algorithm设置的解释。使用此参数允许客户端出于性能和/或保密原因预先哈希密码。
不能在同一请求中使用
password参数和password_hash参数。
示例
edit以下示例更新了jacknich用户的密码：
POST /_security/user/jacknich/_password
{
"password" : "new-test-password"
}
成功的调用返回一个空的JSON结构。
{}
清除缓存 API
edit从用户缓存中驱逐用户。您可以完全清除缓存或驱逐特定用户。
描述
edit用户凭证在每个节点上缓存在内存中，以避免每次传入请求时连接到远程认证服务或访问磁盘。有一些领域设置可以用来配置用户缓存。更多信息，请参见控制用户缓存。
要从角色缓存中驱逐角色，请参阅清除角色缓存 API。 要从权限缓存中驱逐权限，请参阅清除权限缓存 API。 要从 API 密钥缓存中驱逐 API 密钥，请参阅清除 API 密钥缓存 API。
路径参数
edit-
<realms> -
(必需，字符串)
要清除的领域列表，以逗号分隔。要清除所有领域，请使用
*。不支持其他通配符模式。 -
usernames - (可选，列表) 以逗号分隔的用户列表，用于从缓存中清除。 如果您不指定此参数，API将从用户缓存中清除所有用户。
示例
edit例如，要清除由file领域缓存的所有用户：
POST /_security/realm/default_file/_clear_cache
要驱逐选定的用户，请指定usernames参数：
POST /_security/realm/default_file/_clear_cache?usernames=rdeniro,alpacino
要清除多个领域的缓存，请将领域指定为逗号分隔的列表：
POST /_security/realm/default_file,ldap1/_clear_cache
要清除所有领域的缓存，请使用 *。
POST /_security/realm/*/_clear_cache
清除角色缓存 API
edit从本地角色缓存中驱逐角色。
请求
editPOST /_security/role/
前提条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
<roles> -
(必需，字符串)
以逗号分隔的角色列表，用于从角色缓存中驱逐。要驱逐所有角色，请使用
*。不支持其他通配符模式。
示例
edit清除角色缓存 API 从本机角色缓存中删除角色。例如，要清除 my_admin_role 的缓存：
POST /_security/role/my_admin_role/_clear_cache
指定多个角色为一个逗号分隔的列表。
POST /_security/role/my_admin_role,my_test_role/_clear_cache
要清除缓存中的所有角色，请使用 *。
POST /_security/role/*/_clear_cache
清除权限缓存 API
edit从本地应用程序权限缓存中清除权限。 对于权限已更新的应用程序，缓存也会自动清除。
请求
editPOST /_security/privilege/
前提条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
<applications> -
(必需，字符串)
要清除的应用程序的逗号分隔列表。要清除所有应用程序，请使用
*。不支持其他通配符模式。
示例
edit清除权限缓存 API 从本地应用程序权限缓存中删除权限。
例如，要清除 myapp 的缓存：
POST /_security/privilege/myapp/_clear_cache
指定多个应用程序为逗号分隔的列表。
POST /_security/privilege/myapp,my-other-app/_clear_cache
要清除所有应用程序的缓存，请使用 *。
POST /_security/privilege/*/_clear_cache
清除 API 密钥缓存 API
edit从API密钥缓存中驱逐一部分所有条目。 在安全索引状态变化时，缓存也会自动清除。
请求
editPOST /_security/api_key/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
<ids> -
(必需，字符串)
以逗号分隔的 API 密钥 ID 列表，用于从 API 密钥缓存中驱逐。要驱逐所有 API 密钥，请使用
*。不支持其他通配符模式。
示例
edit清除 API 密钥缓存 API 会从 API 密钥缓存中驱逐条目。
例如，要清除 ID 为 yVGMr3QByxdh1MSaicYx 的 API 密钥的条目。
POST /_security/api_key/yVGMr3QByxdh1MSaicYx/_clear_cache
指定多个API密钥为一个逗号分隔的列表。
POST /_security/api_key/yVGMr3QByxdh1MSaicYx,YoiMaqREw0YVpjn40iMg/_clear_cache
要清除API密钥缓存中的所有条目，请使用*。
POST /_security/api_key/*/_clear_cache
清除服务账户令牌缓存 API
edit从 服务账户 令牌缓存中驱逐一部分所有条目。
请求
editPOST /_security/service/{namespace}/{service}/credential/token/{token_name}/_clear_cache
描述
edit存在两个独立的缓存用于服务账户令牌：一个缓存用于由service_tokens文件支持的令牌，另一个用于由.security索引支持的令牌。此API会清除两个缓存中的匹配条目。
由.security索引支持的服务账户令牌缓存在安全索引状态变化时会自动清除。由service_tokens文件支持的令牌缓存在文件变化时会自动清除。
有关更多信息，请参阅服务账户。
路径参数
edit-
namespace - （必需，字符串）命名空间名称。
-
service - (必需，字符串) 服务名称。
-
token_name -
(必需，字符串) 以逗号分隔的令牌名称列表，用于从服务帐户令牌缓存中驱逐。使用通配符 (
*) 驱逐属于服务帐户的所有令牌。不支持其他通配符模式。
示例
edit以下请求清除token1服务账户令牌缓存：
POST /_security/service/elastic/fleet-server/credential/token/token1/_clear_cache
指定多个令牌名称作为逗号分隔的列表：
POST /_security/service/elastic/fleet-server/credential/token/token1,token2/_clear_cache
要清除服务账户令牌缓存中的所有条目，请在令牌名称的位置使用通配符（*）：
POST /_security/service/elastic/fleet-server/credential/token/*/_clear_cache
创建 API 密钥 API
edit创建一个API密钥，以便在不要求基本身份验证的情况下进行访问。
先决条件
edit-
要使用此API，您必须至少拥有
manage_own_api_key集群权限。
如果用于验证此请求的凭证是API密钥，则派生的API密钥不能具有任何权限。如果您指定了权限，API将返回错误。
请参阅role_descriptors下的注释。
描述
editAPI 密钥由 Elasticsearch API 密钥服务创建，该服务默认自动启用。 有关禁用 API 密钥服务的说明，请参阅 API 密钥服务设置。
成功的请求会返回一个包含API密钥、其唯一ID和名称的JSON结构。如果适用，它还会返回API密钥的过期信息，以毫秒为单位。
默认情况下，API 密钥永不过期。您可以在创建 API 密钥时指定过期信息。
请参阅API key service settings以获取与API key服务相关的配置设置。
请求体
edit以下参数可以在POST或PUT请求的正文中指定：
-
name - (必需，字符串) 指定此API密钥的名称。
-
role_descriptors -
(可选, 对象) 此API密钥的角色描述符。此参数是可选的。当未指定或为空数组时，API密钥将具有已认证用户权限的即时快照。如果提供角色描述符，则生成的权限将是API密钥权限和已认证用户权限的交集，从而限制API密钥的访问范围。
由于计算此权限交集的方式，除非派生密钥是在没有任何权限的情况下创建的，否则无法创建另一个API密钥的子API密钥。在这种情况下，您必须显式指定一个没有任何权限的角色描述符。派生的API密钥可用于身份验证；它将没有权限调用Elasticsearch API。
-
applications -
(列表) 应用程序权限条目的列表。
-
application(required) - (字符串) 此条目适用的应用程序名称
-
privileges(required) - (列表) 字符串列表，其中每个元素是应用程序权限或操作的名称。
-
resources(required) - (列表) 权限应用的资源列表。
-
-
cluster - (列表) 集群权限列表。这些权限定义了API密钥能够执行的集群级别操作。
-
global - (对象) 定义全局权限的对象。全局权限是一种请求感知的集群权限。目前，全局权限的支持仅限于应用程序权限的管理。此字段是可选的。
-
indices -
(列表) 一个索引权限条目的列表。
-
field_security - (对象) API密钥具有读访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级别的安全性。
-
names(required) - (列表) 此条目中权限应用的索引列表（或索引名称模式）。
-
privileges(required) - (列表) API密钥在指定索引上的索引级别权限。
-
query - 定义API密钥具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询，才能被API密钥访问。
-
-
metadata -
(对象) 可选的元数据。在
metadata对象中，以_开头的键保留供系统使用。 -
restriction -
(对象) 可选的限制条件，用于指定角色描述符何时可以生效。更多信息，请参阅 角色限制。
-
workflows -
(列表) API 密钥被限制的工作流列表。 有关完整列表，请参见 工作流。
为了使用角色限制，必须使用一个单一角色描述符创建API密钥。
-
-
run_as - (列表) API密钥可以模拟的用户列表。 有关更多信息，请参阅 代表其他用户提交请求。
-
-
expiration - (可选，字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。
-
metadata -
(可选, 对象) 您希望与API密钥关联的任意元数据。
它支持嵌套数据结构。
在
metadata对象中，以_开头的键保留给系统使用。
示例
edit以下示例创建一个API密钥：
POST /_security/api_key
{
"name": "my-api-key",
"expiration": "1d",
"role_descriptors": {
"role-a": {
"cluster": ["all"],
"indices": [
{
"names": ["index-a*"],
"privileges": ["read"]
}
]
},
"role-b": {
"cluster": ["all"],
"indices": [
{
"names": ["index-b*"],
"privileges": ["all"]
}
]
}
},
"metadata": {
"application": "my-application",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
成功的调用返回一个JSON结构，提供API密钥信息。
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"expiration": 1544068612110,
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
|
此 API 密钥的唯一 |
|
|
此API密钥的可选过期时间（以毫秒为单位） |
|
|
生成的 API 密钥 |
|
|
API key 凭证，即 |
要使用生成的 API 密钥，发送一个带有 Authorization 标头的请求，其中包含一个 ApiKey 前缀，后跟 API 密钥凭据（响应中的 encoded 值）。
curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" \ http://localhost:9200/_cluster/health\?pretty
在类Unix系统上，可以使用以下命令创建encoded值：
以下示例创建了一个API密钥，该密钥具有对角色限制的search_application_query工作流的限制，
该限制仅允许调用搜索应用程序搜索API：
POST /_security/api_key
{
"name": "my-restricted-api-key",
"role_descriptors": {
"my-restricted-role-descriptor": {
"indices": [
{
"names": ["my-search-app"],
"privileges": ["read"]
}
],
"restriction": {
"workflows": ["search_application_query"]
}
}
}
}
创建或更新应用程序权限 API
edit添加或更新应用程序权限。
请求体
editbody 是一个 JSON 对象，其中字段的名称是应用程序名称，每个字段的值是一个对象。这个内部对象中的字段是权限的名称，每个值都是一个包含以下字段的 JSON 对象：
-
actions - (字符串数组) 此权限授予的操作名称列表。此字段必须存在且不能为空数组。
-
metadata -
(对象) 可选的元数据。在
metadata对象中，以_开头的键保留供系统使用。
验证
edit- Application names
-
应用程序名称由一个前缀和一个可选的后缀组成，这些名称遵循以下规则：
- 前缀必须以小写ASCII字母开头
- 前缀只能包含ASCII字母或数字
- 前缀必须至少3个字符长
-
如果后缀存在，它必须以
-或_开头 -
后缀不能包含以下任何字符：
\,/,*,?,",<,>,|,,,* - 名称的任何部分都不能包含空白字符。
- Privilege names
-
特权名称必须以小写ASCII字母开头，并且只能包含ASCII字母和数字以及字符
_、-和. - Action names
-
操作名称可以包含任意数量的可打印ASCII字符，并且必须包含以下至少一个字符：
/*,:
响应体
edit成功的调用将返回一个JSON结构，显示权限是否已创建或更新。
示例
edit要添加单个权限，请向 /_security/privilege/ 端点提交 PUT 或 POST 请求。例如：
PUT /_security/privilege
{
"myapp": {
"read": {
"actions": [
"data:read/*" ,
"action:login" ],
"metadata": {
"description": "Read access to myapp"
}
}
}
}
|
这些字符串在“myapp”应用程序中具有重要意义。Elasticsearch 不会对它们赋予任何含义。 |
|
|
这里使用通配符（ |
|
|
元数据对象是可选的。 |
要添加多个权限，请向 /_security/privilege/ 端点提交一个 POST 请求。例如：
PUT /_security/privilege
{
"app01": {
"read": {
"actions": [ "action:login", "data:read/*" ]
},
"write": {
"actions": [ "action:login", "data:write/*" ]
}
},
"app02": {
"all": {
"actions": [ "*" ]
}
}
}
成功的调用将返回一个JSON结构，显示权限是否已创建或更新。
{
"app02": {
"all": {
"created": true
}
},
"app01": {
"read": {
"created": true
},
"write": {
"created": true
}
}
}
创建或更新角色映射 API
edit创建和更新角色映射。
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
描述
edit角色映射定义了每个用户被分配的角色。每个映射都有规则来识别用户，并有一系列角色授予这些用户。
角色映射API通常是管理角色映射的首选方式，而不是使用角色映射文件。创建或更新角色映射API不能更新在角色映射文件中定义的角色映射。
此API不创建角色。相反，它将用户映射到现有角色。 角色可以通过使用创建或更新角色API或角色文件来创建。
有关更多信息，请参阅将用户和组映射到角色。
角色模板
edit角色映射最常见的用途是将用户已知的值映射到一个固定的角色名称。例如，所有在 LDAP 组 cn=admin,dc=example,dc=com 中的用户都应该在 Elasticsearch 中被赋予 superuser 角色。为此目的使用了 roles 字段。
对于更复杂的需求，可以使用 Mustache 模板来动态确定应授予用户的角色名称。为此目的使用了 role_templates 字段。
要成功使用角色模板，必须启用相关的脚本功能。否则，所有尝试使用角色模板创建角色映射的操作都会失败。请参阅允许的脚本类型设置。
在角色映射规则中可用的所有用户字段也可以在角色模板中使用。因此，可以将用户分配到一个反映其用户名、其组或他们进行身份验证的领域名称的角色。
默认情况下，模板会被评估以生成一个字符串，该字符串是应分配给用户的角色的名称。如果模板的format设置为"json"，则模板应生成一个JSON字符串或角色名称的JSON字符串数组。
路径参数
edit-
name - (字符串) 用于标识角色映射的唯一名称。该名称仅作为通过API进行交互的标识符使用；它不会以任何方式影响映射的行为。
请求体
edit以下参数可以在PUT或POST请求的正文中指定，并涉及添加角色映射：
-
enabled -
(必需，布尔值) 当执行角色映射时，将忽略
enabled设置为false的映射。 -
metadata -
(对象) 附加的元数据，用于定义每个用户被分配的角色。在
metadata对象中，以_开头的键是为系统使用保留的。 -
roles -
(字符串列表) 授予符合角色映射规则的用户的角色名称列表。
必须指定
roles或role_templates中的一个。 -
role_templates -
(对象列表) 一个 mustache 模板列表，这些模板将被评估以确定应授予与角色映射规则匹配的用户的角色名称。
这些对象的格式定义如下。
必须指定
roles或role_templates中的一个。 -
rules - (必需，对象) 确定哪些用户应被映射匹配的规则。规则是一个通过使用JSON DSL表达的逻辑条件。 参见 角色映射资源。
示例
edit以下示例将“用户”角色分配给所有用户：
POST /_security/role_mapping/mapping1
{
"roles": [ "user"],
"enabled": true,
"rules": {
"field" : { "username" : "*" }
},
"metadata" : {
"version" : 1
}
}
成功的调用将返回一个JSON结构，显示映射是否已创建或更新。
以下示例将“user”和“admin”角色分配给特定用户：
POST /_security/role_mapping/mapping2
{
"roles": [ "user", "admin" ],
"enabled": true,
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
}
}
以下示例匹配针对特定领域进行身份验证的用户：
POST /_security/role_mapping/mapping3
{
"roles": [ "ldap-user" ],
"enabled": true,
"rules": {
"field" : { "realm.name" : "ldap1" }
}
}
以下示例匹配用户名是 esadmin 或者用户属于 cn=admin,dc=example,dc=com 组的用户：
POST /_security/role_mapping/mapping4
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"any": [
{
"field": {
"username": "esadmin"
}
},
{
"field": {
"groups": "cn=admins,dc=example,dc=com"
}
}
]
}
}
上述示例在您的身份管理系统（如Active Directory或SAML身份提供者）中的组名与Elasticsearch中的角色名没有一一对应关系时非常有用。角色映射是将组名与角色名关联起来的方法。
如果有多个组，可以使用数组语法来表示组字段。 这会匹配任意一个组（而不是所有组）：
POST /_security/role_mapping/mapping4
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"any": [
{
"field": {
"username": "esadmin"
}
},
{
"field": {
"groups": [
"cn=admins,dc=example,dc=com",
"cn=other,dc=example,dc=com"
]
}
}
]
}
}
然而，在极少数情况下，您的用户组名称可能与您的 Elasticsearch 角色名称完全匹配。当您的 SAML 身份提供商包含其自己的“组映射”功能并且可以配置为在用户的 SAML 属性中释放 Elasticsearch 角色名称时，可能会出现这种情况。
在这些情况下，可以使用一个将组名视为角色名的模板。
注意: 这应该仅在你打算为所有提供的组定义角色时进行。将用户映射到大量不必要或未定义的角色是低效的，并且可能对系统性能产生负面影响。如果你只需要映射部分组，那么你应该使用显式映射来完成。
POST /_security/role_mapping/mapping5
{
"role_templates": [
{
"template": { "source": "{{#tojson}}groups{{/tojson}}" },
"format" : "json"
}
],
"rules": {
"field" : { "realm.name" : "saml1" }
},
"enabled": true
}
以下示例匹配特定 LDAP 子树中的用户：
POST /_security/role_mapping/mapping6
{
"roles": [ "example-user" ],
"enabled": true,
"rules": {
"field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
}
}
以下示例匹配特定领域中特定LDAP子树中的用户：
POST /_security/role_mapping/mapping7
{
"roles": [ "ldap-example-user" ],
"enabled": true,
"rules": {
"all": [
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
{ "field" : { "realm.name" : "ldap1" } }
]
}
}
规则可以更复杂并包含通配符匹配。例如，以下映射匹配满足以下所有条件的任何用户：
-
专有名称匹配模式
*,ou=admin,dc=example,dc=com， 或者用户名是es-admin，或者用户名是es-system -
cn=people,dc=example,dc=com组中的用户 -
用户没有
terminated_date
POST /_security/role_mapping/mapping8
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"all": [
{
"any": [
{
"field": {
"dn": "*,ou=admin,dc=example,dc=com"
}
},
{
"field": {
"username": [ "es-admin", "es-system" ]
}
}
]
},
{
"field": {
"groups": "cn=people,dc=example,dc=com"
}
},
{
"except": {
"field": {
"metadata.terminated_date": null
}
}
}
]
}
}
模板角色可以用于自动将每个用户映射到他们自己的自定义角色。角色本身可以通过角色 API或使用自定义角色提供者来定义。
在这个示例中，每个使用“cloud-saml”领域进行身份验证的用户都将自动映射到两个角色——"saml_user"角色和以_user_为前缀的用户名角色。例如，用户nwong将被分配saml_user和_user_nwong角色。
创建或更新角色 API
edit在本地领域中添加和更新角色。
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
name - (字符串) 角色的名称。
请求体
edit以下参数可以在PUT或POST请求的正文中指定，并涉及添加角色：
-
applications -
(列表) 应用程序权限条目的列表。
-
application(必需) - (字符串) 此条目适用的应用程序的名称
-
privileges - (列表) 字符串列表，其中每个元素是应用程序权限或操作的名称。
-
resources - (列表) 权限应用的资源列表。
-
-
cluster - (列表) 集群权限列表。这些权限定义了具有此角色的用户能够执行的集群级别操作。
-
description -
(字符串) 角色的描述。
最大长度为
1000个字符。 -
global - (对象) 定义全局权限的对象。全局权限是一种请求感知的集群权限形式。目前，对全局权限的支持仅限于应用程序权限的管理。此字段是可选的。
-
indices -
(列表) 一个索引权限条目的列表。
-
field_security - (对象) 角色所有者具有读访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级安全。
-
names(必需) - (列表) 权限条目适用的索引列表（或索引名称模式）。
-
privileges(必需) - (列表) 角色所有者在指定索引上的索引级权限。
-
query - 定义角色所有者具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询，才能被角色所有者访问。
-
-
metadata -
(对象) 可选的元数据。在
metadata对象中，以_开头的键保留供系统使用。 -
run_as - (列表) 该角色所有者可以模拟的用户列表。 更多信息，请参阅 代表其他用户提交请求。
-
remote_indices -
(列表) 远程索引权限条目列表。
远程索引对于使用基于API密钥模型的远程集群是有效的。 它们对使用基于证书模型的远程集群没有影响。
-
clusters(必需) - (列表) 权限应用到的集群别名列表。
-
field_security - (对象) 角色所有者具有读访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级安全。
-
names(必需) -
(列表) 远程集群上的索引（或索引名称模式）列表（使用
clusters指定），权限应用到这些索引。 -
privileges(必需) - (列表) 角色所有者在指定索引上的索引级权限。
-
query - 定义角色所有者具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询，才能被角色所有者访问。
-
更多信息，请参阅定义角色。
示例
edit以下示例添加了一个名为 my_admin_role 的角色：
POST /_security/role/my_admin_role
{
"description": "Grants full access to all management features within the cluster.",
"cluster": ["all"],
"indices": [
{
"names": [ "index1", "index2" ],
"privileges": ["all"],
"field_security" : { // optional
"grant" : [ "title", "body" ]
},
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
}
],
"applications": [
{
"application": "myapp",
"privileges": [ "admin", "read" ],
"resources": [ "*" ]
}
],
"run_as": [ "other_user" ], // optional
"metadata" : { // optional
"version" : 1
}
}
成功的调用将返回一个JSON结构，显示角色是否已创建或更新。
以下示例配置了一个可以在JDBC中运行SQL的角色：
POST /_security/role/cli_or_drivers_minimal
{
"cluster": ["cluster:monitor/main"],
"indices": [
{
"names": ["test"],
"privileges": ["read", "indices:admin/get"]
}
]
}
以下示例在远程集群上配置了一个具有远程索引权限的角色：
POST /_security/role/role_with_remote_indices
{
"remote_indices": [
{
"clusters": [ "my_remote" ],
"names": ["logs*"],
"privileges": ["read", "read_cross_cluster", "view_index_metadata"]
}
]
}
|
远程索引权限适用于别名为 |
|
|
在远程集群（ |
|
|
实际授予的 索引权限 对于 |
批量创建或更新角色 API
edit此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。
在原生领域中批量添加和更新角色。
请求
editPOST /_security/role/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
请求体
edit以下参数可以在POST请求的正文中指定，并涉及添加一组角色：
-
roles - (对象) 要添加的角色，作为角色名称到角色映射。
-
<role_name>(required) - (字符串) 角色名称。
-
applications -
(列表) 应用程序权限条目的列表。
-
application(必需) - (字符串) 此条目适用的应用程序的名称。
-
privileges - (列表) 字符串列表，其中每个元素是应用程序权限或操作的名称。
-
resources - (列表) 应用权限的资源列表。
-
-
cluster - (列表) 集群权限列表。这些权限定义了具有此角色的用户能够执行的集群级别操作。
-
global - (对象) 定义全局权限的对象。全局权限是一种请求感知的集群权限形式。目前，对全局权限的支持仅限于应用程序权限的管理。
-
indices -
(列表) 一个索引权限条目的列表。
-
field_security - (对象) 角色所有者具有读访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级安全。
-
names(必需) - (列表) 权限应用到的索引（或索引名称模式）列表。
-
privileges(必需) - (列表) 角色所有者在指定索引上的索引级权限。
-
query - 定义角色所有者具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询，才能被角色所有者访问。
-
-
metadata -
(对象) 可选的元数据。在
metadata对象中，以_开头的键保留供系统使用。 -
run_as - (列表) 该角色所有者可以模拟的用户列表。 更多信息，请参阅 代表其他用户提交请求。
-
remote_indices -
[测试版] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试版功能不受正式发布功能的SLA支持。 (列表) 远程索引权限条目的列表。
远程索引对于使用基于API密钥模型的远程集群是有效的。 它们对使用基于证书模型的远程集群没有影响。
-
clusters(必需) - (列表) 此条目中权限适用的集群别名列表。
-
field_security - (对象) 角色所有者具有读访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级安全。
-
names(必需) -
(列表) 远程集群上的索引（或索引名称模式）列表（使用
clusters指定），此条目中的权限适用。 -
privileges(必需) - (列表) 角色所有者在指定索引上的索引级权限。
-
query - 定义角色所有者具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询，才能被角色所有者访问。
-
更多信息，请参阅定义角色。
示例
edit以下示例添加了名为 my_admin_role 和 my_user_role 的角色：
POST /_security/role
{
"roles": {
"my_admin_role": {
"cluster": [
"all"
],
"indices": [
{
"names": [
"index1",
"index2"
],
"privileges": [
"all"
],
"field_security": {
"grant": [
"title",
"body"
]
},
"query": "{\"match\": {\"title\": \"foo\"}}"
}
],
"applications": [
{
"application": "myapp",
"privileges": [
"admin",
"read"
],
"resources": [
"*"
]
}
],
"run_as": [
"other_user"
],
"metadata": {
"version": 1
}
},
"my_user_role": {
"cluster": [
"all"
],
"indices": [
{
"names": [
"index1"
],
"privileges": [
"read"
],
"field_security": {
"grant": [
"title",
"body"
]
},
"query": "{\"match\": {\"title\": \"foo\"}}"
}
],
"applications": [
{
"application": "myapp",
"privileges": [
"admin",
"read"
],
"resources": [
"*"
]
}
],
"run_as": [
"other_user"
],
"metadata": {
"version": 1
}
}
}
}
成功的调用将返回一个JSON结构，显示角色是否已创建、更新或未发生任何更改。
因为每个角色创建或更新的错误是单独处理的，所以API允许部分成功。
以下查询会为my_admin_role抛出错误，因为权限bad_cluster_privilege不存在，但对于my_user_role则会成功。
POST /_security/role
{
"roles": {
"my_admin_role": {
"cluster": [
"bad_cluster_privilege"
],
"indices": [
{
"names": [
"index1",
"index2"
],
"privileges": ["all"],
"field_security": {
"grant": [
"title",
"body"
]
},
"query": "{\"match\": {\"title\": \"foo\"}}"
}
],
"applications": [
{
"application": "myapp",
"privileges": [
"admin",
"read"
],
"resources": [
"*"
]
}
],
"run_as": [
"other_user"
],
"metadata": {
"version": 1
}
},
"my_user_role": {
"cluster": [
"all"
],
"indices": [
{
"names": [
"index1"
],
"privileges": [
"read"
],
"field_security": {
"grant": [
"title",
"body"
]
},
"query": "{\"match\": {\"title\": \"foo\"}}"
}
],
"applications": [
{
"application": "myapp",
"privileges": [
"admin",
"read"
],
"resources": [
"*"
]
}
],
"run_as": [
"other_user"
],
"metadata": {
"version": 1
}
}
}
}
结果将把errors字段设置为true，并保留my_admin_role更新的错误。
{
"created": [
"my_user_role"
],
"errors": {
"count": 1,
"details": {
"my_admin_role": {
"type": "action_request_validation_exception",
"reason": "Validation Failed: 1: unknown cluster privilege [bad_cluster_privilege]. a privilege must be either one of the predefined cluster privilege names [manage_own_api_key,manage_data_stream_global_retention,monitor_data_stream_global_retention,none,cancel_task,cross_cluster_replication,cross_cluster_search,delegate_pki,grant_api_key,manage_autoscaling,manage_index_templates,manage_logstash_pipelines,manage_oidc,manage_saml,manage_search_application,manage_search_query_rules,manage_search_synonyms,manage_service_account,manage_token,manage_user_profile,monitor_connector,monitor_enrich,monitor_inference,monitor_ml,monitor_rollup,monitor_snapshot,monitor_text_structure,monitor_watcher,post_behavioral_analytics_event,read_ccr,read_connector_secrets,read_fleet_secrets,read_ilm,read_pipeline,read_security,read_slm,transport_client,write_connector_secrets,write_fleet_secrets,create_snapshot,manage_behavioral_analytics,manage_ccr,manage_connector,manage_enrich,manage_ilm,manage_inference,manage_ml,manage_rollup,manage_slm,manage_watcher,monitor_data_frame_transforms,monitor_transform,manage_api_key,manage_ingest_pipelines,manage_pipeline,manage_data_frame_transforms,manage_transform,manage_security,monitor,manage,all] or a pattern over one of the available cluster actions;"
}
}
}
}
批量删除角色 API
edit此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。
在原生领域中批量删除角色。
请求
editDELETE /_security/role/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
示例
edit以下示例删除了一个my_admin_role和my_user_role角色：
DELETE /_security/role
{
"names": ["my_admin_role", "my_user_role"]
}
如果角色成功删除，请求将返回：
{
"deleted": [
"my_admin_role",
"my_user_role"
]
}
如果找不到角色，未找到的角色将归类在 not_found 下：
DELETE /_security/role
{
"names": ["my_admin_role", "not_an_existing_role"]
}
{
"deleted": [
"my_admin_role"
],
"not_found": [
"not_an_existing_role"
]
}
如果请求失败或无效，错误将归类在 errors 下：
DELETE /_security/role
{
"names": ["my_admin_role", "superuser"]
}
{
"deleted": [
"my_admin_role"
],
"errors": {
"count": 1,
"details": {
"superuser": {
"type": "illegal_argument_exception",
"reason": "role [superuser] is reserved and cannot be deleted"
}
}
}
}
创建或更新用户 API
edit在本地领域中添加和更新用户。这些用户通常被称为本地用户。
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
username -
(必需，字符串) 用户的标识符。
用户名必须至少为1个字符，且不超过507个字符。它们可以包含字母数字字符（
a-z、A-Z、0-9）、空格、标点符号以及基本拉丁（ASCII）字符块中的可打印符号。不允许使用前导或尾随空格。
查询参数
edit-
refresh -
(字符串) 可以是
true、false或wait_for之一。 这些值与 索引 API 中的含义相同， 但此 API（Put User）的默认值为true。
请求体
edit以下参数可以在POST或PUT请求的正文中指定：
-
enabled -
(布尔值) 指定用户是否启用。默认值为
true。 -
email - (字符串) 用户的电子邮件。
-
full_name - (字符串) 用户的完整姓名。
-
metadata - (object) 您希望与用户关联的任意元数据。
-
password -
(必需*, 字符串) 用户的密码。密码必须至少6个字符长。
在添加用户时，需要提供
password或password_hash中的一个。 在更新现有用户时，密码是可选的，以便在不修改用户密码的情况下更新用户的其他字段（例如他们的角色）。 -
password_hash -
(字符串) 用户密码的哈希值。这必须使用与配置用于密码存储的相同哈希算法生成。更多详情，请参阅 用户缓存和密码哈希算法中关于
xpack.security.authc.password_hashing.algorithm设置的解释。使用此参数允许客户端出于性能和/或保密原因预先哈希密码。
不能在同一请求中使用
password参数和password_hash参数。 -
roles -
(必需，列表) 用户拥有的一组角色。这些角色决定了用户的访问权限。要创建没有角色的用户，请指定一个空列表：
[]。
示例
edit以下示例创建了一个用户 jacknich：
POST /_security/user/jacknich
{
"password" : "l0ng-r4nd0m-p@ssw0rd",
"roles" : [ "admin", "other_role1" ],
"full_name" : "Jack Nicholson",
"email" : "jacknich@example.com",
"metadata" : {
"intelligence" : 7
}
}
成功的调用将返回一个JSON结构，显示用户是否已被创建或更新。
添加用户后，来自该用户的请求可以进行身份验证。例如：
curl -u jacknich:l0ng-r4nd0m-p@ssw0rd http://localhost:9200/_cluster/health
创建服务账户令牌 API
edit创建一个服务账户令牌，以便在不使用基本身份验证的情况下进行访问。
请求
editPOST /_security/service/
PUT /_security/service/
POST /_security/service/
路径参数
edit-
namespace - （必需，字符串）命名空间名称。
-
service - (必需，字符串) 服务名称。
-
token_name -
(可选, 字符串) 服务账户令牌的名称。如果省略，将生成一个随机名称。
令牌名称必须至少为1个字符，且不超过256个字符。它们可以包含字母数字字符（
a-z、A-Z、0-9）、破折号（-）和下划线（_），但不能以下划线开头。令牌名称在关联的服务帐户上下文中必须是唯一的。它们还必须在其完全限定名称中全局唯一，这些名称由服务帐户主体和令牌名称组成，例如
/ /
示例
edit以下请求创建一个服务账户令牌：
POST /_security/service/elastic/fleet-server/credential/token/token1
响应包括服务账户令牌、其名称及其密钥值：
{
"created": true,
"token": {
"name": "token1",
"value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ"
}
}
要使用服务账户令牌，请在请求中包含生成的令牌值，并使用Authorization: Bearer头：
curl -H "Authorization: Bearer AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" http://localhost:9200/_cluster/health
如果你的节点将 xpack.security.http.ssl.enabled 设置为 true，那么
你必须在请求 URL 中指定 https。
以下请求创建一个具有自动生成令牌名称的服务令牌：
POST /_security/service/elastic/fleet-server/credential/token
响应包括服务账户令牌、其自动生成的名称及其密钥值：
{
"created": true,
"token": {
"name": "Jk5J1HgBuyBK5TpDrdo4",
"value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ"
}
}
委托 PKI 认证 API
edit实现将X509Certificate链交换为Elasticsearch访问令牌。
请求
editPOST /_security/delegate_pki
描述
edit此API实现了将X509Certificate链交换为Elasticsearch访问令牌的功能。根据RFC 5280，证书链通过依次考虑每个已安装的PKI领域的信任配置进行验证，其中delegation.enabled设置为true（默认值为false）。成功信任的客户端证书还需根据相应领域的username_pattern验证主题专有名称。
此API由智能和可信代理（如Kibana）调用，这些代理终止用户的TLS会话，但仍希望通过使用PKI领域来验证用户，就像用户直接连接到Elasticsearch一样。有关更多详细信息，请参阅PKI authentication for clients connecting to Kibana。
目标证书中的主题公钥与相应私钥之间的关联未经过验证。这是TLS认证过程的一部分，并委托给调用此API的代理。代理被信任已执行TLS认证，此API将该认证转换为Elasticsearch访问令牌。
请求体
edit-
x509_certificate_chain -
(必需，字符串列表) X509Certificate 链，表示为一个有序的字符串数组。数组中的每个字符串都是证书的 DER 编码的 base64 编码（RFC4648 第 4 节 - 不是 base64url 编码）。
第一个元素是目标证书，包含请求访问的主体可分辨名称。这可能后面跟随额外的证书；每个后续证书用于证明前一个证书。
响应体
edit-
access_token - (字符串) 与客户端证书的主题区分名相关联的访问令牌。
-
expires_in - (时间单位) 令牌过期的时长（以秒为单位）。
-
type - (字符串) 令牌的类型。
示例
edit以下是一个示例请求：
POST /_security/delegate_pki
{
"x509_certificate_chain": ["MIIDeDCCAmCgAwIBAgIUBzj/nGGKxP2iXawsSquHmQjCJmMwDQYJKoZIhvcNAQELBQAwUzErMCkGA1UEAxMiRWxhc3RpY3NlYXJjaCBUZXN0IEludGVybWVkaWF0ZSBDQTEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMB4XDTIzMDcxODE5MjkwNloXDTQzMDcxMzE5MjkwNlowSjEiMCAGA1UEAxMZRWxhc3RpY3NlYXJjaCBUZXN0IENsaWVudDEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAllHL4pQkkfwAm/oLkxYYO+r950DEy1bjH+4viCHzNADLCTWO+lOZJVlNx7QEzJE3QGMdif9CCBBxQFMapA7oUFCLq84fPSQQu5AnvvbltVD9nwVtCs+9ZGDjMKsz98RhSLMFIkxdxi6HkQ3Lfa4ZSI4lvba4oo+T/GveazBDS+NgmKyq00EOXt3tWi1G9vEVItommzXWfv0agJWzVnLMldwkPqsw0W7zrpyT7FZS4iLbQADGceOW8fiauOGMkscu9zAnDR/SbWl/chYioQOdw6ndFLn1YIFPd37xL0WsdsldTpn0vH3YfzgLMffT/3P6YlwBegWzsx6FnM/93Ecb4wIDAQABo00wSzAJBgNVHRMEAjAAMB0GA1UdDgQWBBQKNRwjW+Ad/FN1Rpoqme/5+jrFWzAfBgNVHSMEGDAWgBRcya0c0x/PaI7MbmJVIylWgLqXNjANBgkqhkiG9w0BAQsFAAOCAQEACZ3PF7Uqu47lplXHP6YlzYL2jL0D28hpj5lGtdha4Muw1m/BjDb0Pu8l0NQ1z3AP6AVcvjNDkQq6Y5jeSz0bwQlealQpYfo7EMXjOidrft1GbqOMFmTBLpLA9SvwYGobSTXWTkJzonqVaTcf80HpMgM2uEhodwTcvz6v1WEfeT/HMjmdIsq4ImrOL9RNrcZG6nWfw0HR3JNOgrbfyEztEI471jHznZ336OEcyX7gQuvHE8tOv5+oD1d7s3Xg1yuFp+Ynh+FfOi3hPCuaHA+7F6fLmzMDLVUBAllugst1C3U+L/paD7tqIa4ka+KNPCbSfwazmJrt4XNiivPR4hwH5g=="]
}
返回以下响应：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"authentication" : {
"username" : "Elasticsearch Test Client",
"roles" : [ ],
"full_name" : null,
"email" : null,
"metadata" : {
"pki_dn" : "O=org, OU=Elasticsearch, CN=Elasticsearch Test Client",
"pki_delegated_by_user" : "test_admin",
"pki_delegated_by_realm" : "file"
},
"enabled" : true,
"authentication_realm" : {
"name" : "pki1",
"type" : "pki"
},
"lookup_realm" : {
"name" : "pki1",
"type" : "pki"
},
"authentication_type" : "realm"
}
}
删除应用程序权限 API
edit移除应用程序权限。
请求
editDELETE /_security/privilege/
路径参数
edit-
application - (必需，字符串) 应用程序的名称。应用程序权限总是与一个应用程序相关联。
-
privilege - (必需, 字符串) 权限的名称。
示例
edit以下示例从 myapp 应用程序中删除了 read 应用程序权限：
DELETE /_security/privilege/myapp/read
如果权限成功删除，请求将返回 {"found": true}。
否则，found 设置为 false。
{
"myapp": {
"read": {
"found" : true
}
}
}
删除角色映射 API
edit移除角色映射。
请求
editDELETE /_security/role_mapping/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
描述
edit角色映射定义了每个用户被分配的角色。更多信息，请参见将用户和组映射到角色。
角色映射API通常是管理角色映射的首选方式，而不是使用角色映射文件。删除角色映射API无法移除在角色映射文件中定义的角色映射。
路径参数
edit-
name - (字符串) 用于标识角色映射的唯一名称。该名称仅作为通过API进行交互的标识符使用；它不会以任何方式影响映射的行为。
示例
edit以下示例删除角色映射：
DELETE /_security/role_mapping/mapping1
如果映射成功删除，请求将返回 {"found": true}。
否则，found 设置为 false。
{
"found" : true
}
删除角色 API
edit移除本机领域中的角色。
请求
editDELETE /_security/role/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
name - (字符串) 角色的名称。
示例
edit以下示例删除了一个my_admin_role角色：
DELETE /_security/role/my_admin_role
如果角色成功删除，请求将返回{"found": true}。
否则，found 设置为 false。
{
"found" : true
}
删除服务账户令牌 API
edit删除指定命名空间中服务的服务帐户令牌。
请求
editDELETE /_security/service/
描述
editAPI 响应指示是否找到并删除了指定的服务帐户令牌，或者未找到该令牌。
路径参数
edit-
namespace - （必需，字符串）命名空间名称。
-
service - (必需，字符串) 服务名称。
-
token_name - （必需，字符串）服务账户令牌的名称。
示例
edit以下请求从elastic/fleet-server服务帐户中删除token1服务帐户令牌：
DELETE /_security/service/elastic/fleet-server/credential/token/token42
如果服务账户令牌成功删除，请求将返回{"found": true}。否则，响应将具有状态码404，并且`found`将被设置为false。
{
"found" : true
}
删除用户 API
edit从本地领域删除用户。
请求
editDELETE /_security/user/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
username - (必需，字符串) 用户的标识符。
示例
edit以下示例删除了用户 jacknich：
DELETE /_security/user/jacknich
如果用户成功删除，请求将返回{"found": true}。
否则，found 将设置为 false。
{
"found" : true
}
禁用用户 API
edit在本地领域中禁用用户。
请求
editPUT /_security/user/
前提条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
username - (必需, 字符串) 用户的标识符。
启用用户API
edit在本地领域启用用户。
请求
editPUT /_security/user/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
路径参数
edit-
username - (必需，字符串) 用户的标识符。
注册 Kibana API
edit使Kibana实例能够配置自身以与安全的Elasticsearch集群进行通信。
此API目前仅供Kibana内部使用。
请求
editGET /_security/enroll/kibana
描述
editKibana 在内部使用此 API 来配置自身，以便与已启用安全功能的 Elasticsearch 集群进行通信。
示例
edit以下示例展示了如何注册一个 Kibana 实例。
GET /_security/enroll/kibana
API返回以下响应：
{
"token" : {
"name" : "enroll-process-token-1629123923000",
"value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ"
},
"http_ca" : "MIIJlAIBAzVoGCSqGSIb3...vsDfsA3UZBAjEPfhubpQysAICAA=",
}
|
用于 |
|
|
用于 |
|
|
用于签署Elasticsearch在HTTP层上用于TLS的节点证书的CA证书。该证书以ASN.1 DER编码的Base64编码字符串形式返回。 |
注册节点 API
edit允许一个新节点加入已启用安全功能的现有集群。
请求
editGET /_security/enroll/node
描述
editenroll node API 的目的是允许一个新节点加入一个已启用了安全性的现有集群。enroll node API 响应包含加入节点启动发现和安全相关设置所需的所有信息，以便其能够成功加入集群。
响应包含密钥和证书材料，允许调用者为集群中所有节点的HTTP层生成有效的签名证书。
示例
editGET /security/enroll/node
API返回的响应如下
{
"http_ca_key" : "MIIJlAIBAzCCCVoGCSqGSIb3DQEHAaCCCUsEgglHMIIJQzCCA98GCSqGSIb3DQ....vsDfsA3UZBAjEPfhubpQysAICCAA=",
"http_ca_cert" : "MIIJlAIBAzCCCVoGCSqGSIb3DQEHAaCCCUsEgglHMIIJQzCCA98GCSqGSIb3DQ....vsDfsA3UZBAjEPfhubpQysAICCAA=",
"transport_ca_cert" : "MIIJlAIBAzCCCVoGCSqGSIb3DQEHAaCCCUsEgglHMIIJQzCCA98GCSqG....vsDfsA3UZBAjEPfhubpQysAICCAA=",
"transport_key" : "MIIEJgIBAzCCA98GCSqGSIb3DQEHAaCCA9AEggPMMIIDyDCCA8QGCSqGSIb3....YuEiOXvqZ6jxuVSQ0CAwGGoA==",
"transport_cert" : "MIIEJgIBAzCCA98GCSqGSIb3DQEHAaCCA9AEggPMMIIDyDCCA8QGCSqGSIb3....YuEiOXvqZ6jxuVSQ0CAwGGoA==",
"nodes_addresses" : [
"192.168.1.2:9300"
]
}
获取API密钥信息API
edit检索一个或多个API密钥的信息。
请求
editGET /_security/api_key
先决条件
edit-
要使用此API，您必须至少拥有
manage_own_api_key或read_security集群权限。-
如果你只有
manage_own_api_key权限，此 API 仅返回你拥有的 API 密钥。使用具有
manage_own_api_key权限的 API 密钥进行身份验证，不允许检索已验证用户的自有密钥。相反，请使用基本凭证对用户进行身份验证。 -
如果你有
read_security、manage_api_key或更高的权限（包括manage_security），此 API 返回所有 API 密钥，无论所有权如何。
-
路径参数
edit以下参数可以在GET请求的查询参数中指定，并涉及检索API密钥：
-
id -
(可选，字符串) API 密钥 ID。此参数不能与任何
name、realm_name或username一起使用。 -
name -
(可选，字符串) API 密钥名称。此参数不能与任何
id、realm_name或username一起使用。它支持带通配符的前缀搜索。 -
realm_name -
(可选，字符串) 认证领域名称。此参数不能与
id或name一起使用，也不能在owner标志设置为true时使用。 -
username -
(可选，字符串) 用户的用户名。此参数不能与
id或name一起使用，也不能在owner标志设置为true时使用。 -
owner - (可选, 布尔值) 一个布尔标志，可用于查询当前经过身份验证的用户拥有的API密钥。默认为false。 当此参数设置为true时，不能指定realm_name或username参数，因为它们被假定为当前经过身份验证的用户。
-
with_limited_by -
(可选, 布尔值) 一个布尔标志，用于返回与API密钥关联的所有者用户的角色描述符的快照。API密钥的实际权限是其分配的角色描述符与所有者用户的角色描述符的交集（实际上受其限制）。API密钥必须具有
manage_api_key或更高权限才能检索任何API密钥（包括其自身）的受限角色描述符。 -
with_profile_uid -
(可选，布尔值) 确定是否也为API密钥所有者用户检索用户配置文件
uid。 如果存在，配置文件uid将在每个API密钥的profile_uid响应字段下返回。 默认为false。 -
active_only -
(可选, 布尔值) 一个布尔标志，用于查询当前处于活动状态的API密钥。
API密钥在查询时如果既未失效也未过期，则被视为活动状态。您可以与其他参数（如
owner或name）一起指定此参数。如果active_only为false，响应将同时包含活动和非活动（已过期或已失效）的密钥。默认为false。
当未指定参数 "id"、"name"、"username" 和 "realm_name"，并且 "owner" 设置为 false 时，如果用户有权限，它将检索所有 API 密钥。如果用户无权检索其他用户的 API 密钥，则会返回错误。
示例
edit如果你如下创建一个API密钥：
POST /_security/api_key
{
"name": "my-api-key",
"role_descriptors": {},
"metadata": {
"application": "myapp"
}
}
成功调用后返回一个JSON结构，提供API密钥信息。例如：
{
"id":"VuaCfGcBCdbkQm-e5aOx",
"name":"my-api-key",
"api_key":"ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
您可以使用以下示例通过ID检索API密钥：
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&with_limited_by=true
成功调用返回一个包含API密钥信息的JSON结构：
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"creation": 1548550550158,
"expiration": 1548551550158,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"realm_type": "native",
"metadata": {
"application": "myapp"
},
"role_descriptors": { },
"limited_by": [
{
"role-power-user": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"*"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
]
}
]
}
|
为此次请求检索到的API密钥列表。 |
|
|
API 密钥的 ID |
|
|
API 密钥的名称 |
|
|
API 密钥的创建时间，以毫秒为单位 |
|
|
API 密钥的可选过期时间，单位为毫秒 |
|
|
API 密钥的失效状态。如果该密钥已被失效，则其值为 |
|
|
创建此API密钥的主体 |
|
|
为创建此API密钥的主体所在的领域名称 |
|
|
API 密钥的元数据 |
|
|
与API密钥关联的所有者用户的权限。 这是在创建和 后续更新时捕获的时间点快照。API密钥的 有效权限是其分配的权限与 所有者用户权限的交集。 |
您可以使用以下示例按名称检索API密钥：
GET /_security/api_key?name=my-api-key
API密钥名称支持通过使用通配符进行前缀搜索：
GET /_security/api_key?name=my-*
以下示例检索 native1 领域中的所有 API 密钥：
GET /_security/api_key?realm_name=native1
以下示例检索用户 myuser 在所有领域中的所有 API 密钥：
GET /_security/api_key?username=myuser
以下示例检索当前经过身份验证的用户拥有的所有 API 密钥：
GET /_security/api_key?owner=true
以下示例在用户有权限的情况下检索所有API密钥：
GET /_security/api_key
以下示例在用户有权限的情况下检索所有活动的API密钥：
GET /_security/api_key?active_only=true
以下创建一个API密钥
POST /_security/api_key
{
"name": "my-api-key-1",
"metadata": {
"application": "my-application"
}
}
以下示例检索由当前经过身份验证的用户拥有的、标识为指定id的API密钥：
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true
最后，以下示例立即检索用户 myuser 在 native1 领域中的所有 API 密钥：
GET /_security/api_key?username=myuser&realm_name=native1
成功的调用将返回一个包含一个或多个API密钥信息的JSON结构。
{
"api_keys": [
{
"id": "0GF5GXsBCXxz2eDxWwFN",
"name": "hadoop_myuser_key",
"creation": 1548550550158,
"expiration": 1548551550158,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"realm_type": "native",
"metadata": {
"application": "myapp"
},
"role_descriptors": {
"role-a": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"index-a"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
},
{
"id": "6wHJmcQpReKBa42EHV5SBw",
"name": "api-key-name-2",
"creation": 1548550550158,
"invalidated": false,
"username": "user-y",
"realm": "realm-2",
"metadata": {},
"role_descriptors": { }
}
]
}
获取应用程序权限 API
edit检索应用程序权限。
先决条件
edit要使用此API，您必须拥有以下任一条件：
-
read_security集群权限（或更高权限，如manage_security或all）；或者 - 所引用应用程序的 “管理应用程序权限” 全局权限
描述
edit要检查用户的应用程序权限，请使用has privileges API。
路径参数
edit-
application - (可选，字符串) 应用程序的名称。应用程序权限总是与一个应用程序相关联。如果你不指定这个参数，API将返回所有应用程序的所有权限信息。
-
privilege - (可选，字符串) 权限的名称。如果您不指定此参数，API 将返回所请求应用程序的所有权限信息。
示例
edit以下示例检索有关app01应用程序的read权限的信息：
GET /_security/privilege/myapp/read
成功的调用返回一个由应用程序名称和权限名称键控的对象。如果权限未定义，请求将返回404状态。
{
"myapp": {
"read": {
"application": "myapp",
"name": "read",
"actions": [
"data:read/*",
"action:login"
],
"metadata": {
"description": "Read access to myapp"
}
}
}
}
要检索应用程序的所有权限，请省略权限名称：
GET /_security/privilege/myapp/
要检索所有特权，请省略应用程序和特权名称：
GET /_security/privilege/
获取内置权限 API
edit检索在此版本的 Elasticsearch 中可用的集群权限和 索引权限列表。
请求
editGET /_security/privilege/_builtin
先决条件
edit-
要使用此API，您必须拥有
read_security集群权限（或更高权限，如manage_security或all）。
响应体
edit响应是一个包含两个字段的对象：
示例
edit以下示例检索所有内置权限的名称：
GET /_security/privilege/_builtin
成功调用返回一个包含“cluster”、“index”和“remote_cluster”字段的对象。
{
"cluster" : [
"all",
"cancel_task",
"create_snapshot",
"cross_cluster_replication",
"cross_cluster_search",
"delegate_pki",
"grant_api_key",
"manage",
"manage_api_key",
"manage_autoscaling",
"manage_behavioral_analytics",
"manage_ccr",
"manage_connector",
"manage_data_frame_transforms",
"manage_data_stream_global_retention",
"manage_enrich",
"manage_ilm",
"manage_index_templates",
"manage_inference",
"manage_ingest_pipelines",
"manage_logstash_pipelines",
"manage_ml",
"manage_oidc",
"manage_own_api_key",
"manage_pipeline",
"manage_rollup",
"manage_saml",
"manage_search_application",
"manage_search_query_rules",
"manage_search_synonyms",
"manage_security",
"manage_service_account",
"manage_slm",
"manage_token",
"manage_transform",
"manage_user_profile",
"manage_watcher",
"monitor",
"monitor_connector",
"monitor_data_frame_transforms",
"monitor_data_stream_global_retention",
"monitor_enrich",
"monitor_inference",
"monitor_ml",
"monitor_rollup",
"monitor_snapshot",
"monitor_text_structure",
"monitor_transform",
"monitor_watcher",
"none",
"post_behavioral_analytics_event",
"read_ccr",
"read_connector_secrets",
"read_fleet_secrets",
"read_ilm",
"read_pipeline",
"read_security",
"read_slm",
"transport_client",
"write_connector_secrets",
"write_fleet_secrets"
],
"index" : [
"all",
"auto_configure",
"create",
"create_doc",
"create_index",
"cross_cluster_replication",
"cross_cluster_replication_internal",
"delete",
"delete_index",
"index",
"maintenance",
"manage",
"manage_data_stream_lifecycle",
"manage_follow_index",
"manage_ilm",
"manage_leader_index",
"monitor",
"none",
"read",
"read_cross_cluster",
"view_index_metadata",
"write"
],
"remote_cluster" : [
"monitor_enrich"
]
}
获取角色映射 API
edit检索角色映射。
先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
描述
edit角色映射定义了每个用户被分配的角色。更多信息，请参见将用户和组映射到角色。
角色映射API通常是管理角色映射的首选方式，而不是使用角色映射文件。 获取角色映射API无法检索在角色映射文件中定义的角色映射。
路径参数
edit-
name - (可选，字符串) 用于标识角色映射的唯一名称。该名称仅用作通过API进行交互的标识符；它不会以任何方式影响映射的行为。您可以指定多个映射名称，以逗号分隔的列表形式。如果您未指定此参数，API将返回有关所有角色映射的信息。
响应代码
edit如果没有与请求名称对应的映射，响应将返回状态码 404。
示例
edit以下示例检索有关 mapping1 角色映射的信息：
GET /_security/role_mapping/mapping1
{
"mapping1": {
"enabled": true,
"roles": [
"user"
],
"rules": {
"field": {
"username": "*"
}
},
"metadata": {}
}
}
获取角色 API
edit检索本机领域中的角色。
先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
路径参数
edit-
name - (可选，字符串) 角色的名称。您可以指定多个角色作为逗号分隔的列表。如果您不指定此参数，API 将返回有关所有角色的信息。
响应体
edit成功调用后返回一个包含角色信息的数组，其中包含角色的JSON表示形式。返回的角色格式是角色定义格式的简单扩展，仅添加了一个额外的字段transient_metadata.enabled。如果角色被自动禁用，例如当许可证级别不允许角色授予的某些权限时，此字段为false。
响应代码
edit如果角色未在原生领域中定义，请求将返回404。
示例
edit以下示例检索有关本机领域中my_admin_role角色的信息：
GET /_security/role/my_admin_role
{
"my_admin_role": {
"description": "Grants full access to all management features within the cluster.",
"cluster" : [ "all" ],
"indices" : [
{
"names" : [ "index1", "index2" ],
"privileges" : [ "all" ],
"allow_restricted_indices" : false,
"field_security" : {
"grant" : [ "title", "body" ]}
}
],
"applications" : [ ],
"run_as" : [ "other_user" ],
"metadata" : {
"version" : 1
},
"transient_metadata": {
"enabled": true
}
}
}
要检索所有角色，请省略角色名称：
GET /_security/role
查询角色 API
edit先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
描述
edit角色管理API通常是管理角色的首选方式，而不是使用基于文件的角色管理。查询角色API不会检索在角色文件中定义的角色，也不会检索内置角色。您可以选择使用查询来过滤结果。此外，结果可以分页和排序。
请求体
edit您可以在请求体中指定以下参数：
-
query -
(可选，字符串) 一个 查询 用于过滤返回的角色。 该查询支持部分查询类型，包括
match_all,bool,term,terms,match,ids,prefix,wildcard,exists,range, 以及simple query string。您可以查询与角色关联的以下值。
Valid values for
query-
name - (keyword) The name of the role.
-
description - (text) The description of the role.
-
metadata -
(flattened) Metadata field associated with the role, such as
metadata.app_tag. Note that metadata is internally indexed as a flattened field type. This means that all sub-fields act likekeywordfields when querying and sorting. It also implies that it is not possible to refer to a subset of metadata fields using wildcard patterns, e.g.metadata.field*, even for query types that support field name patterns. Lastly, all the metadata fields can be searched together when simply mentioning themetadatafield (i.e. not followed by any dot and sub-field name). -
applications -
该角色授予的应用程序权限列表。
-
application - (keyword) The name of the application associated to the privileges and resources.
-
privileges - (keyword) The names of the privileges that the role grants.
-
resources - (keyword) The resources to which the privileges apply.
-
-
-
from -
(可选，整数) 起始文档偏移量。需要是非负数，默认为
0。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
size -
(可选, 整数) 返回的命中数量。必须为非负数，默认为
10。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
sort -
(可选, 对象) 排序定义。你可以按
username、roles或enabled进行排序。 此外，还可以对_doc字段应用排序，以按索引顺序排序。 -
search_after - (可选, 数组) Search after 定义。
响应体
edit此API返回以下顶级字段：
-
total - 找到的角色总数。
-
count - 响应中返回的角色数量。
-
roles -
与查询匹配的角色列表。
返回的角色格式是角色定义格式的扩展。
它添加了
transient_metadata.enabled和_sort字段。transient_metadata.enabled在角色被自动禁用时设置为false， 例如当角色授予的权限不被已安装的许可证允许时。_sort在搜索查询对某些字段进行排序时存在。 它包含用于排序的值的数组。
示例
edit以下请求列出了所有角色，按角色名称排序：
POST /_security/_query/role
{
"sort": ["name"]
}
成功的调用将返回一个包含为一个或多个角色检索到的信息的JSON结构：
{
"total": 2,
"count": 2,
"roles": [
{
"name" : "my_admin_role",
"cluster" : [
"all"
],
"indices" : [
{
"names" : [
"index1",
"index2"
],
"privileges" : [
"all"
],
"field_security" : {
"grant" : [
"title",
"body"
]
},
"allow_restricted_indices" : false
}
],
"applications" : [ ],
"run_as" : [
"other_user"
],
"metadata" : {
"version" : 1
},
"transient_metadata" : {
"enabled" : true
},
"description" : "Grants full access to all management features within the cluster.",
"_sort" : [
"my_admin_role"
]
},
{
"name" : "my_user_role",
"cluster" : [ ],
"indices" : [
{
"names" : [
"index1",
"index2"
],
"privileges" : [
"all"
],
"field_security" : {
"grant" : [
"title",
"body"
]
},
"allow_restricted_indices" : false
}
],
"applications" : [ ],
"run_as" : [ ],
"metadata" : {
"version" : 1
},
"transient_metadata" : {
"enabled" : true
},
"description" : "Grants user access to some indicies.",
"_sort" : [
"my_user_role"
]
}
]
}
同样地，可以使用以下请求来查询仅具有特定描述的用户访问角色：
POST /_security/_query/role
{
"query": {
"match": {
"description": {
"query": "user access"
}
}
},
"size": 1
}
{
"total": 2,
"count": 1,
"roles": [
{
"name" : "my_user_role",
"cluster" : [ ],
"indices" : [
{
"names" : [
"index1",
"index2"
],
"privileges" : [
"all"
],
"field_security" : {
"grant" : [
"title",
"body"
]
},
"allow_restricted_indices" : false
}
],
"applications" : [ ],
"run_as" : [ ],
"metadata" : {
"version" : 1
},
"transient_metadata" : {
"enabled" : true
},
"description" : "Grants user access to some indicies."
}
]
}
获取服务账户 API
edit检索有关服务账户的信息。
目前，仅提供 elastic/fleet-server 服务账户。
描述
edit此API返回与提供的路径参数匹配的服务帐户列表。
路径参数
edit-
namespace -
(可选，字符串) 命名空间的名称。省略此参数以检索所有服务帐户的信息。如果省略此参数，还必须省略
service参数。 -
service -
(可选，字符串) 服务名称的名称。省略此参数以
检索属于指定
namespace的所有服务帐户的信息。
响应体
edit成功的调用将返回一个服务账户的JSON对象。如果未找到服务账户，API将返回一个空对象。
示例
edit以下请求检索elastic/fleet-server服务帐户的服务帐户：
GET /_security/service/elastic/fleet-server
{
"elastic/fleet-server": {
"role_descriptor": {
"cluster": [
"monitor",
"manage_own_api_key",
"read_fleet_secrets",
"cluster:admin/xpack/connector/*"
],
"indices": [
{
"names": [
"logs-*",
"metrics-*",
"traces-*",
".logs-endpoint.diagnostic.collection-*",
".logs-endpoint.action.responses-*",
".logs-endpoint.heartbeat-*"
],
"privileges": [
"write",
"create_index",
"auto_configure"
],
"allow_restricted_indices": false
},
{
"names": [
"profiling-*"
],
"privileges": [
"read",
"write"
],
"allow_restricted_indices": false
},
{
"names": [
"traces-apm.sampled-*"
],
"privileges": [
"read",
"monitor",
"maintenance"
],
"allow_restricted_indices": false
},
{
"names": [
".fleet-secrets*"
],
"privileges": [
"read"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-actions*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-agents*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-artifacts*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-enrollment-api-keys*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-policies*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-policies-leader*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-servers*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
".fleet-fileds*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance"
],
"allow_restricted_indices": true
},
{
"names": [
"synthetics-*"
],
"privileges": [
"read",
"write",
"create_index",
"auto_configure"
],
"allow_restricted_indices": false
},
{
"names": [
".elastic-connectors*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance",
"view_index_metadata"
],
"allow_restricted_indices": false
},
{
"names": [
"content-*",
".search-acl-filter-*"
],
"privileges": [
"read",
"write",
"monitor",
"create_index",
"auto_configure",
"maintenance",
"view_index_metadata"
],
"allow_restricted_indices": false
}
],
"applications": [
{
"application": "kibana-*",
"privileges": [
"reserved_fleet-setup"
],
"resources": [
"*"
]
}
],
"run_as": [],
"metadata": {},
"transient_metadata": {
"enabled": true
}
}
}
}
省略 namespace 和 service 以检索所有服务帐户：
GET /_security/service
获取服务账户凭证API
edit检索某个服务账户的所有服务凭证。
请求
editGET /_security/service/
描述
edit使用此API检索服务帐户的凭据列表。 响应包括通过 创建服务帐户令牌API 创建的服务帐户令牌以及来自集群中所有节点的文件支持的令牌。
对于由 service_tokens 文件支持的令牌，API 从集群的所有节点收集它们。来自不同节点的具有相同名称的令牌被假定为相同的令牌，并且仅在服务令牌总数中计数一次。
路径参数
edit-
namespace - （必需，字符串）命名空间名称。
-
service - (必需，字符串) 服务名称。
示例
edit以下请求使用创建服务账户令牌API在elastic/fleet-server服务账户中创建名为token1的服务账户令牌：
POST /_security/service/elastic/fleet-server/credential/token/token1
以下请求返回elastic/fleet-server服务帐户的所有凭据：
GET /_security/service/elastic/fleet-server/credential
响应包括与指定服务帐户相关的所有凭据：
获取安全索引设置
edit检索安全内部索引的设置。
先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
描述
edit此API允许用户检索安全内部索引（.security 及其相关索引）的用户可配置设置。只会显示索引设置的一个子集——那些用户可配置的设置。这包括：
-
index.auto_expand_replicas -
index.number_of_replicas
获取令牌 API
edit创建一个不需基本身份验证即可访问的承载令牌。
请求
editPOST /_security/oauth2/token
先决条件
edit-
要使用此API，您必须拥有
manage_token集群权限。
描述
edit令牌由 Elasticsearch 令牌服务创建，当您在 HTTP 接口上配置 TLS 时，该服务会自动启用。请参阅 为 Elasticsearch 加密 HTTP 客户端通信。或者，您可以显式启用 xpack.security.authc.token.enabled 设置。当您在生产模式下运行时，引导检查会阻止您启用令牌服务，除非您也在 HTTP 接口上启用 TLS。
获取令牌API与典型的OAuth 2.0令牌API采用相同的参数，除了使用JSON请求体。
成功的获取令牌API调用返回一个JSON结构，其中包含访问令牌、令牌过期的时间（秒）、类型以及可用时的范围。
由 get token API 返回的令牌有一个有限的有效期，超过这个时间后，它们将无法再使用。这个时间周期由 xpack.security.authc.token.timeout 设置定义。更多信息，请参阅 Token service settings。
如果您想立即使一个令牌失效，您可以通过使用使令牌失效API来实现。
请求体
edit以下参数可以在POST请求的正文中指定，并涉及创建令牌：
-
grant_type -
(必需，字符串) 授权的类型。 支持的授权类型有：
password、_kerberos、client_credentials和refresh_token。-
client_credentials -
这种授权类型实现了OAuth2的客户端凭据授予。它适用于机器对机器的通信，不适合或不设计用于自助用户创建令牌。它只生成无法刷新的访问令牌。前提是使用
client_credentials的实体始终可以访问一组（客户端，非最终用户）凭据，并且可以随时进行身份验证。 -
_kerberos -
这种授权类型在内部支持并实现了基于SPNEGO的Kerberos支持。
_kerberos授权类型可能会随版本变化而变化。 -
password - 这种授权类型实现了OAuth2的资源所有者密码凭据授予。在这种授权中，受信任的客户端交换最终用户的凭据以获取访问令牌和（可能）刷新令牌。请求需要由经过身份验证的用户发出，但代表另一个经过身份验证的用户（其凭据作为请求参数传递）。这种授权类型不适合或不设计用于自助用户创建令牌。
-
refresh_token - 这种授权类型实现了OAuth2的刷新令牌授予。在这种授权中，用户交换先前颁发的刷新令牌以获取新的访问令牌和新的刷新令牌。
-
-
password -
(可选*，字符串) 用户的密码。如果您指定
password授权类型，则此参数是必需的。此参数不适用于任何其他支持的授权类型。 -
kerberos_ticket -
(可选*，字符串) 经过base64编码的kerberos票据。如果你指定
_kerberos授权类型，此参数是必需的。此参数不适用于任何其他支持的授权类型。 -
refresh_token -
(可选*，字符串) 创建令牌时返回的字符串，用于延长其有效期。如果指定
refresh_token授权类型，则此参数是必需的。此参数与其他任何支持的授权类型均无效。 -
scope -
(可选，字符串) 令牌的作用域。目前，无论请求中发送的值是什么，令牌的作用域仅为
FULL。 -
username -
(可选*，字符串) 用于标识用户的用户名。如果您指定
password授权类型，则此参数是必需的。此参数不适用于任何其他支持的授权类型。
示例
edit以下示例使用client_credentials授权类型获取令牌，该类型简单地为已认证的用户创建一个令牌：
POST /_security/oauth2/token
{
"grant_type" : "client_credentials"
}
以下示例输出包含访问令牌、令牌过期的时间（以秒为单位）以及类型：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "realm"
}
}
此API返回的令牌可以通过发送带有Authorization标头的请求来使用，该标头的值以“Bearer ”为前缀，后跟access_token的值。
curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
以下示例使用password授权类型为test_admin用户获取令牌。此请求需要由具有足够权限的已认证用户发出，该用户可能与在username参数中传递的用户名相同，也可能不同：
POST /_security/oauth2/token
{
"grant_type" : "password",
"username" : "test_admin",
"password" : "x-pack-test-password"
}
以下示例输出包含访问令牌、令牌过期时间（以秒为单位）、类型和刷新令牌：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"refresh_token": "vLBPvmAB6KvwvJZr27cS",
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "realm"
}
}
要延长使用密码授权类型获得的现有令牌的生命周期，
您可以在令牌创建后的24小时内再次调用API并使用刷新令牌。例如：
POST /_security/oauth2/token
{
"grant_type": "refresh_token",
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
API将返回一个新的令牌和刷新令牌。每个刷新令牌只能使用一次。
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"refresh_token": "vLBPvmAB6KvwvJZr27cS",
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "token"
}
}
以下示例使用kerberos授权类型获取访问令牌和刷新令牌，该类型只需将base64编码的kerberos票据交换为令牌：
POST /_security/oauth2/token
{
"grant_type" : "_kerberos",
"kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
}
如果Kerberos认证成功，API将返回一个新的令牌和刷新令牌。
每个刷新令牌只能使用一次。当在Spnego GSS上下文中请求相互认证时，
服务器将在kerberos_authentication_response_token中返回一个base64编码的令牌，供客户端使用并完成认证。
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
"kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg",
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "realm"
}
}
获取用户权限 API
edit检索已登录用户的安全权限。
请求
editGET /_security/user/_privileges
先决条件
edit- 所有用户都可以使用此API，但仅限于确定自己的权限。要检查其他用户的权限，您必须使用run as功能。有关更多信息，请参阅代表其他用户提交请求。
描述
edit要检查用户是否具有特定的权限列表，请使用has privileges API。
示例
editGET /_security/user/_privileges
{
"cluster" : [
"all"
],
"global" : [ ],
"indices" : [
{
"names" : [
"*"
],
"privileges" : [
"all"
],
"allow_restricted_indices" : true
}
],
"applications" : [
{
"application" : "*",
"privileges" : [
"*"
],
"resources" : [
"*"
]
}
],
"run_as" : [
"*"
]
}
获取用户 API
edit检索本地领域和内置用户的信息。
先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
路径参数
edit-
username - (可选，字符串) 用户的标识符。您可以指定多个用户名作为逗号分隔的列表。如果您省略此参数，API将检索所有用户的信息。
响应体
edit成功调用返回一个包含用户JSON表示的用户数组。请注意，用户密码不包括在内。
响应代码
edit如果用户未在native领域中定义，请求将返回404错误。
示例
edit要检索本地用户，请向 /_security/user/ 端点提交 GET 请求：
GET /_security/user/jacknich
{
"jacknich": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": { "intelligence" : 7 },
"enabled": true
}
}
要检索用户 profile_uid 作为响应的一部分：
GET /_security/user/jacknich?with_profile_uid=true
{
"jacknich": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": { "intelligence" : 7 },
"enabled": true,
"profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
}
}
省略用户名以检索所有用户：
GET /_security/user
授予 API 密钥 API
edit代表另一个用户创建API密钥。
请求
editPOST /_security/api_key/grant
先决条件
edit-
要使用此API，您必须拥有
grant_api_key或manage_api_key集群权限。
描述
edit此API类似于创建API密钥，但它为与运行API的用户不同的用户创建API密钥。
调用者必须拥有为其创建API密钥的用户的身份验证凭据。没有该用户的凭据，无法使用此API创建API密钥。 支持的用户身份验证凭据类型包括： * 用户名和密码 * Elasticsearch访问令牌 * JWTs
为用户提供了身份验证凭据的用户可以选择"作为"（冒充）另一个用户。在这种情况下，API 密钥将代表被冒充的用户创建。
此API旨在供需要为用户创建和管理API密钥的应用程序使用，但不能保证这些用户有权自行创建API密钥（参见先决条件）。API密钥由Elasticsearch API密钥服务创建，该服务会自动启用。
成功的 grant API key API 调用返回一个包含 API 密钥、其唯一 ID 和名称的 JSON 结构。如果适用，它还会以毫秒为单位返回 API 密钥的过期信息。
默认情况下，API 密钥永不过期。您可以在创建 API 密钥时指定过期信息。
请参阅API key service settings以获取与API key服务相关的配置设置。
请求体
edit以下参数可以在POST请求的正文中指定：
-
access_token -
(必填*, 字符串)
用户的 Elasticsearch 访问令牌 或 JWT。支持 访问 和
ID JWT 令牌类型，它们依赖于底层 JWT 领域配置。
创建的 API 密钥将具有使用此令牌进行身份验证的用户的权限的即时快照（甚至更受限制的权限，请参阅
role_descriptors参数）。 如果您指定access_token授权类型，则此参数是必需的。它与其他授权类型无效。 -
api_key -
(必需，对象) 定义 API 密钥。
-
expiration - (可选，字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。
-
name - (必需，字符串) 指定此 API 密钥的名称。
-
role_descriptors - (可选，对象) 此 API 密钥的角色描述符。此参数是可选的。当未指定或为空数组时，API 密钥具有指定用户或访问令牌的权限的即时快照。如果提供角色描述符，则生成的权限是 API 密钥权限与用户或访问令牌权限的交集。角色描述符的结构与 创建 API 密钥 API 的请求相同。
-
metadata -
(可选，对象) 您希望与 API 密钥关联的任意元数据。它支持嵌套数据结构。
在
metadata对象中，以_开头的键保留供系统使用。
-
-
client_authentication -
(可选, 对象) 当使用
access_token授权类型时，并且提供 JWT 时，这指定了需要它的 JWTs 的客户端认证（即通常由ES-Client-Authentication请求头指定的内容）。-
scheme -
(必需, 字符串) 方案（区分大小写），如在
ES-Client-Authentication请求头中提供的。目前，唯一支持的值是SharedSecret。 -
value -
(必需, 字符串) 客户端凭据的值，该值跟随方案，如在
ES-Client-Authentication请求头中提供的。例如，如果请求头是ES-Client-Authentication: SharedSecret myShar3dS3cret，如果客户端直接使用 JWT 进行认证，那么这里的value应该是myShar3dS3cret。
-
-
grant_type -
(必需, 字符串) 授权类型。支持的授权类型有：
access_token,password。-
access_token -
在这种授权类型中，您必须提供一个由Elasticsearch令牌服务创建的访问令牌（参见获取令牌API和为Elasticsearch加密HTTP客户端通信），或者一个JWT（可以是JWT
access_token或JWTid_token）。 -
password - 在这种授权类型中，您必须提供您想要创建API密钥的用户ID和密码。
-
-
password -
(必填*, 字符串)
用户的密码。如果您指定
password授权类型，此参数是必需的。它与其他授权类型不兼容。 -
username -
(必需*, 字符串)
用于标识用户的用户名。如果指定
password授权类型，此参数是必需的。它不适用于其他授权类型。 -
run_as - (可选，字符串) 要模拟的用户名称。
*表示在某些情况下需要设置，但并非所有情况下都需要。
示例
editPOST /_security/api_key/grant
{
"grant_type": "password",
"username" : "test_admin",
"password" : "x-pack-test-password",
"api_key" : {
"name": "my-api-key",
"expiration": "1d",
"role_descriptors": {
"role-a": {
"cluster": ["all"],
"indices": [
{
"names": ["index-a*"],
"privileges": ["read"]
}
]
},
"role-b": {
"cluster": ["all"],
"indices": [
{
"names": ["index-b*"],
"privileges": ["all"]
}
]
}
},
"metadata": {
"application": "my-application",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
}
提供凭据的用户（test_admin）可以“以”另一个用户（test_user）的身份运行。
API 密钥将授予被模拟的用户（test_user）。
拥有权限 API
edit先决条件
edit- 所有用户都可以使用此API，但仅限于确定自己的权限。 要检查其他用户的权限，您必须使用run as功能。有关更多信息，请参阅 代表其他用户提交请求。
请求体
edit-
cluster - (列表) 您要检查的集群权限列表。
-
index -
-
names - (列表) 索引列表。
-
allow_restricted_indices -
(布尔值) 如果使用通配符或正则表达式来覆盖受限索引的模式，则需要将其设置为
true（默认值为false）。隐式地，受限索引不匹配索引模式，因为受限索引通常具有有限的权限，并且将它们包含在模式测试中会使大多数此类测试结果为false。如果受限索引在names列表中被显式包含，则无论allow_restricted_indices的值如何，都会检查它们对应的权限。 -
privileges - (列表) 您希望为指定索引检查的权限列表。
-
-
application -
-
application - (字符串) 应用程序的名称。
-
privileges - (列表) 您想要检查的指定资源的权限列表。可以是应用程序权限名称，或者是这些权限授予的操作名称。
-
resources - (列表) 要检查权限的资源名称列表。
-
示例
edit以下示例检查当前用户是否具有特定的集群、索引和应用程序权限集：
GET /_security/user/_has_privileges
{
"cluster": [ "monitor", "manage" ],
"index" : [
{
"names": [ "suppliers", "products" ],
"privileges": [ "read" ]
},
{
"names": [ "inventory" ],
"privileges" : [ "read", "write" ]
}
],
"application": [
{
"application": "inventory_manager",
"privileges" : [ "read", "data:write/inventory" ],
"resources" : [ "product/1852563" ]
}
]
}
以下示例输出显示了“rdeniro”用户拥有的权限：
{
"username": "rdeniro",
"has_all_requested" : false,
"cluster" : {
"monitor" : true,
"manage" : false
},
"index" : {
"suppliers" : {
"read" : true
},
"products" : {
"read" : true
},
"inventory" : {
"read" : true,
"write" : false
}
},
"application" : {
"inventory_manager" : {
"product/1852563" : {
"read": false,
"data:write/inventory": false
}
}
}
}
使API密钥失效API
edit使一个或多个API密钥失效。
请求
editDELETE /_security/api_key
先决条件
edit-
要使用此API，您必须至少拥有
manage_security、manage_api_key或manage_own_api_key集群权限。manage_security权限允许删除任何API密钥，包括REST和跨集群API密钥。manage_api_key权限允许删除任何REST API密钥，但不包括跨集群API密钥。manage_own_api_key仅允许删除用户拥有的REST API密钥。 此外，使用manage_own_api_key权限时，必须以以下三种格式之一发出失效请求：-
设置参数
owner=true -
或者，设置
username和realm_name以匹配用户的身份。 -
或者，如果请求是由API密钥发出的，即API密钥使自身失效，请在
ids字段中指定其ID。
-
设置参数
描述
edit此API使通过创建API密钥或授予API密钥 API创建的API密钥失效。 失效的API密钥将无法通过身份验证，但仍可以使用 获取API密钥信息和查询API密钥信息API查看， 至少在配置的保留期内，直到它们被自动删除。
请求体
edit以下参数可以在DELETE请求的正文中指定，并涉及使API密钥失效：
-
ids -
(可选，字符串数组) API 密钥 ID 列表。当使用任何
name、realm_name、username时，不能使用此参数 -
name -
(可选，字符串) API 密钥名称。此参数不能与任何
ids、realm_name或username一起使用。 -
realm_name -
(可选，字符串) 认证域的名称。此参数不能与
ids或name一起使用，也不能在owner标志设置为true时使用。 -
username -
(可选，字符串) 用户的用户名。此参数不能与
ids或name一起使用，也不能在owner标志设置为true时使用。 -
owner - (可选, 布尔值) 一个布尔标志，可用于查询当前经过身份验证的用户拥有的API密钥。默认为false。 当此参数设置为true时，不能指定realm_name或username参数，因为它们被假定为当前经过身份验证的用户。
如果 "owner" 是 "false"（默认），则必须指定 "ids"、"name"、"username" 和 "realm_name" 中的至少一个。
响应体
edit成功的调用返回一个JSON结构，其中包含已失效的API密钥的ID、已失效的API密钥的ID，以及在使特定API密钥失效时可能遇到的错误列表。
示例
edit如果你如下创建一个API密钥：
POST /_security/api_key
{
"name": "my-api-key"
}
成功调用后返回一个JSON结构，提供API密钥信息。例如：
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
以下示例立即使由指定ids标识的API密钥失效：
DELETE /_security/api_key
{
"ids" : [ "VuaCfGcBCdbkQm-e5aOx" ]
}
以下示例立即使指定名称标识的API密钥失效：
DELETE /_security/api_key
{
"name" : "my-api-key"
}
以下示例立即使native1领域中的所有API密钥失效：
DELETE /_security/api_key
{
"realm_name" : "native1"
}
以下示例立即使用户 myuser 在所有领域中的所有 API 密钥失效：
DELETE /_security/api_key
{
"username" : "myuser"
}
以下示例会立即使由当前认证用户拥有的、指定ids标识的API密钥失效：
DELETE /_security/api_key
{
"ids" : ["VuaCfGcBCdbkQm-e5aOx"],
"owner" : "true"
}
以下示例会立即使当前经过身份验证的用户拥有的所有 API 密钥失效：
DELETE /_security/api_key
{
"owner" : "true"
}
最后，以下示例立即使用户 myuser 在 native1 领域中的所有 API 密钥失效：
DELETE /_security/api_key
{
"username" : "myuser",
"realm_name" : "native1"
}
{
"invalidated_api_keys": [
"api-key-id-1"
],
"previously_invalidated_api_keys": [
"api-key-id-2",
"api-key-id-3"
],
"error_count": 2,
"error_details": [
{
"type": "exception",
"reason": "error occurred while invalidating api keys",
"caused_by": {
"type": "illegal_argument_exception",
"reason": "invalid api key id"
}
},
{
"type": "exception",
"reason": "error occurred while invalidating api keys",
"caused_by": {
"type": "illegal_argument_exception",
"reason": "invalid api key id"
}
}
]
}
使令牌失效 API
edit使一个或多个访问令牌或刷新令牌失效。
请求
editDELETE /_security/oauth2/token
描述
edit由获取令牌 API返回的访问令牌具有有限的有效期，超过该时间后，它们将无法再使用。该时间周期由xpack.security.authc.token.timeout设置定义。更多信息，请参阅令牌服务设置。
通过获取令牌API返回的刷新令牌仅在24小时内有效。它们也只能使用一次。
如果您想立即使一个或多个访问或刷新令牌失效，请使用此失效令牌API。
请求体
edit以下参数可以在DELETE请求的正文中指定，并涉及令牌的失效：
-
token -
(可选, 字符串) 一个访问令牌。此参数不能与任何
refresh_token,realm_name或username一起使用。 -
refresh_token -
(可选, 字符串) 一个刷新令牌。此参数不能与
refresh_token,realm_name或username一起使用。 -
realm_name -
(可选，字符串) 认证域的名称。此参数不能与
refresh_token或token一起使用。 -
username -
(可选，字符串) 用户的用户名。此参数不能与
refresh_token或token一起使用
虽然所有参数都是可选的，但至少需要其中一个。更具体地说，需要指定token或refresh_token参数中的一个。如果这两个都没有指定，则需要指定realm_name和/或username。
响应体
edit成功的调用返回一个JSON结构，其中包含被作废的令牌数量、已经作废的令牌数量，以及在作废特定令牌时可能遇到的错误列表。
示例
edit例如，如果您使用 client_credentials 授权类型创建令牌，如下所示：
POST /_security/oauth2/token
{
"grant_type" : "client_credentials"
}
获取令牌API返回有关访问令牌的以下信息：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "realm"
}
}
此访问令牌现在可以立即失效，如下例所示：
DELETE /_security/oauth2/token
{
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}
如果你使用密码授权类型为用户获取令牌，响应中可能还会包含一个刷新令牌。例如：
POST /_security/oauth2/token
{
"grant_type" : "password",
"username" : "test_admin",
"password" : "x-pack-test-password"
}
获取令牌API返回以下信息：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"refresh_token": "vLBPvmAB6KvwvJZr27cS",
"authentication" : {
"username" : "test_admin",
"roles" : [
"superuser"
],
"full_name" : null,
"email" : null,
"metadata" : { },
"enabled" : true,
"authentication_realm" : {
"name" : "file",
"type" : "file"
},
"lookup_realm" : {
"name" : "file",
"type" : "file"
},
"authentication_type" : "realm"
}
}
刷新令牌现在也可以立即失效，如下例所示：
DELETE /_security/oauth2/token
{
"refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}
以下示例立即使saml1领域中的所有访问令牌和刷新令牌失效：
DELETE /_security/oauth2/token
{
"realm_name" : "saml1"
}
以下示例立即使所有领域中用户myuser的所有访问令牌和刷新令牌失效：
DELETE /_security/oauth2/token
{
"username" : "myuser"
}
最后，以下示例立即使saml1领域中用户myuser的所有访问令牌和刷新令牌失效：
DELETE /_security/oauth2/token
{
"username" : "myuser",
"realm_name" : "saml1"
}
{
"invalidated_tokens":9,
"previously_invalidated_tokens":15,
"error_count":2,
"error_details":[
{
"type":"exception",
"reason":"Elasticsearch exception [type=exception, reason=foo]",
"caused_by":{
"type":"exception",
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=bar]"
}
},
{
"type":"exception",
"reason":"Elasticsearch exception [type=exception, reason=boo]",
"caused_by":{
"type":"exception",
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=far]"
}
}
]
}
OpenID Connect 准备认证 API
edit根据Elasticsearch中相应OpenID Connect认证域的配置，创建一个oAuth 2.0认证请求作为URL字符串。
请求
editPOST /_security/oidc/prepare
描述
edit此API的响应是一个指向配置的OpenID Connect提供者的授权端点的URL，可用于重定向用户的浏览器以继续身份验证过程。
Elasticsearch 通过 OpenID Connect API 暴露了所有必要的 OpenID Connect 相关功能。这些 API 由 Kibana 内部使用，以提供基于 OpenID Connect 的身份验证，但也可以被其他自定义 Web 应用程序或其他客户端使用。另请参阅 OpenID Connect authenticate API 和 OpenID Connect logout API。
请求体
edit以下参数可以在请求体中指定：
-
realm -
（可选，字符串）Elasticsearch 中 OpenID Connect 领域的名称，其配置应被用于生成身份验证请求。当指定了
iss时，不能指定此项。realm和iss中必须指定其中一个。 -
state - （可选，字符串）用于在身份验证请求和响应之间维护状态的值，通常用作跨站请求伪造的缓解措施。如果 API 的调用者没有提供值，Elasticsearch 将自行生成一个具有足够熵的值，并在响应中返回它。
-
nonce - （可选，字符串）用于将客户端会话与ID令牌关联并减轻重放攻击的值。如果API的调用者未提供值，Elasticsearch将自行生成一个具有足够熵的值，并在响应中返回。
-
iss -
（可选，字符串）在第三方发起的单点登录情况下，这是RP要发送身份验证请求的OP的发行者标识符。
当指定了
realm时，不能指定此项。realm和iss中必须指定一个。 -
login_hint -
（可选，字符串）在第三方发起的单点登录情况下，作为
login_hint参数包含在认证请求中的字符串值。当指定realm时，此参数无效
示例
edit以下示例生成用于 OpenID Connect 领域 oidc1 的身份验证请求：
POST /_security/oidc/prepare
{
"realm" : "oidc1"
}
以下示例输出包含指向OpenID Connect Provider的授权端点的URI，以及所有作为HTTP GET参数的身份验证请求参数：
{
"redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
"state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
"nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
"realm" : "oidc1"
}
以下示例为 OpenID Connect Realm oidc1 生成一个身份验证请求，其中 state 和 nonce 的值由客户端生成：
POST /_security/oidc/prepare
{
"realm" : "oidc1",
"state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
"nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5"
}
以下示例输出包含指向OpenID Connect Provider的授权端点的URI，以及所有作为HTTP GET参数的身份验证请求参数：
{
"redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO&nonce=zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5&client_id=elasticsearch-rp",
"state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
"nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5",
"realm" : "oidc1"
}
以下示例生成一个第三方发起的单点登录的身份验证请求，指定用于匹配适当OpenID Connect身份验证领域的发行者：
POST /_security/oidc/prepare
{
"iss" : "http://127.0.0.1:8080",
"login_hint": "this_is_an_opaque_string"
}
以下示例输出包含指向OpenID Connect Provider的授权端点的URI，以及所有作为HTTP GET参数的身份验证请求参数：
{
"redirect" : "http://127.0.0.1:8080/c2id-login?login_hint=this_is_an_opaque_string&scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
"state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
"nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
"realm" : "oidc1"
}
OpenID Connect 认证 API
edit提交响应以供Elasticsearch消费的oAuth 2.0身份验证请求。验证成功后，Elasticsearch将响应一个Elasticsearch内部访问令牌和刷新令牌，随后可用于身份验证。
请求
editPOST /_security/oidc/authenticate
描述
edit此API端点基本上将成功的OpenID Connect身份验证响应交换为用于身份验证的Elasticsearch访问和刷新令牌。
Elasticsearch 通过 OpenID Connect API 提供了所有必要的 OpenID Connect 相关功能。这些 API 由 Kibana 内部使用，以提供基于 OpenID Connect 的身份验证，但也可以被其他自定义 Web 应用程序或其他客户端使用。另请参阅 OpenID Connect 准备身份验证 API 和 OpenID Connect 登出 API
请求体
edit-
redirect_uri -
（必需，字符串）OpenID Connect Provider在成功认证后，将用户代理重定向到的URL，以响应认证请求。此URL应按原样提供（URL编码），从响应体中获取或作为OpenID Connect Provider响应中的
Location头值。 -
state -
（必需，字符串）用于在身份验证请求和响应之间保持状态。此值需要与之前调用
/_security/oidc/prepare时提供的值相同，或者与 Elasticsearch 生成并包含在该调用响应中的值相同。 -
nonce -
（必需，字符串）用于将客户端会话与ID令牌关联，并缓解重放攻击。此值需要与之前调用
/_security/oidc/prepare时提供的值相同，或者是由Elasticsearch生成并包含在该调用响应中的值。 -
realm - （可选，字符串）用于标识应使用的OpenID Connect领域的名称。当定义了多个领域时，这很有用。
示例
edit以下示例请求将成功认证后从 OpenID Connect Provider 返回的响应交换为 Elasticsearch 访问令牌和刷新令牌，以便在后续请求中使用。此示例来自使用授权代码授予流程的认证。
POST /_security/oidc/authenticate
{
"redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
"state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
"nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
"realm" : "oidc1"
}
以下示例输出包含生成的访问令牌、令牌过期的时间（以秒为单位）、类型以及刷新令牌：
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type" : "Bearer",
"expires_in" : 1200,
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
OpenID Connect 注销 API
edit提交一个请求以使一个刷新令牌和一个访问令牌失效，该访问令牌是在调用 /_security/oidc/authenticate 时生成的响应。
请求
editPOST /_security/oidc/logout
描述
edit如果Elasticsearch中的OpenID Connect认证领域已相应配置， 此调用的响应将包含一个指向OpenID Connect提供者的结束会话端点的URI，以便执行单点注销。
Elasticsearch 通过 OpenID Connect API 暴露了所有必要的 OpenID Connect 相关功能。这些 API 由 Kibana 内部使用，以提供基于 OpenID Connect 的身份验证，但也可以被其他自定义 Web 应用程序或其他客户端使用。另请参阅 OpenID Connect authenticate API 和 OpenID Connect prepare authentication API。
请求体
edit-
access_token - (必需，字符串) 要作为注销一部分而被无效化的访问令牌的值。
-
refresh_token - (可选，字符串) 要作为注销一部分而被无效化的刷新令牌的值。
示例
edit以下示例执行注销
POST /_security/oidc/logout
{
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
以下示例响应的输出包含指向 OpenID Connect Provider 的 End Session Endpoint 的 URI，以及所有作为 HTTP GET 参数的注销请求参数：
{
"redirect" : "https://op-provider.org/logout?id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c&post_logout_redirect_uri=http%3A%2F%2Foidc-kibana.elastic.co%2Floggedout&state=lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO"
}
查询 API 密钥信息 API
edit以查询DSL的方式检索API密钥的信息，并以分页的方式进行。
先决条件
edit-
要使用此API，您必须至少拥有
manage_own_api_key或read_security集群权限。 -
如果您仅拥有
manage_own_api_key权限，此API仅返回您拥有的API密钥。如果您拥有read_security、manage_api_key或更高权限（包括manage_security），此API将返回所有API密钥，无论其所有权如何。
描述
edit使用此API以分页方式检索通过创建API密钥API创建的API密钥。您可以选择使用查询来过滤结果。
路径参数
edit-
with_limited_by -
(可选, 布尔值) 一个布尔标志，用于返回与API密钥关联的所有者用户的角色描述符的快照。API密钥的实际权限是其分配的角色描述符与所有者用户的角色描述符的交集（实际上受其限制）。除非具有
manage_api_key或更高权限，否则API密钥无法检索任何API密钥的受限角色描述符（包括其自身）。 -
with_profile_uid -
(可选，布尔值) 确定是否也为API密钥所有者用户检索用户配置文件
uid。 如果存在，配置文件uid将在每个API密钥的profile_uid响应字段下返回。 默认为false。 -
typed_keys -
(可选，布尔值) 如果为
true，聚合名称在响应中会带有各自类型的前缀。 默认为false。
请求体
edit您可以在请求体中指定以下参数：
-
query -
(可选, 对象) 一个 查询 用于过滤返回哪些 API 密钥。 如果缺少查询参数，则等同于
match_all查询。 该查询支持部分查询类型，包括match_all,bool,term,terms,match,ids,prefix,wildcard,exists,range, 以及simple query string。您可以查询与API密钥关联的以下公共值。
Valid values for
query-
id -
API密钥的ID。注意
id必须使用ids查询进行查询。 -
type -
API密钥可以是类型
rest，如果通过 创建API密钥 或 授予API密钥 API创建，或者是类型cross_cluster如果通过 创建跨集群API密钥 API创建。 -
name - API密钥的名称。
-
creation - API密钥的创建时间，以毫秒为单位。
-
expiration -
API密钥的过期时间，以毫秒为单位。如果密钥未配置为过期，则为
null。 -
invalidated -
指示API密钥是否已失效。如果为
true，则密钥已失效。 默认为false。 -
invalidation - API密钥的失效时间，以毫秒为单位。此字段仅对已失效的API密钥设置。
-
username - API密钥所有者的用户名。
-
realm - API密钥所有者的领域名称。
-
metadata -
与API密钥关联的元数据字段，例如
metadata.my_field。 元数据在内部索引为 扁平化 字段类型。 这意味着所有字段在查询和排序时都像keyword字段一样。 使用通配符模式引用元数据字段的子集是不可能的，例如metadata.field*，即使对于支持字段名称模式的查询类型也是如此。最后，当简单地提到metadata（后面没有任何点和子字段名称）时，可以一起搜索所有元数据字段。
您无法查询API密钥的角色描述符。
-
-
aggsoraggregations -
(可选, 对象) 任何在返回的API密钥语料库上运行的聚合。
聚合和查询一起工作。聚合仅在匹配查询的API密钥上计算。
这仅支持一部分聚合类型，即：词项、
范围、日期范围、
缺失、基数、
值计数、复合、
过滤器和过滤器。
此外，聚合仅在
query所使用的相同字段子集上运行。 -
from -
(可选，整数) 起始文档偏移量。需要是非负数，默认为
0。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
size -
(可选，整数) 返回的命中数。必须不小于零，默认为
10。size参数可以设置为0，在这种情况下不会返回 API 密钥匹配项， 仅返回聚合结果。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
sort -
(可选, 对象) 排序定义。除了
id之外， API 密钥的所有公共字段都适用于排序。此外，排序也可以应用于_doc字段，以按索引顺序排序。 -
search_after - (可选, 数组) Search after 定义。
示例
edit以下请求列出了所有 API 密钥，假设您拥有 manage_api_key 权限：
GET /_security/_query/api_key
成功调用返回一个包含从一个或多个API密钥中检索到的信息的JSON结构：
{
"total": 3,
"count": 3,
"api_keys": [
{
"id": "nkvrGXsB8w290t56q3Rg",
"name": "my-api-key-1",
"creation": 1628227480421,
"expiration": 1629091480421,
"invalidated": false,
"username": "elastic",
"realm": "reserved",
"realm_type": "reserved",
"metadata": {
"letter": "a"
},
"role_descriptors": {
"role-a": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"index-a"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
},
{
"id": "oEvrGXsB8w290t5683TI",
"name": "my-api-key-2",
"creation": 1628227498953,
"expiration": 1628313898953,
"invalidated": false,
"username": "elastic",
"realm": "reserved",
"metadata": {
"letter": "b"
},
"role_descriptors": { }
}
]
}
|
为此次请求检索到的API密钥列表 |
|
|
当此API密钥创建或最后一次更新时分配给它的角色描述符。请注意，API密钥的有效权限是其分配的权限与所有者用户权限的时间点快照的交集。 |
|
|
空的权限描述符意味着API密钥继承所有者用户的权限。 |
如果您使用以下详细信息创建API密钥：
POST /_security/api_key
{
"name": "application-key-1",
"metadata": { "application": "my-application"}
}
成功调用后返回一个JSON结构，提供API密钥信息。例如：
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "application-key-1",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
使用响应中的信息通过ID检索API密钥：
GET /_security/_query/api_key?with_limited_by=true
{
"query": {
"ids": {
"values": [
"VuaCfGcBCdbkQm-e5aOx"
]
}
}
}
成功调用将返回一个包含API密钥信息的JSON结构，包括其受限角色描述符：
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "application-key-1",
"creation": 1548550550158,
"expiration": 1548551550158,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"realm_type": "native",
"metadata": {
"application": "my-application"
},
"role_descriptors": { },
"limited_by": [
{
"role-power-user": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"*"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
]
}
]
}
您也可以通过名称检索API密钥：
GET /_security/_query/api_key
{
"query": {
"term": {
"name": {
"value": "application-key-1"
}
}
}
}
使用 bool 查询来发出复杂的逻辑条件，并使用 from、size、sort 来帮助分页结果：
GET /_security/_query/api_key
{
"query": {
"bool": {
"must": [
{
"prefix": {
"name": "app1-key-"
}
},
{
"term": {
"invalidated": "false"
}
}
],
"must_not": [
{
"term": {
"name": "app1-key-01"
}
}
],
"filter": [
{
"wildcard": {
"username": "org-*-user"
}
},
{
"term": {
"metadata.environment": "production"
}
}
]
}
},
"from": 20,
"size": 10,
"sort": [
{ "creation": { "order": "desc", "format": "date_time" } },
"name"
]
}
|
API 密钥名称必须以 |
|
|
API 密钥必须仍然有效 |
|
|
API 密钥名称不能是 |
|
|
API 密钥必须由符合 通配符 模式 |
|
|
API 密钥必须具有元数据字段 |
|
|
开始搜索结果的偏移量是第20个（基于零的索引）API密钥 |
|
|
响应的页面大小为10个API密钥 |
|
|
结果首先按 |
响应包含一个匹配的 API 密钥列表及其排序值：
{
"total": 100,
"count": 10,
"api_keys": [
{
"id": "CLXgVnsBOGkf8IyjcXU7",
"name": "app1-key-79",
"creation": 1629250154811,
"invalidated": false,
"username": "org-admin-user",
"realm": "native1",
"metadata": {
"environment": "production"
},
"role_descriptors": { },
"_sort": [
"2021-08-18T01:29:14.811Z",
"app1-key-79"
]
},
{
"id": "BrXgVnsBOGkf8IyjbXVB",
"name": "app1-key-78",
"creation": 1629250153794,
"invalidated": false,
"username": "org-admin-user",
"realm": "native1",
"metadata": {
"environment": "production"
},
"role_descriptors": { },
"_sort": [
"2021-08-18T01:29:13.794Z",
"app1-key-78"
]
},
...
]
}
|
第一个排序值是创建时间，以 |
|
|
第二个排序值是API键名称 |
聚合示例
edit例如，给定2个用户“june”和“king”，每个用户拥有3个API密钥：
- 一个永不过期的（对用户“king”无效）
- 一个在10天后过期的
- 还有一个在100天后过期的（对用户“june”无效）
以下请求返回有效（未过期且未失效）的API密钥名称，这些密钥即将在30天内到期，按所有者用户名分组。
请求
editPOST /_security/_query/api_key
{
"size": 0,
"query": {
"bool": {
"must": {
"term": {
"invalidated": false
}
},
"should": [
{
"range": { "expiration": { "gte": "now" } }
},
{
"bool": { "must_not": { "exists": { "field": "expiration" } } }
}
],
"minimum_should_match": 1
}
},
"aggs": {
"keys_by_username": {
"composite": {
"sources": [ { "usernames": { "terms": { "field": "username" } } } ]
},
"aggs": {
"expires_soon": {
"filter": {
"range": { "expiration": { "lte": "now+30d/d" } }
},
"aggs": {
"key_names": { "terms": { "field": "name" } }
}
}
}
}
}
}
响应
edit{
"total" : 4,
"count" : 0,
"api_keys" : [ ],
"aggregations" : {
"keys_by_username" : {
"after_key" : {
"usernames" : "king"
},
"buckets" : [
{
"key" : {
"usernames" : "june"
},
"doc_count" : 2,
"expires_soon" : {
"doc_count" : 1,
"key_names" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 0,
"buckets" : [
{
"key" : "june-key-10",
"doc_count" : 1
}
]
}
}
},
{
"key" : {
"usernames" : "king"
},
"doc_count" : 2,
"expires_soon" : {
"doc_count" : 1,
"key_names" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 0,
"buckets" : [
{
"key" : "king-key-10",
"doc_count" : 1
}
]
}
}
}
]
}
}
}
要检索已失效（但尚未删除）的API密钥，按所有者用户名和API密钥名称分组，请发出以下请求：
请求
editPOST /_security/_query/api_key
{
"size": 0,
"query": {
"bool": {
"filter": {
"term": {
"invalidated": true
}
}
}
},
"aggs": {
"invalidated_keys": {
"composite": {
"sources": [
{ "username": { "terms": { "field": "username" } } },
{ "key_name": { "terms": { "field": "name" } } }
]
}
}
}
}
响应
edit{
"total" : 2,
"count" : 0,
"api_keys" : [ ],
"aggregations" : {
"invalidated_keys" : {
"after_key" : {
"username" : "king",
"key_name" : "king-key-no-expire"
},
"buckets" : [
{
"key" : {
"username" : "june",
"key_name" : "june-key-100"
},
"doc_count" : 1
},
{
"key" : {
"username" : "king",
"key_name" : "king-key-no-expire"
},
"doc_count" : 1
}
]
}
}
}
查询用户 API
edit先决条件
edit-
要使用此API，您必须至少拥有
read_security集群权限。
请求体
edit您可以在请求体中指定以下参数：
-
query -
(可选, 字符串) 一个 查询 用于过滤返回哪些用户。 该查询支持部分查询类型，包括
match_all,bool,term,terms,match,ids,prefix,wildcard,exists,range, 以及simple query string。您可以查询与用户关联的以下公共值。
Valid values for
query-
username - 用户的标识符。
-
roles - 分配给用户的 角色 的角色名称数组。
-
full_name - 用户的完整名称。
-
email - 用户的电子邮件。
-
enabled - 指定用户是否已启用。
-
-
from -
(可选，整数) 起始文档偏移量。需要是非负数，默认为
0。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
size -
(可选, 整数) 返回的命中数量。必须为非负数，默认为
10。默认情况下，您不能使用
from和size参数分页浏览超过10,000条结果。要分页浏览更多结果，请使用search_after参数。 -
sort -
(可选, 对象) 排序定义。你可以按
username、roles或enabled进行排序。 此外，还可以对_doc字段应用排序，以按索引顺序排序。 -
search_after - (可选, 数组) Search after 定义。
示例
edit以下请求列出所有用户，假设您拥有read_security权限：
GET /_security/_query/user
成功的调用返回一个包含从一个或多个用户检索到的信息的JSON结构：
{
"total": 2,
"count": 2,
"users": [
{
"username": "jacknich",
"roles": [
"admin",
"other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true
},
{
"username": "sandrakn",
"roles": [
"admin",
"other_role1"
],
"full_name": "Sandra Knight",
"email": "sandrakn@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true
}
]
}
如果您使用以下详细信息创建用户：
POST /_security/user/jacknich
{
"password" : "l0ng-r4nd0m-p@ssw0rd",
"roles" : [ "admin", "other_role1" ],
"full_name" : "Jack Nicholson",
"email" : "jacknich@example.com",
"metadata" : {
"intelligence" : 7
}
}
成功调用返回一个JSON结构：
{
"created": true
}
使用用户信息通过查询获取用户：
POST /_security/_query/user
{
"query": {
"prefix": {
"roles": "other"
}
}
}
成功调用返回用户的JSON结构：
{
"total": 1,
"count": 1,
"users": [
{
"username": "jacknich",
"roles": [
"admin",
"other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true
}
]
}
要检索用户 profile_uid 作为响应的一部分：
POST /_security/_query/user?with_profile_uid=true
{
"query": {
"prefix": {
"roles": "other"
}
}
}
{
"total": 1,
"count": 1,
"users": [
{
"username": "jacknich",
"roles": [
"admin",
"other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true,
"profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
}
]
}
使用 bool 查询来发出复杂的逻辑条件，并使用 from、size、sort 来帮助分页结果：
POST /_security/_query/user
{
"query": {
"bool": {
"must": [
{
"wildcard": {
"email": "*example.com"
}
},
{
"term": {
"enabled": true
}
}
],
"filter": [
{
"wildcard": {
"roles": "*other*"
}
}
]
}
},
"from": 1,
"size": 2,
"sort": [
{ "username": { "order": "desc"} }
]
}
|
电子邮件必须以 |
|
|
用户必须启用 |
|
|
结果将被过滤，仅包含至少拥有一个包含子字符串 |
|
|
开始搜索结果的偏移量是第2个（基于零的索引）用户 |
|
|
响应的页面大小为2个用户 |
|
|
结果按 |
响应包含一个匹配用户的列表以及他们的排序值：
{
"total": 5,
"count": 2,
"users": [
{
"username": "ray",
"roles": [
"other_role3"
],
"full_name": "Ray Nicholson",
"email": "rayn@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true,
"_sort": [
"ray"
]
},
{
"username": "lorraine",
"roles": [
"other_role3"
],
"full_name": "Lorraine Nicholson",
"email": "lorraine@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true,
"_sort": [
"lorraine"
]
}
]
}
更新 API 密钥 API
edit请求
editPUT /_security/api_key/
先决条件
edit-
要使用此API，您必须至少拥有
manage_own_api_key集群权限。 用户只能更新他们创建或被授予的API密钥。 要更新其他用户的API密钥，请使用run_as功能 代表其他用户提交请求。
无法使用 API 密钥作为此 API 的身份验证凭据。 要更新 API 密钥，需要所有者用户的凭据。
描述
edit使用此API更新由创建API密钥或授予API密钥API创建的API密钥。 如果您需要对许多API密钥应用相同的更新，可以使用批量更新API密钥来减少开销。
无法更新已过期的API密钥，或已被invalidate API Key作废的API密钥。
此API支持对API密钥的访问范围、元数据和过期时间的更新。
API密钥的访问范围由请求中指定的role_descriptors以及请求时所有者用户权限的快照决定。
所有者权限的快照会在每次调用时自动更新。
如果在请求中未指定role_descriptors，调用此API仍可能更改API密钥的访问范围。
如果自API密钥创建或上次修改以来，所有者的权限发生了变化，则可能会发生此更改。
路径参数
edit-
id - (必需, 字符串) 要更新的API密钥的ID。
请求体
edit您可以在请求体中指定以下参数，这是可选的。
-
role_descriptors -
(可选, 对象) 要分配给此API密钥的角色描述符。
API密钥的有效权限是其分配的权限与所有者用户权限的时间点快照的交集。
您可以通过在此参数中指定它们来分配新权限。
要移除已分配的权限，您可以提供一个空的
role_descriptors参数，即空对象{}。 如果API密钥没有分配的权限，它将继承所有者用户的全部权限。 所有者权限的快照始终会更新，无论您是否提供role_descriptors参数。 角色描述符的结构与创建API密钥API的请求相同。 -
metadata -
(可选, 对象) 您希望与 API 密钥关联的任意元数据。
它支持嵌套数据结构。
在
metadata对象中，以_开头的顶级键保留用于系统使用。 指定时，这将完全替换之前与 API 密钥关联的元数据。 -
expiration - (可选, 字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。可以省略以保持不变。
响应体
edit-
updated -
(布尔值) 如果
true，API 密钥已更新。 如果false，API 密钥没有变化，因为没有检测到变化。
示例
edit如果你如下创建一个API密钥：
POST /_security/api_key
{
"name": "my-api-key",
"role_descriptors": {
"role-a": {
"cluster": ["all"],
"indices": [
{
"names": ["index-a*"],
"privileges": ["read"]
}
]
}
},
"metadata": {
"application": "my-application",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
成功调用后返回一个JSON结构，提供API密钥信息。 例如：
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
对于下面的示例，假设所有者用户的权限是：
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
以下示例更新了上面创建的API密钥，为其分配新的角色描述符和元数据：
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
"role_descriptors": {
"role-a": {
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
},
"metadata": {
"environment": {
"level": 2,
"trusted": true,
"tags": ["production"]
}
}
}
成功调用返回一个JSON结构，表明API密钥已更新：
{
"updated": true
}
更新后API密钥的有效权限将是提供的角色描述符与所有者用户权限的交集：
{
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
以下示例移除了API密钥之前分配的权限，使其继承所有者用户的完整权限。
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
"role_descriptors": {}
}
返回的响应如下：
{
"updated": true
}
更新后API密钥的有效权限将与所有者用户的权限相同：
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
对于下一个示例，假设所有者用户的权限已从原始权限更改为：
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
以下请求会自动更新与API密钥关联的用户权限的快照：
PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
返回的响应如下：
{
"updated": true
}
生成的API密钥的以下有效权限：
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
更新安全索引设置
edit更新安全内部指数的设置。
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。
请求体
edit描述
edit此API允许用户修改安全内部索引的设置（.security 及其相关索引）。只有一部分设置允许修改。这包括：
-
index.auto_expand_replicas -
index.number_of_replicas
如果设置了index.auto_expand_replicas，则在更新期间将忽略index.number_of_replicas。
示例
edit修改安全设置的示例：
PUT /_security/settings
{
"security": {
"index.auto_expand_replicas": "0-all"
},
"security-tokens": {
"index.auto_expand_replicas": "0-all"
},
"security-profile": {
"index.auto_expand_replicas": "0-all"
}
}
可以使用获取安全索引设置 API 检索配置的设置。如果系统上未使用某个索引，但为其提供了设置，请求将被拒绝——此 API 尚不支持在这些索引使用之前配置其设置。
批量更新 API 密钥 API
edit请求
editPOST /_security/api_key/_bulk_update
前提条件
edit-
要使用此API，您必须至少拥有
manage_own_api_key集群权限。 用户只能更新他们创建或被授予的API密钥。 要更新其他用户的API密钥，请使用run_as功能 代表其他用户提交请求。
无法使用 API 密钥作为此 API 的身份验证凭据。 要更新 API 密钥，需要所有者用户的凭据。
描述
edit此API类似于更新单个API密钥，但它允许您在一次API调用中对多个API密钥应用相同的更新。 此操作可以大大提高性能，而不是逐个进行更新。
无法更新已过期或失效的 API 密钥。
此API支持对API密钥访问范围、元数据和过期的更新。
每个API密钥的访问范围由您在请求中指定的role_descriptors以及请求时所有者用户权限的快照决定。
所有者权限的快照会在每次调用时自动更新。
如果在请求中未指定role_descriptors，调用此API仍可能更改API密钥的访问范围。
如果自API密钥创建或上次修改以来，所有者的权限发生了变化，则可能会发生此更改。
请求体
edit您可以在请求体中指定以下参数。
-
ids - (必需，列表) 要更新的 API 密钥的 ID。
-
role_descriptors -
(可选, 对象) 要分配给 API 密钥的角色描述符。
API 密钥的有效权限是其分配的权限与所有者用户权限的快照的交集。
您可以通过在此参数中指定它们来分配新权限。
要移除已分配的权限，请将
role_descriptors参数提供为空对象{}。 如果 API 密钥没有分配的权限，它将继承所有者用户的全部权限。 无论是否提供role_descriptors参数，所有者权限的快照始终会更新。 角色描述符的结构与 创建 API 密钥 API 的请求相同。 -
metadata - (可选, 对象) 与API密钥关联的任意嵌套元数据。
在metadata对象中，以下划线（_）开头的顶级键是为系统使用保留的。
使用此参数指定的任何信息将完全替换与API密钥先前关联的元数据。
-
expiration - (可选，字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。可以省略以保持不变。
示例
edit对于下面的示例，假设用户创建了两个API密钥。 用户创建了第一个API密钥：
POST /_security/api_key
{
"name": "my-api-key",
"role_descriptors": {
"role-a": {
"cluster": ["all"],
"indices": [
{
"names": ["index-a*"],
"privileges": ["read"]
}
]
}
},
"metadata": {
"application": "my-application",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
这将返回包含以下 API 密钥信息的响应。
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
用户创建第二个API密钥：
POST /_security/api_key
{
"name": "my-other-api-key",
"metadata": {
"application": "my-application",
"environment": {
"level": 2,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
生成了以下 API 密钥信息。
{
"id": "H3_AhoIBA9hmeQJdg7ij",
"name": "my-other-api-key",
"api_key": "134G4ilmT_uGWXHRfJfXXA",
"encoded": "SDNfQWhvSUJBOWhtZVFKZGc3aWo6MTM0RzRpbG1UX3VHV1hIUmZKZlhYQQ=="
}
此外，假设所有者用户的权限是：
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
以下示例更新了上面创建的API密钥，为其分配新的角色描述符、元数据并更新其过期时间。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {
"role-a": {
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
},
"metadata": {
"environment": {
"level": 2,
"trusted": true,
"tags": ["production"]
}
},
"expiration": "30d"
}
成功调用返回一个JSON结构，表明API密钥已更新：
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
更新后，两个API密钥的有效权限将是提供的角色描述符与所有者用户的权限的交集：
{
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
以下示例移除了API密钥之前分配的权限，使其继承所有者用户的全部权限。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {}
}
返回的响应如下：
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
更新后，API 密钥的有效权限将与所有者用户的权限相同：
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
对于下一个示例，假设所有者用户的权限已从原始权限更改为：
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
以下请求自动更新与两个API密钥关联的用户权限的快照。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
]
}
返回的响应如下：
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
结果导致两个API密钥的以下有效权限：
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
如果任何API密钥更新失败，错误详情将包含在errors字段中。
例如：
{
"updated": ["VuaCfGcBCdbkQm-e5aOx"],
"noops": [],
"errors": {
"count": 3,
"details": {
"g_PqP4IBcBaEQdwM5-WI": {
"type": "resource_not_found_exception",
"reason": "no API key owned by requesting user found for ID [g_PqP4IBcBaEQdwM5-WI]"
},
"OM4cg4IBGgpHBfLerY4B": {
"type": "illegal_argument_exception",
"reason": "cannot update invalidated API key [OM4cg4IBGgpHBfLerY4B]"
},
"Os4gg4IBGgpHBfLe2I7j": {
"type": "exception",
"reason": "bulk request execution failure",
"caused_by": {
"type" : "version_conflict_engine_exception",
"reason" : "[1]: version conflict, required seqNo [1], primary term [1]. current document has seqNo [2] and primary term [1]"
}
}
}
}
}
SAML 准备认证 API
edit创建一个基于 Elasticsearch 中相应 SAML 领域配置的 SAML 身份验证请求（
此API旨在供Kibana以外的自定义Web应用程序使用。 如果您使用的是Kibana，请参阅在Elastic Stack上配置SAML单点登录。
请求
editPOST /_security/saml/prepare
描述
edit此API返回一个指向SAML身份提供者的URL。您可以使用该URL重定向用户的浏览器，以继续身份验证过程。URL包含一个名为SAMLRequest的参数，该参数包含一个经过压缩和Base64编码的SAML身份验证请求。如果配置指示SAML身份验证请求应被签名，则URL有两个额外的参数，分别名为SigAlg和Signature。这些参数包含用于签名的算法和签名值本身。
它还返回一个唯一标识此SAML身份验证请求的随机字符串。此API的调用者需要存储此标识符，因为它需要在身份验证过程的后续步骤中使用（参见SAML authenticate API）。
Elasticsearch 通过 SAML API 提供了所有必要的 SAML 相关功能。 这些 API 由 Kibana 内部使用，以提供基于 SAML 的身份验证，但也可以由其他自定义 Web 应用程序或其他客户端使用。另请参阅 SAML authenticate API、 SAML invalidate API、 SAML logout API 和 SAML complete logout API。
请求体
edit-
acs -
(可选，字符串) 与 Elasticsearch 中 SAML 领域之一的断言消费者服务 URL 匹配。该领域用于生成身份验证请求。
您必须指定此参数或
realm参数。 -
realm -
(可选，字符串) Elasticsearch 中用于生成身份验证请求的 SAML 领域的名称。您必须指定此参数或
acs参数。 -
relay_state -
(可选, 字符串) 一个字符串，将包含在此API返回的重定向URL中，作为
RelayState查询参数。如果身份验证请求已签名，此值将用作签名计算的一部分。
响应体
edit-
id - (字符串) 用于存储由API调用者发出的SAML请求的唯一标识符。
-
realm - (字符串) 用于构建身份验证请求的 Elasticsearch 领域名称。
-
redirect - (字符串) 重定向用户的URL。
示例
edit以下示例为名为 saml1 的 SAML 领域生成一个 SAML 身份验证请求
POST /_security/saml/prepare
{
"realm" : "saml1"
}
以下示例为具有断言消费服务URL匹配`https://kibana.org/api/security/saml/callback`的SAML领域生成一个SAML认证请求。
POST /_security/saml/prepare
{
"acs" : "https://kibana.org/api/security/saml/callback"
}
此API返回以下响应：
{
"redirect": "https://my-idp.org/login?SAMLRequest=fVJdc6IwFP0rmbwDgUKLGbFDtc462%2B06FX3Yl50rBJsKCZsbrPbXL6J22hdfk%2FNx7zl3eL%2BvK7ITBqVWCfVdRolQuS6k2iR0mU2dmN6Phgh1FTQ8be2rehH%2FWoGWdESF%2FPST0NYorgElcgW1QG5zvkh%2FPfHAZbwx2upcV5SkiMLYzmqsFba1MAthdjIXy5enhL5a23DPOyo6W7kGBa7cwhZ2gO7G8OiW%2BR400kORt0bag7fzezAlk24eqcD2OxxlsNN5O3MdsW9c6CZnbq7rntF4d3s0D7BaHTZhIWN52P%2BcjiuGRbDU6cdj%2BEjJbJLQv4N4ADdhxBiEZbQuWclY4Q8iABbCXczCdSiKMAC%2FgyO2YqbQgrIJDZg%2FcFjsMD%2Fzb3gUcBa5sR%2F9oWR%2BzuJBqlPG14Jbn0DIf2TZ3Jn%2FXmSUrC5ddQB6bob37uZrJdeF4dIDHV3iuhb70Ptq83kOz53ubDLXlcwPJK0q%2FT42AqxIaAkVCkqm2tRgr49yfJGFU%2FZQ3hy3QyuUpd7obPv97kb%2FAQ%3D%3D"}",
"realm": "saml1",
"id": "_989a34500a4f5bf0f00d195aa04a7804b4ed42a1"
}
SAML 认证 API
edit向 Elasticsearch 提交一个 SAML Response 消息以供消费。
此API旨在供Kibana以外的自定义Web应用程序使用。 如果您使用的是Kibana，请参阅在Elastic Stack上配置SAML单点登录。
请求
editPOST /_security/saml/authenticate
描述
edit提交的SAML消息可以是：
- 对使用SAML prepare authentication API 创建的SAML身份验证请求的响应。
- 在IdP发起的单点登录（SSO）流程中的非请求SAML消息。
在任何情况下，SAML消息都需要是一个以
成功验证后，Elasticsearch 会返回一个 Elasticsearch 内部访问令牌和刷新令牌，这些令牌可以随后用于身份验证。此 API 端点本质上是用 SAML 响应交换 Elasticsearch 访问和刷新令牌，这些令牌可以用于对 Elasticsearch 进行身份验证。
Elasticsearch 通过 SAML API 暴露了所有必要的 SAML 相关功能。 这些 API 由 Kibana 内部使用，以提供基于 SAML 的身份验证，但也可以由其他自定义 Web 应用程序或其他客户端使用。另请参阅 SAML prepare authentication API、 SAML invalidate API、 SAML logout API 和 SAML complete logout API。
请求体
edit-
content - (必需，字符串) 由用户浏览器发送的SAML响应，通常是一个Base64编码的XML文档。
-
ids - (必需，数组) 包含当前用户所有有效 SAML 请求 ID 的 JSON 数组。
-
realm - (可选，字符串) 应该对 SAML 响应进行身份验证的领域名称。 在定义了多个 SAML 领域的情况下很有用。
响应体
edit-
access_token - (字符串) Elasticsearch 生成的访问令牌。
-
username - (字符串) 已认证用户的名称。
-
expires_in - (整数) 令牌到期前的剩余时间（以秒为单位）。
-
refresh_token - (字符串) Elasticsearch 生成的刷新令牌。
-
realm - (字符串) 用户被认证的域的名称。
示例
edit以下示例交换一个表示在SAML IdP成功认证的SAML响应，以获取一个Elasticsearch访问令牌和刷新令牌，用于后续请求：
POST /_security/saml/authenticate
{
"content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
"ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
}
API返回以下响应：
{
"access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
"username" : "Bearer",
"expires_in" : 1200,
"refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
"realm": "saml1"
}
SAML 注销 API
edit提交请求以使访问令牌和刷新令牌失效。
此API旨在供Kibana以外的自定义Web应用程序使用。 如果您使用的是Kibana，请参阅在Elastic Stack上配置SAML单点登录。
请求
editPOST /_security/saml/logout
描述
edit此API使通过SAML authenticate API为用户生成的令牌失效。
如果Elasticsearch中的SAML领域配置得当，并且SAML身份提供者支持此功能，Elasticsearch的响应将包含一个URL，用于将用户重定向到包含SAML注销请求的身份提供者（启动SP发起的SAML单点注销）。
Elasticsearch 通过 SAML API 暴露了所有必要的 SAML 相关功能。 这些 API 由 Kibana 内部使用，以提供基于 SAML 的身份验证，但也可以由其他自定义 Web 应用程序或其他客户端使用。另请参阅 SAML authenticate API、 SAML prepare authentication API、 SAML invalidate API 和 SAML complete logout API。
请求体
edit-
token -
(必需，字符串) 作为调用
SAML authenticate API 响应返回的访问令牌。或者，通过使用
refresh_token刷新原始令牌后收到的最新令牌。 -
refresh_token - (可选, 字符串) 作为调用 SAML authenticate API响应返回的刷新令牌。或者，是在刷新原始访问令牌后收到的最新刷新令牌。
响应体
edit-
redirect - (字符串) 一个包含SAML注销请求作为参数的URL。用户可以使用此URL重定向回SAML身份提供者并启动单点注销。
示例
edit以下示例使通过调用SAML authenticate API 生成的成功SAML响应的一对令牌失效：
POST /_security/saml/logout
{
"token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
"refresh_token" : "mJdXLtmvTUSpoLwMvdBt_w"
}
API返回以下响应：
{
"redirect" : "https://my-idp.org/logout/SAMLRequest=...."
}
SAML 失效 API
edit向 Elasticsearch 提交一个 SAML LogoutRequest 消息以供消费。
此API旨在供Kibana以外的自定义Web应用程序使用。 如果您使用的是Kibana，请参阅在Elastic Stack上配置SAML单点登录。
请求
editPOST /_security/saml/invalidate
描述
edit注销请求来自SAML IdP，在IdP发起的单点注销过程中。
自定义Web应用程序可以使用此API让Elasticsearch处理LogoutRequest。
在成功验证请求后，Elasticsearch会使与该特定SAML主体对应的访问令牌和刷新令牌失效，并提供一个包含SAML LogoutResponse消息的URL，以便用户可以重定向回其IdP。
Elasticsearch 通过 SAML API 暴露了所有必要的 SAML 相关功能。 这些 API 由 Kibana 内部使用，以提供基于 SAML 的身份验证，但也可以由其他自定义 Web 应用程序或其他客户端使用。另请参阅 SAML authenticate API、 SAML prepare authentication API、 SAML logout API 和 SAML complete logout API。
请求体
edit-
acs -
(可选，字符串) 与Elasticsearch中SAML领域之一的断言消费者服务URL匹配的URL。您必须指定此参数或
realm参数。 -
query_string -
（必需，字符串）用户被SAML IdP重定向以启动单点注销的URL的查询部分。此查询应包含一个名为
SAMLRequest的参数，该参数包含一个被压缩和Base64编码的SAML注销请求。如果SAML IdP已签署注销请求，URL应包含两个额外的参数，名为SigAlg和Signature，分别包含用于签名的算法和签名值本身。 为了使Elasticsearch能够验证IdP的签名，query_string字段的值必须与浏览器提供的字符串完全匹配。客户端应用程序不得尝试以任何方式解析或处理该字符串。 -
queryString -
[7.14.0]
在7.14.0中已弃用。请改用query_string
请参阅
query_string。 -
realm -
(可选, 字符串) Elasticsearch 中 SAML 领域的名称。您必须指定此参数或
acs参数。
响应体
edit-
invalidated - (整数) 作为此注销的一部分被无效化的令牌数量。
-
realm - (字符串) Elasticsearch 中对用户进行身份验证的 SAML 领域的领域名称。
-
redirect - (字符串) 一个作为参数的SAML注销响应，以便用户可以被重定向回SAML身份提供者。
示例
edit以下示例使与用户相关的领域 saml1 的所有令牌失效，该用户在 SAML 注销请求中被标识：
POST /_security/saml/invalidate
{
"query_string" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
"realm" : "saml1"
}
{
"redirect" : "https://my-idp.org/logout/SAMLResponse=....",
"invalidated" : 2,
"realm" : "saml1"
}
SAML 完全注销 API
edit验证从SAML身份提供者发送的注销响应。
此API旨在供Kibana以外的自定义Web应用程序使用。 如果您使用的是Kibana，请参阅在Elastic Stack上配置SAML单点登录。
请求
editPOST /_security/saml/complete_logout
描述
editSAML IdP 在处理完 SP 发起的 SAML 单点注销 后，可能会向 SP 发送一个注销响应。此 API 通过确保内容相关并验证其签名来验证响应。如果验证过程成功，则返回空响应。IdP 可以通过 HTTP-Redirect 或 HTTP-Post 绑定发送响应。调用此 API 的调用者必须相应地准备请求，以便此 API 可以处理其中任何一种方式。
Elasticsearch 通过 SAML API 提供了所有必要的 SAML 相关功能。 这些 API 由 Kibana 内部使用，以提供基于 SAML 的身份验证，但也可以由其他自定义 Web 应用程序或其他客户端使用。另请参阅 SAML authenticate API、 SAML prepare authentication API、 SAML invalidate API 和 SAML logout API。
请求体
edit-
realm - (必需，字符串) 用于验证注销响应的 Elasticsearch 中 SAML 领域的名称。
-
ids - (必需，数组) 包含当前用户所有有效 SAML 请求 ID 的 JSON 数组。
-
query_string - (可选, 字符串) 如果 SAML IdP 使用 HTTP-Redirect 绑定发送注销响应，此字段必须设置为重定向 URI 的查询字符串。
-
queryString -
[7.14.0]
在7.14.0中已弃用。请改用query_string
参见
query_string -
content -
(可选，字符串) 如果 SAML IdP 使用 HTTP-Post 绑定发送注销响应，此字段必须设置为注销响应中
SAMLResponse表单参数的值。
示例
edit以下示例验证通过HTTP-Redirect绑定发送的SAML IdP的注销响应：
POST /_security/saml/complete_logout
{
"realm": "saml1",
"ids": [ "_1c368075e0b3..." ],
"query_string": "SAMLResponse=fZHLasMwEEVbfb1bf...&SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa-sha1&Signature=CuCmFn%2BLqnaZGZJqK..."
}
如果注销响应是通过HTTP-Post绑定发送的，可以按如下方式进行验证：
POST /_security/saml/complete_logout
{
"realm": "saml1",
"ids": [ "_1c368075e0b3..." ],
"content": "PHNhbWxwOkxvZ291dFJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..."
}
API在成功时返回一个空响应。
SAML服务提供者元数据API
edit生成SAML 2.0服务提供商的SAML元数据。
请求
editGET /_security/saml/metadata/
描述
editSAML 2.0 规范提供了一种机制，使服务提供商能够使用元数据文件描述其功能和配置。此 API 根据 Elasticsearch 中 SAML 领域的配置生成服务提供商元数据。
路径参数
edit-
<realm_name> - (必需，字符串) Elasticsearch 中 SAML 领域的名称。
响应体
edit-
metadata - (字符串) 包含领域SAML服务提供商元数据的XML字符串。
示例
edit以下示例为 SAML 领域 saml1 生成服务提供商元数据：
GET /_security/saml/metadata/saml1
API返回包含SAML元数据的XML字符串的响应：
{
"metadata" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://kibana.org\"><md:SPSSODescriptor AuthnRequestsSigned=\"false\" WantAssertionsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://kibana.org/logout\"/><md:AssertionConsumerService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://kibana.org/api/security/saml/callback\" index=\"1\" isDefault=\"true\"/></md:SPSSODescriptor></md:EntityDescriptor>"
}
SSL证书API
editThe certificates API 使您能够检索有关用于加密 Elasticsearch 集群中通信的 X.509 证书的信息。
请求
editGET /_ssl/certificates
描述
edit有关证书如何与传输层安全（TLS）一起配置的更多信息，请参阅 使用 TLS 加密节点间通信。
API返回一个包含所有TLS上下文中证书的列表，包括：
- 传输和HTTP接口的设置
- 在认证领域内使用的TLS设置
- 远程监控导出器的TLS设置
该列表包括用于配置信任的证书，例如在 xpack.security.transport.ssl.truststore 和 xpack.security.transport.ssl.certificate_authorities 设置中配置的证书。它还包括用于配置服务器身份的证书，例如 xpack.security.http.ssl.keystore 和 xpack.security.http.ssl.certificate 设置。
该列表不包括从Java运行时环境（JRE）默认SSL上下文中获取的证书，即使这些证书在Elasticsearch中正在使用。
当一个PKCS#11令牌被配置为JRE的信任库时，API将返回所有包含在PKCS#11令牌中的证书，无论这些证书是否在Elasticsearch TLS配置中使用。
如果 Elasticsearch 配置为使用密钥库或信任库，API 输出将包含该库中的所有证书，即使其中一些证书可能不在集群中处于活动使用状态。
响应体
edit响应是一个对象数组，每个对象代表一个单独的证书。每个对象中的字段包括：
-
path -
(字符串) 证书的路径，如在
elasticsearch.yml文件中配置的那样。 -
format -
(字符串) 文件的格式。可以是以下之一：
jks,PKCS12,PEM。 -
alias - (字符串) 如果路径指向一个容器文件（如jks密钥库或PKCS#12文件），则为证书的别名。否则，为null。
-
subject_dn - (字符串) 证书主题的专有名称。
-
serial_number - (字符串) 证书序列号的十六进制表示。
-
has_private_key - (布尔值) 指示 Elasticsearch 是否可以访问此证书的私钥。
-
expiry - (字符串) 证书的到期日期（not-after日期）的ISO格式日期。
-
issuer - (字符串) 证书颁发者的可分辨名称。
示例
edit以下示例提供了有关 Elasticsearch 单个节点上证书的信息：
GET /_ssl/certificates
API返回以下结果：
[
{
"path": "certs/elastic-certificates.p12",
"format": "PKCS12",
"alias": "instance",
"subject_dn": "CN=Elastic Certificate Tool Autogenerated CA",
"serial_number": "a20f0ee901e8f69dc633ff633e5cd5437cdb4137",
"has_private_key": false,
"expiry": "2021-01-15T20:42:49.000Z"
},
{
"path": "certs/elastic-certificates.p12",
"format": "PKCS12",
"alias": "ca",
"subject_dn": "CN=Elastic Certificate Tool Autogenerated CA",
"serial_number": "a20f0ee901e8f69dc633ff633e5cd5437cdb4137",
"has_private_key": false,
"expiry": "2021-01-15T20:42:49.000Z"
},
{
"path": "certs/elastic-certificates.p12",
"format": "PKCS12",
"alias": "instance",
"subject_dn": "CN=instance",
"serial_number": "fc1905e1494dc5230218d079c47a617088f84ce0",
"has_private_key": true,
"expiry": "2021-01-15T20:44:32.000Z"
}
]
激活用户配置文件 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
代表另一个用户创建或更新用户配置文件。
请求
editPOST /_security/profile/_activate
先决条件
edit-
要使用此API，您必须拥有
manage_user_profile集群权限。
描述
edit激活用户配置文件 API 创建或更新一个配置文件文档，该文档包含从用户的认证对象中提取的信息，包括 username、full_name、roles 以及认证领域。例如，在 JWT access_token 的情况下，配置文件用户的 username 是从 JWT 令牌声明中提取的，该声明由认证该令牌的 JWT 领域的 claims.principal 设置所指向。
当更新个人资料文档时，API会启用该文档（如果它之前被禁用）。任何更新都不会改变labels或data字段的现有内容。
此API仅供需要为最终用户创建或更新配置文件的应用程序（如Kibana）使用。
调用应用程序必须拥有一个access_token，或者为用户的目标配置文件文档提供username和password的组合。
请求体
edit-
access_token -
(必填*, 字符串)
用户的 Elasticsearch 访问令牌 或 JWT。支持 访问 和
ID JWT 令牌类型，它们依赖于底层 JWT 领域配置。
如果您指定
access_token授权类型，则此参数是必需的。它与其他授权类型不兼容。 -
client_authentication -
(可选, 对象) 当使用
access_token授权类型时，并且提供 JWT 时，这指定了需要它的 JWTs 的客户端认证（即通常由ES-Client-Authentication请求头指定的内容）。-
scheme -
(必需, 字符串) 方案（区分大小写），如在
ES-Client-Authentication请求头中提供的。目前，唯一支持的值是SharedSecret。 -
value -
(必需, 字符串) 客户端凭据的值，该值跟随方案，如在
ES-Client-Authentication请求头中提供的。例如，如果请求头是ES-Client-Authentication: SharedSecret myShar3dS3cret，如果客户端直接使用 JWT 进行认证，那么这里的value应该是myShar3dS3cret。
-
-
grant_type -
(必需, 字符串) 授权的类型。
有效值为
grant_type-
access_token -
在这种授权类型中，您必须提供一个由 Elasticsearch 令牌服务创建的访问令牌（参见 获取令牌 API 和 为 Elasticsearch 加密 HTTP 客户端通信），或者一个 JWT（可以是 JWT
access_token或 JWTid_token）。 -
password -
在这种授权类型中，您必须提供要为其创建 API 密钥的用户的
username和password。
-
-
password -
(必填*, 字符串)
用户的密码。如果您指定
password授权类型，此参数是必需的。它与其他授权类型不兼容。 -
username -
(必填*, 字符串)
用于标识用户的用户名。如果您指定
password授权类型，则此参数是必需的。它与其他授权类型不兼容。
*表示在某些情况下需要设置，但并非所有情况下都需要。
响应体
edit成功的激活用户配置文件 API 调用返回一个 JSON 结构，其中包含配置文件唯一 ID、用户信息、操作时间戳和版本控制编号。
示例
editPOST /_security/profile/_activate
{
"grant_type": "password",
"username" : "jacknich",
"password" : "l0ng-r4nd0m-p@ssw0rd"
}
API返回以下响应：
{
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
"enabled": true,
"last_synchronized": 1642650651037,
"user": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"realm_name": "native",
"full_name": "Jack Nicholson",
"email": "jacknich@example.com"
},
"labels": {},
"data": {},
"_doc": {
"_primary_term": 88,
"_seq_no": 66
}
}
禁用用户配置文件 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
禁用用户配置文件，使其在用户配置文件搜索中不可见。
先决条件
edit要使用此API，您必须拥有manage_user_profile集群权限。
描述
edit当您激活用户档案时，它会自动启用并在用户档案搜索中可见。您可以使用禁用用户档案API来禁用用户档案，使其在这些搜索中不可见。
要重新启用已禁用的用户配置文件，请使用启用用户配置文件 API。
路径参数
edit-
<uid> - (必需，字符串) 用户配置文件的唯一标识符。
查询参数
edit-
refresh -
(可选，枚举) 如果
true，Elasticsearch 会刷新受影响的 shards 以使此操作对搜索可见，如果wait_for则等待刷新以使此操作对搜索可见，如果false则不对刷新做任何操作。 有效值:true,false,wait_for。默认值:false。
示例
edit以下请求禁用了与uid匹配的用户档案：
POST /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0/_disable
启用用户配置文件API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
启用用户配置文件，使其在 用户配置文件搜索中可见。
先决条件
edit要使用此API，您必须拥有manage_user_profile集群权限。
路径参数
edit-
<uid> - (必需, 字符串) 用户配置文件的唯一标识符。
查询参数
edit-
refresh -
(可选，枚举) 如果
true，Elasticsearch 会刷新受影响的 shards 以使此操作对搜索可见，如果wait_for则等待刷新以使此操作对搜索可见，如果false则不对刷新做任何操作。 有效值：true、false、wait_for。默认值：false。
示例
edit以下请求为匹配u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0的uid启用用户配置文件：
POST /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0/_enable
获取用户资料 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
使用唯一用户档案ID列表检索用户档案。
请求
editGET /_security/profile/
路径参数
edit-
uid - (必需，字符串) 用户配置文件的唯一标识符。您可以指定多个ID作为逗号分隔的列表。
查询参数
edit-
data -
(可选，字符串) 用于
data字段过滤器的逗号分隔列表。要返回所有内容，请使用data=*。要返回内容的子集，请使用data=来检索嵌套在指定
响应体
edit成功的调用将返回用户配置文件的JSON表示形式及其内部版本号。如果未找到所提供的uid的配置文件文档，API将返回一个空对象。默认情况下，不会返回data字段的内容，以避免反序列化潜在的大负载。
示例
editGET /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0
API 返回以下响应，对应于匹配 u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0 的 uid：
{
"profiles": [
{
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
"enabled": true,
"last_synchronized": 1642650651037,
"user": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"realm_name": "native",
"full_name": "Jack Nicholson",
"email": "jacknich@example.com"
},
"labels": {
"direction": "north"
},
"data": {},
"_doc": {
"_primary_term": 88,
"_seq_no": 66
}
}
]
}
以下请求检索嵌套在键 app1 下的 data 子集，以及用户的个人资料：
GET /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0?data=app1.key1
{
"profiles": [
{
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
"enabled": true,
"last_synchronized": 1642650651037,
"user": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"realm_name": "native",
"full_name": "Jack Nicholson",
"email": "jacknich@example.com"
},
"labels": {
"direction": "north"
},
"data": {
"app1": {
"key1": "value1"
}
},
"_doc": {
"_primary_term": 88,
"_seq_no": 66
}
}
]
}
如果在获取用户资料时出现任何错误，它们将返回在 errors 字段中：
{
"profiles": [],
"errors": {
"count": 1,
"details": {
"u_FmxQt3gr1BBH5wpnz9HkouPj3Q710XkOgg1PWkwLPBW_5": {
"type": "resource_not_found_exception",
"reason": "profile document not found"
}
}
}
}
建议用户资料 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
获取与指定搜索条件匹配的用户配置文件建议。
查询参数
edit-
data -
(可选，字符串) 用于
data字段过滤器的逗号分隔列表。要返回所有内容，请使用data=*。要返回内容的子集，请使用data=来检索嵌套在指定
请求体
edit指定data作为查询参数和请求体字段是错误的。
-
hint -
(可选, 对象) 额外的搜索条件以提高建议结果的相关性。 与指定提示匹配的配置文件在响应中排名更高。 但不匹配提示的配置文件只要匹配
name字段查询，就不会被排除在响应之外。Properties ofhint:-
uids - (可选, 字符串列表) 要匹配的配置文件UID列表。
-
labels -
(可选, 对象)
一个键值对，用于匹配配置文件的
labels部分。 键必须是字符串，值必须是字符串或字符串列表。 如果配置文件匹配至少一个字符串，则认为它匹配。
-
响应体
edit-
total - (对象) 匹配配置文件数量的元数据。
-
took - (整数) Elasticsearch 执行请求所花费的毫秒数。
-
profiles - (对象数组) 按相关性排序的配置文件文档列表，符合搜索条件。
示例
edit以下请求获取与名称相关字段匹配jack的配置文件文档的建议。它指定了uids和labels提示以提高相关性：
POST /_security/profile/_suggest
{
"name": "jack",
"hint": {
"uids": [
"u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
"u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
],
"labels": {
"direction": ["north", "east"]
}
}
}
|
配置文件的与名称相关的字段必须匹配 |
|
|
提示 |
|
|
如果配置文件的 |
API返回：
{
"took": 30,
"total": {
"value": 3,
"relation": "eq"
},
"profiles": [
{
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
"user": {
"username": "jacknich",
"roles": [ "admin", "other_role1" ],
"realm_name": "native",
"email" : "jacknich@example.com",
"full_name": "Jack Nicholson"
},
"labels": {
"direction": "north"
},
"data": {}
},
{
"uid": "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
"user": {
"username": "jackspa",
"roles": [ "user" ],
"realm_name": "native",
"email" : "jackspa@example.com",
"full_name": "Jack Sparrow"
},
"labels": {
"direction": "south"
},
"data": {}
},
{
"uid": "u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0",
"user": {
"username": "jackrea",
"roles": [ "admin" ],
"realm_name": "native",
"email" : "jackrea@example.com",
"full_name": "Jack Reacher"
},
"labels": {
"direction": "west"
},
"data": {}
}
]
}
更新用户资料数据 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
更新与指定唯一ID关联的用户个人资料的特定数据。
请求
editPOST /_security/profile/
描述
edit更新用户资料API使用JSON对象更新现有用户资料文档中的labels和data字段。新的键及其值会被添加到用户资料文档中，而冲突的键将被请求中包含的数据替换。
对于labels和data，内容由顶级字段进行命名空间划分。
update_profile_data全局权限仅授予更新允许的命名空间的权限。
路径参数
edit-
uid - (必需，字符串) 用户配置文件的唯一标识符。
查询参数
edit请求体
edit-
labels -
(必需*, 对象)
您希望与用户档案关联的可搜索数据。
此字段支持嵌套数据结构。在
labels对象中， 顶级键不能以下划线 (_) 开头或包含句点 (.)。 -
data -
(必需*, 对象)
您希望与用户档案关联的不可搜索数据。
此字段支持嵌套数据结构。在
data对象中，顶级键不能以下划线 (_) 开头或包含句点 (.)。data对象不可搜索，但可以通过 获取用户档案 API 检索。
*表示在某些情况下需要设置，但并非所有情况下都需要。
示例
edit以下请求更新与uid匹配的配置文件文档，u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0：
POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data
{
"labels": {
"direction": "east"
},
"data": {
"app1": {
"theme": "default"
}
}
}
您可以更新配置文件数据以替换某些键并添加新键：
POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data
{
"labels": {
"direction": "west"
},
"data": {
"app1": {
"font": "large"
}
}
}
如果你现在获取个人资料，将返回合并后的个人资料数据：
GET /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0?data=*
{
"profiles": [
{
"uid": "u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0",
"enabled": true,
"last_synchronized": 1642650651037,
"user": {
"username": "jackrea",
"roles": [
"admin"
],
"realm_name": "native",
"full_name": "Jack Reacher",
"email": "jackrea@example.com"
},
"labels": {
"direction": "west"
},
"data": {
"app1": {
"theme": "default",
"font": "large"
}
},
"_doc": {
"_primary_term": 88,
"_seq_no": 66
}
}
]
}
拥有权限用户配置文件 API
edit用户配置文件功能仅设计用于 Kibana 和 Elastic 的可观测性、企业搜索及 Elastic 安全解决方案。个人用户和外部应用程序不应直接调用此 API。Elastic 保留在未来的版本中更改或移除此功能而无需事先通知的权利。
确定与指定用户配置文件 ID 关联的用户是否拥有所有请求的权限。
描述
edit此API使用由激活用户配置文件返回的配置文件ID，来识别要检查权限的用户。 它类似于拥有权限API，但与它不同的是，此API检查其他用户的权限，而不是调用它的用户的权限。
请参阅安全权限以获取可在此API中指定的权限列表。
成功的调用将返回具有所有请求权限的配置文件ID子集列表。
请求体
edit-
uids - (列表) 一个包含配置文件ID的列表。特权是为与这些配置文件关联的用户检查的。
-
privileges -
包含所有要检查的权限的对象。
-
cluster - (列表) 您要检查的集群权限列表。
-
index -
-
names - (列表) 索引列表。
-
allow_restricted_indices -
(布尔值) 如果使用通配符或正则表达式来覆盖受限索引的模式，则需要将其设置为
true（默认值为false）。隐式地，受限索引不匹配索引模式，因为受限索引通常具有有限的权限，并且将它们包含在模式测试中会使大多数此类测试结果为false。如果受限索引明确包含在names列表中，则无论allow_restricted_indices的值如何，都会检查它们对应的权限。 -
privileges - (列表) 您要为指定索引检查的权限列表。
-
-
application -
-
application - (字符串) 应用程序的名称。
-
privileges - (列表) 您要为指定资源检查的权限列表。可以是应用程序权限名称，或者是这些权限授予的操作名称。
-
resources - (列表) 应检查权限的资源名称列表。
-
-
请注意，上面的privileges部分与其他Has Privileges API的请求体相同。
响应体
edit一个成功的用户权限配置文件API调用返回一个包含两个字段的JSON结构：
-
has_privilege_uids - (列表) 具有所请求权限的用户请求的配置文件ID的子集。 所有 所请求的权限。
-
errors -
(对象) 在满足请求时遇到的错误。如果没有错误，此字段不存在。 它不包括没有所有请求权限的用户的配置文件ID。
对象的属性在
errors-
count - (数字) 错误总数
-
details - (对象) 详细的错误报告，键为配置文件ID，值为确切的错误。
-
示例
edit以下示例检查与指定配置文件关联的两个用户是否具有所有请求的集群、索引和应用程序权限：
POST /_security/profile/_has_privileges
{
"uids": [
"u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0",
"u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1",
"u_does-not-exist_0"
],
"privileges": {
"cluster": [ "monitor", "create_snapshot", "manage_ml" ],
"index" : [
{
"names": [ "suppliers", "products" ],
"privileges": [ "create_doc"]
},
{
"names": [ "inventory" ],
"privileges" : [ "read", "write" ]
}
],
"application": [
{
"application": "inventory_manager",
"privileges" : [ "read", "data:write/inventory" ],
"resources" : [ "product/1852563" ]
}
]
}
}
以下示例输出表明，三个用户中只有一个拥有所有权限，其中一个未找到：
{
"has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"],
"errors": {
"count": 1,
"details": {
"u_does-not-exist_0": {
"type": "resource_not_found_exception",
"reason": "profile document not found"
}
}
}
}
创建跨集群API密钥API
edit为基于API密钥的远程集群访问创建一个cross_cluster类型的API密钥。
cross_cluster API密钥不能用于通过REST接口进行身份验证。
相反，REST API密钥旨在通过REST接口使用，
并且不能用于基于API密钥的远程集群访问。
请求
editPOST /_security/cross_cluster/api_key
描述
edit跨集群API密钥由Elasticsearch API密钥服务创建，该服务默认自动启用。 有关禁用API密钥服务的说明，请参阅API密钥服务设置。
成功的请求返回一个包含API密钥、其唯一ID和名称的JSON结构。如果适用，它还会返回API密钥的过期信息，以毫秒为单位。
默认情况下，API 密钥永不过期。您可以在创建 API 密钥时指定过期信息。
请参阅API key service settings以获取与API key服务相关的配置设置。
跨集群API密钥只能通过 更新跨集群API密钥API进行更新。 尝试使用更新REST API密钥API 或批量更新REST API密钥API进行更新将导致错误。 它们可以通过获取API密钥API、查询API密钥API 和使API密钥失效API进行检索和失效。
请求体
edit以下参数可以在POST请求的正文中指定：
-
name - (必需，字符串) 指定此API密钥的名称。
-
access -
(必需, 对象) 授予此 API 密钥的访问权限。访问权限由跨集群搜索和跨集群复制的权限组成。至少必须指定其中之一。
-
search -
(可选, 列表) 一个用于跨集群搜索的索引权限条目列表。
-
names - (必需, 列表) 一个索引或名称模式的列表，此条目中的权限适用于这些索引或名称模式。
-
field_security -
(可选, 对象) 角色所有者具有读访问权限的文档字段。当同时定义了
replication字段时，此字段可能不会被设置。有关更多信息，请参阅 跨集群 API 密钥的字段和文档级安全。 -
query -
(可选) 定义角色所有者具有读访问权限的文档的搜索查询。指定索引中的文档必须匹配此查询才能被角色所有者访问。当同时定义了
replication字段时，此字段可能不会被设置。有关更多信息，请参阅 跨集群 API 密钥的字段和文档级安全。 -
allow_restricted_indices -
(可选, 布尔值) 如果
names字段中的模式应覆盖 系统索引，则需要设置为true（默认值为false）。
-
-
replication -
(可选，列表) 用于跨集群复制的索引权限条目列表。
-
names - (必需, 列表) 一个索引或名称模式的列表，此条目中的权限适用于这些索引或名称模式。
-
-
对于搜索或复制访问，不应指定任何显式的权限。创建过程会自动将access规范转换为角色描述符，并相应地分配相关权限。access值及其对应的role_descriptors会在获取API密钥信息API和查询API密钥信息API的响应中返回。
与REST API 密钥不同，跨集群 API 密钥不会捕获已验证用户的权限。API 密钥的有效权限与使用 access 参数指定的权限完全一致。
-
expiration - (可选, 字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。
-
metadata -
(可选, 对象) 您希望与API密钥关联的任意元数据。
它支持嵌套数据结构。
在
metadata对象中，以_开头的键保留用于系统使用。
示例
edit以下示例创建了一个跨集群的API密钥：
POST /_security/cross_cluster/api_key
{
"name": "my-cross-cluster-api-key",
"expiration": "1d",
"access": {
"search": [
{
"names": ["logs*"]
}
],
"replication": [
{
"names": ["archive*"]
}
]
},
"metadata": {
"description": "phase one",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
成功的调用返回一个JSON结构，提供API密钥信息。
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-cross-cluster-api-key",
"expiration": 1544068612110,
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
|
此 API 密钥的唯一 |
|
|
此API密钥的可选过期时间（以毫秒为单位） |
|
|
生成的 API 密钥密文 |
|
|
API key 凭证，即 |
API 密钥信息可以通过 获取 API 密钥信息 API 来检索。
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
成功调用返回一个包含API密钥信息的JSON结构：
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-cross-cluster-api-key",
"type": "cross_cluster",
"creation": 1548550550158,
"expiration": 1548551550158,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"metadata": {
"description": "phase one",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
},
"role_descriptors": {
"cross_cluster": {
"cluster": [
"cross_cluster_search", "cross_cluster_replication"
],
"indices": [
{
"names": [
"logs*"
],
"privileges": [
"read", "read_cross_cluster", "view_index_metadata"
],
"allow_restricted_indices": false
},
{
"names": [
"archive*"
],
"privileges": [
"cross_cluster_replication", "cross_cluster_replication_internal"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
},
"access": {
"search": [
{
"names": [
"logs*"
],
"allow_restricted_indices": false
}
],
"replication": [
{
"names": [
"archive*"
],
"allow_restricted_indices": false
}
]
}
}
]
}
|
API 密钥的 ID |
|
|
API 密钥的名称 |
|
|
API 密钥的类型 |
|
|
为跨集群 API 密钥生成的角色描述符。它总是包含一个名为 |
|
|
进行所需跨集群访问所需的集群权限。
如果只需要跨集群搜索，则值为 |
|
|
与所需跨集群搜索访问相对应的索引权限。 |
|
|
与所需跨集群复制访问相对应的索引权限。 |
|
|
The |
要使用生成的 API 密钥，请将其配置为 API 密钥远程集群配置的一部分中的集群凭据。
更新跨集群API密钥API
edit更新用于基于API密钥的远程集群访问的现有跨集群API密钥。
请求
editPUT /_security/cross_cluster/api_key/
先决条件
edit-
要使用此API，您必须至少拥有
manage_security集群权限。 用户只能更新他们自己创建的API密钥。 要更新其他用户的API密钥，请使用run_as功能 代表其他用户提交请求。
无法使用 API 密钥作为此 API 的身份验证凭据。 要更新 API 密钥，需要所有者用户的凭据。
描述
edit使用此API更新由创建跨集群API密钥API创建的跨集群API密钥。 无法更新已过期的API密钥，或已被使API密钥失效的API密钥。
此API支持对API密钥的访问范围、元数据和过期时间的更新。
每次调用时，所有者用户的信息，例如用户名、领域，也会自动更新。
此API无法更新REST API密钥，应通过更新API密钥或批量更新API密钥API进行更新。
路径参数
edit-
id - (必需, 字符串) 要更新的API密钥的ID。
请求体
edit您可以在请求体中指定以下参数。这些参数是可选的，但不能全部缺失。
-
access - (可选, 对象) 授予此API密钥的访问权限。访问权限由跨集群搜索和跨集群复制的权限组成。 至少需要指定其中之一。 指定时，新的访问分配将完全替换之前分配的访问权限。 有关字段结构的详细信息，请参阅创建跨集群API密钥API的相同参数。
-
metadata -
(可选, 对象) 您希望与 API 密钥关联的任意元数据。
它支持嵌套数据结构。
在
metadata对象中，以_开头的顶级键保留用于系统使用。 指定时，这将完全替换之前与 API 密钥关联的元数据。 -
expiration - (可选, 字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。可以省略以保持不变。
响应体
edit-
updated -
(布尔值) 如果
true，API 密钥已更新。 如果false，API 密钥没有变化，因为没有检测到变化。
示例
edit如果你创建一个跨集群API密钥如下：
POST /_security/cross_cluster/api_key
{
"name": "my-cross-cluster-api-key",
"access": {
"search": [
{
"names": ["logs*"]
}
]
},
"metadata": {
"application": "search"
}
}
成功调用后返回一个JSON结构，提供API密钥信息。 例如：
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-cross-cluster-api-key",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
API 密钥的信息，包括其确切的角色描述符，可以通过 获取 API 密钥信息 API 进行检查
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
成功调用返回一个包含API密钥信息的JSON结构：
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-cross-cluster-api-key",
"type": "cross_cluster",
"creation": 1548550550158,
"expiration": null,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"metadata": {
"application": "search"
},
"role_descriptors": {
"cross_cluster": {
"cluster": [
"cross_cluster_search"
],
"indices": [
{
"names": [
"logs*"
],
"privileges": [
"read", "read_cross_cluster", "view_index_metadata"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
},
"access": {
"search": [
{
"names": [
"logs*"
],
"allow_restricted_indices": false
}
]
}
}
]
}
以下示例更新了上面创建的API密钥，为其分配了新的访问范围和元数据：
PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx
{
"access": {
"replication": [
{
"names": ["archive"]
}
]
},
"metadata": {
"application": "replication"
}
}
成功调用返回一个JSON结构，表明API密钥已更新：
{
"updated": true
}
更新后，API 密钥的权限可以通过 获取 API 密钥信息 API 再次检查，结果将是：
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-cross-cluster-api-key",
"type": "cross_cluster",
"creation": 1548550550158,
"expiration": null,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"metadata": {
"application": "replication"
},
"role_descriptors": {
"cross_cluster": {
"cluster": [
"cross_cluster_replication"
],
"indices": [
{
"names": [
"archive*"
],
"privileges": [
"cross_cluster_replication", "cross_cluster_replication_internal"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
},
"access": {
"replication": [
{
"names": [
"archive*"
],
"allow_restricted_indices": false
}
]
}
}
]
}