› › ›

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, его уникальный идентификатор и имя. При необходимости также возвращается информация о времени действия ключа API в миллисекундах.

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

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

Тело запроса

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

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

role_descriptors

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

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

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

	Необязательное время действия для генерируемого ключа 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 не выводила символ конца строки

Следующий пример создает ключ API с ограничением на рабочий процесс search_application_query, что позволяет вызывать только API поиска приложения Search:

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

© 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-api-key.html