› › ›

创建跨集群 API 密钥 API

为基于 API 密钥的远程集群访问创建类型为 cross_cluster 的 API 密钥。 cross_cluster API 密钥不能通过 REST 接口进行身份验证。相反，REST API 密钥旨在通过 REST 接口使用，不能用于基于 API 密钥的远程集群访问。

请求

编辑

POST /_security/cross_cluster/api_key

先决条件

编辑

要使用此 API，您必须至少拥有 manage_security 集群权限。

要验证此请求，您必须使用不是 API 密钥的凭据。即使您使用具有所需权限的 API 密钥，API 也会返回错误。

描述

编辑

跨集群 API 密钥由 Elasticsearch API 密钥服务创建，该服务会自动启用。有关禁用 API 密钥服务的说明，请参阅 API 密钥服务设置。

成功请求将返回一个 JSON 结构，其中包含 API 密钥、其唯一 ID 及其名称。如果适用，它还会返回 API 密钥的过期信息（以毫秒为单位）。

默认情况下，API 密钥永不过期。您可以在创建 API 密钥时指定过期信息。

有关与 API 密钥服务相关的配置设置，请参阅 API 密钥服务设置。

跨集群 API 密钥只能使用更新跨集群 API 密钥 API 进行更新。尝试使用更新 REST API 密钥 API 或批量更新 REST API 密钥 API 更新它们将导致错误。可以使用获取 API 密钥 API、查询 API 密钥 API 和使 API 密钥无效 API 来检索和使它们失效。

请求正文

编辑

以下参数可以在 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 对象中，以 _ 开头的键保留供系统使用。

示例

编辑

以下示例创建了一个跨集群 API 密钥

resp = client.perform_request(
    "POST",
    "/_security/cross_cluster/api_key",
    headers={"Content-Type": "application/json"},
    body={
        "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"
                ]
            }
        }
    },
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_security/cross_cluster/api_key",
  body: {
    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"],
      },
    },
  },
});
console.log(response);

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

	正在生成的 API 密钥的可选过期时间。如果未提供过期时间，则 API 密钥不会过期。
	要授予 API 密钥的跨集群搜索访问权限。
	要授予 API 密钥的跨集群复制访问权限。

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

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

	此 API 密钥的唯一 `id`
	此 API 密钥的可选过期时间（以毫秒为单位）
	生成的 API 密钥密钥
	API 密钥凭据，它是 `id` 和 `api_key` 的 UTF-8 表示形式的 Base64 编码，它们通过冒号 ( `:` ) 连接。

可以使用获取 API 密钥 API 检索 API 密钥信息。

resp = client.security.get_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
)
print(resp)

const response = await client.security.getApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
});
console.log(response);

GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx

成功调用将返回一个 JSON 结构，其中包含 API 密钥的信息

{
  "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 密钥生成的角色描述符。它始终包含一个名为 `cross_cluster` 的角色描述符。跨集群 API 密钥没有受限角色描述符。
	所需跨集群访问所需的集群权限。如果仅需要跨集群搜索，则该值为 `cross_cluster_search`。如果仅需要跨集群复制，则该值为 `cross_cluster_replication`。如果需要搜索和复制，则为两者。
	与所需跨集群搜索访问对应的索引权限。
	与所需跨集群复制访问对应的索引权限。
	`access` 对应于 API 密钥创建时指定的值。

要使用生成的 API 密钥，请将其配置为基于 API 密钥的远程集群配置的一部分的集群凭据。

« 具有用户配置文件 API 的权限更新跨集群 API 密钥 API »