New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 清除服务帐户令牌缓存 API 创建或更新应用程序权限 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›安全 API

创建 API 密钥 API

编辑

创建 API 密钥 API

编辑

创建无需基本身份验证即可访问的 API 密钥。

请求

编辑

POST /_security/api_key

PUT /_security/api_key

先决条件

编辑
  • 要使用此 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"]
    }
  }
}
Copy as curlTry in Elastic 

为正在生成的 API 密钥设置可选的过期时间。 如果未提供过期时间，则 API 密钥不会过期。

此 API 密钥的可选角色描述符。 如果未提供，则应用已认证用户的权限。

成功调用会返回一个 JSON 结构，其中提供了 API 密钥信息。

{
  "id": "VuaCfGcBCdbkQm-e5aOx",        
  "name": "my-api-key",
  "expiration": 1544068612110,         
  "api_key": "ui2lp2axTNmsyakw9tvNnw", 
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="  
}

此 API 密钥的唯一 id

此 API 密钥的可选过期时间（以毫秒为单位）

生成的 API 密钥

API 密钥凭据是 id 和 api_key 的 UTF-8 表示形式的 Base64 编码，它们之间用冒号 (:) 连接。

要使用生成的 API 密钥，请发送一个带有 Authorization 标头的请求，其中包含 ApiKey 前缀，后跟 API 密钥凭据（响应中的 encoded 值）。

curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" \
https://127.0.0.1:9200/_cluster/health\?pretty

如果您的节点的 xpack.security.http.ssl.enabled 设置为 true，则在创建 API 密钥时必须指定 https

在类 Unix 系统上，可以使用以下命令创建 encoded 值

echo -n "VuaCfGcBCdbkQm-e5aOx:ui2lp2axTNmsyakw9tvNnw" | base64

使用 -n，以便 echo 命令不打印尾随的换行符

以下示例创建了一个 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"]
      }
    }
  }
}
Copy as curlTry in Elastic 
« 清除服务帐户令牌缓存 API 创建或更新应用程序权限 API »

On this page

Was this helpful?
Feedback