创建 API 密钥 API
编辑创建 API 密钥 API编辑
创建 API 密钥以进行访问，无需基本身份验证。
先决条件编辑
- 要使用此 API，您必须至少具有
manage_own_api_key集群权限。
如果用于验证此请求的凭据是 API 密钥，则派生的 API 密钥不能具有任何权限。如果您指定权限，API 将返回错误。请参阅 role_descriptors 下的说明。
描述编辑
API 密钥由 Elasticsearch API 密钥服务创建，该服务会自动启用。有关禁用 API 密钥服务的说明，请参阅 API 密钥服务设置。
成功请求将返回一个 JSON 结构，其中包含 API 密钥、其唯一 ID 及其名称。如果适用，它还会以毫秒为单位返回 API 密钥的过期信息。
默认情况下，API 密钥永不过期。您可以在创建 API 密钥时指定过期信息。
有关与 API 密钥服务相关的配置设置，请参阅 API 密钥服务设置。
请求正文编辑
以下参数可以在 POST 或 PUT 请求的正文中指定
-
name - (必需，字符串) 指定此 API 密钥的名称。
-
role_descriptors -
(可选，对象) 此 API 密钥的角色描述符。此参数是可选的。当它未指定或为空数组时，API 密钥将具有经过身份验证的用户的权限的快照。如果您提供角色描述符，则结果权限将是 API 密钥权限和经过身份验证的用户的权限的交集，从而限制 API 密钥的访问范围。
由于此权限交集的计算方式，无法创建另一个 API 密钥的子级 API 密钥，除非派生的密钥是在没有任何权限的情况下创建的。在这种情况下，您必须显式指定一个没有权限的角色描述符。派生的 API 密钥可用于身份验证；它将没有调用 Elasticsearch API 的权限。
-
applications -
(列表) 应用程序权限条目的列表。
-
application(必需) - (字符串) 此条目适用的应用程序的名称
-
privileges(必需) - (列表) 字符串列表，其中每个元素都是应用程序权限或操作的名称。
-
resources(必需) - (列表) 应用权限的资源列表。
-
-
cluster - (列表) 集群权限列表。这些权限定义 API 密钥能够执行的集群级别操作。
-
global - (对象) 定义全局权限的对象。全局权限是集群权限的一种形式，它与请求相关。目前，对全局权限的支持仅限于应用程序权限的管理。此字段是可选的。
-
indices -
(列表) 索引权限条目的列表。
-
field_security - (对象) API 密钥具有读取访问权限的文档字段。有关更多信息，请参阅 设置字段和文档级别安全。
-
names(必需) - (列表) 此条目中权限适用的索引（或索引名称模式）列表。
-
privileges(必需) - (列表) API 密钥在指定索引上具有的索引级别权限。
-
query - 定义 API 密钥具有读取访问权限的文档的搜索查询。指定索引中的文档必须与该查询匹配，才能被 API 密钥访问。
-
-
metadata - (对象) 可选的元数据。在
metadata对象中，以_开头的键保留供系统使用。 -
restriction -
(对象) 角色描述符何时被允许生效的可选限制。有关更多信息，请参阅 角色限制。
-
workflows -
(列表) API 密钥受限的工作流列表。有关完整列表，请参阅 工作流。
为了使用角色限制，必须使用 单个角色描述符 创建 API 密钥。
-
-
run_as - (列表) API 密钥可以模拟的用户列表。有关更多信息，请参阅 代表其他用户提交请求。
-
-
expiration - (可选，字符串) API 密钥的过期时间。默认情况下，API 密钥永不过期。
-
metadata - (可选，对象) 您要与 API 密钥关联的任意元数据。它支持嵌套数据结构。在
metadata对象中，以_开头的键保留供系统使用。
示例编辑
以下示例创建一个 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 密钥凭据，它是 |
要使用生成的 API 密钥，请发送一个带有 Authorization 标头的请求，该标头包含一个 ApiKey 前缀，后跟 API 密钥凭据（响应中的 encoded 值）。
curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" \ https://127.0.0.1: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"]
}
}
}
}