› › ›

API создания ключа API

Создаёт ключ API для доступа без необходимости базовой аутентификации.

Запрос

POST /_security/api_key

PUT /_security/api_key

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

Для использования этого API у вас должна быть хотя бы привилегия кластера manage_own_api_key.

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

Описание

Ключи API создаются службой ключей API Elasticsearch, которая автоматически включается, когда вы настраиваете TLS для HTTP-интерфейса. В качестве альтернативы вы можете явно включить параметр xpack.security.authc.api_key.enabled.

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

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

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

Тело запроса

В теле запроса POST или PUT можно указать следующие параметры:

name: (Обязательно, строка) Указывает имя для этого ключа API.

role_descriptors: (Необязательно, массив-список-описаний-ролей) Массив описаний ролей для этого ключа API. Этот параметр необязателен. Если он не указан или представляет собой пустой массив, ключ API будет иметь моментальный снимок разрешений аутентифицированного пользователя. Если вы укажете описания ролей, полученные разрешения будут представлять собой пересечение разрешений ключа API и разрешений аутентифицированного пользователя, ограничивая область доступа ключей API. Структура описания роли аналогична запросу для API создания роли. Для получения более подробной информации см. API создания или обновления ролей.

Из-за способа расчёта этого пересечения разрешений невозможно создать ключ API, который является потомком другого ключа API, если только производный ключ не создаётся без каких-либо привилегий. В этом случае вы должны явно указать описание роли без привилегий. Производный ключ API может использоваться для аутентификации; он не будет иметь права вызывать API Elasticsearch.
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"]
    }
  }
}

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

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

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

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

Для использования сгенерированного ключа API отправьте запрос с заголовком Authorization, который содержит префикс ApiKey, за которым следуют учетные данные ключа API (значение encoded из ответа).

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

Если на вашем узле параметр xpack.security.http.ssl.enabled имеет значение true, то при создании ключа API необходимо указать https

В системе Unix-подобной операционной системы значение encoded можно создать с помощью следующей команды:

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

Используйте -n, чтобы команда echo не выводила символ новой строки в конце

© 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/7.17/security-api-create-api-key.html