› › ›

API создания ключа API для межкластерного доступа

Создает ключ API типа cross_cluster для доступа к удаленным кластерам на основе ключа API. Ключ API типа cross_cluster не может использоваться для аутентификации через REST-интерфейс. Напротив, ключ REST API предназначен для использования через REST-интерфейс и не может использоваться для доступа к удаленным кластерам на основе ключа API.

Запрос

POST /_security/cross_cluster/api_key

Предварительные условия

Для использования этого API необходимо обладать привилегией manage_security кластера.

Для аутентификации этого запроса необходимо использовать учетные данные, которые не являются ключом API. Даже если вы используете ключ API, обладающий необходимой привилегией, API вернёт ошибку.

Описание

Ключи API для межкластерного доступа создаются службой ключей Elasticsearch, которая автоматически включена. Инструкции по отключению службы ключей API см. в разделе Параметры службы ключей API.

Успешный запрос возвращает JSON-структуру, содержащую ключ API, его уникальный идентификатор и имя. При необходимости также возвращается информация о сроке действия ключа API в миллисекундах.

По умолчанию ключи API не истекают. Вы можете указать информацию о сроке действия при создании ключей API.

См. раздел Параметры службы ключей API для параметров конфигурации, связанных со службой ключей API.

Ключи API для межкластерного доступа могут быть обновлены только с помощью API обновления ключа API для межкластерного доступа. Попытка обновить их с помощью API обновления ключа API или 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: (необязательный, булево) Должно быть установлено в true (по умолчанию false), если шаблоны в поле names должны охватывать системные индексы.

replication

(необязательный, список) Список записей разрешений на индексы для межкластерной репликации.

names: (обязательный, список) Список индексов или шаблонов имен, к которым относятся разрешения в этой записи.

Явные права доступа для поиска или репликации не должны указываться. Процесс создания автоматически преобразует спецификацию access в описание роли, которому присваиваются соответствующие привилегии. Значение access и соответствующее role_descriptors возвращаются в ответах API получения информации о ключах API и API запроса информации о ключах API.

В отличие от ключей API REST, межкластерный ключ 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=="  
}

	Уникальный `id` для этого ключа API
	Необязательное время истечения срока действия в миллисекундах для этого ключа API
	Сгенерированный секрет ключа API
	Учетные данные ключа API, представляющие собой Base64-кодирование UTF-8-представления `id` и `api_key`, соединённых двоеточием (`:`)

Информация о ключе 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
	Название ключа API
	Тип ключа API
	Описание ролей, сгенерированных для ключа API межкластерного взаимодействия. Оно всегда содержит ровно одно описание роли с именем `cross_cluster`. Ключ API межкластерного взаимодействия не имеет ограничений по ролям.
	Права кластера, необходимые для требуемого межкластерного доступа. Значение равно `cross_cluster_search`, если требуется только межкластерный поиск. Значение равно `cross_cluster_replication`, если требуется только межкластерная репликация. Или оба, если требуются поиск и репликация.
	Права на индексы, соответствующие необходимому межкластерному доступу для поиска.
	Права на индексы, соответствующие необходимому межкластерному доступу для репликации.
	`access` соответствует значению, указанному при создании ключа API.

Для использования сгенерированного ключа API настройте его в качестве учетных данных кластера в рамках удалённой конфигурации кластера, основанной на ключе API.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-create-cross-cluster-api-key.html