创建 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 密钥
resp = client.security.create_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"
]
}
},
)
print(resp)
const response = await client.security.createApiKey({
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"],
},
},
});
console.log(response);
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
resp = client.security.create_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"
]
}
}
},
)
print(resp)
const response = await client.security.createApiKey({
name: "my-restricted-api-key",
role_descriptors: {
"my-restricted-role-descriptor": {
indices: [
{
names: ["my-search-app"],
privileges: ["read"],
},
],
restriction: {
workflows: ["search_application_query"],
},
},
},
});
console.log(response);
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"]
}
}
}
}