Spec-Zone.ru › Elasticsearch 8
›Elasticsearch Guide [8.17] ›REST API ›API безопасности

API получения информации о ключах API

Справочник по новым API

Для получения самых актуальных данных об API обратитесь к API безопасности.

Получает информацию о ключах API с помощью Query DSL в страничном формате.

Запрос

GET /_security/_query/api_key

POST /_security/_query/api_key

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

  • Для использования этого API необходимо обладать, как минимум, привилегией manage_own_api_key или read_security кластера.
  • Если у вас есть только привилегия manage_own_api_key, этот API возвращает только ключи API, которые вы владеете. Если у вас есть привилегии read_security, manage_api_key или выше (включая manage_security), этот API возвращает все ключи API независимо от владения.

Описание

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

Параметры пути

with_limited_by
(Необязательно, логическое значение) Флаг, определяющий, нужно ли возвращать моментальную фотографию описателей ролей пользователя-владельца, связанных с ключом API. Фактическое разрешение ключа API — это пересечение его назначенных описателей ролей и описателей ролей пользователя-владельца (в сущности, с ограничениями). Ключ API не может получить описатели ролей с ограничением (включая себя), если у него нет привилегии manage_api_key или выше.
with_profile_uid
(Необязательно, логическое значение) Определяет, нужно ли также получить профиль пользователя uid для пользователя-владельца ключа API. Если профиль существует, его идентификатор (uid) возвращается в поле profile_uid для каждого ключа API. По умолчанию false.
typed_keys
(Необязательно, логическое значение) Если true, имена агрегаций в ответе будут иметь префиксы с соответствующими типами. По умолчанию false.

Тело запроса

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

query

(Необязательно, объект) Запрос для фильтрации возвращаемых API-ключей. Если параметр запроса отсутствует, он эквивалентен запросу match_all. Запрос поддерживает подмножество типов запросов, включая match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range и simple query string.

Вы можете запросить следующие общедоступные значения, связанные с API-ключом.

Запрашиваемые строковые значения, связанные с API-ключами, внутренне отображаются как keywords. Следовательно, если для запроса match не указан параметр analyzer, то предоставленная строка запроса match интерпретируется как единственное ключевое значение. Такой запрос match поэтому эквивалентен запросу term.

Допустимые значения для query
id
Идентификатор API-ключа. Обратите внимание, что id необходимо запросить с помощью запроса ids.
type
API-ключи могут быть типа rest, если созданы с помощью API Создание API-ключа или Предоставление API-ключа, или типа cross_cluster, если созданы с помощью API Создание API-ключа кросс-кластера.
name
Название API-ключа.
creation
Время создания API-ключа в миллисекундах.
expiration
Время истечения срока действия API-ключа в миллисекундах. Это null, если ключ не был настроен на истечение.
invalidated
Указывает, является ли API-ключ недействительным. Если true, ключ недействителен. По умолчанию false.
invalidation
Время аннулирования API-ключа в миллисекундах. Это поле устанавливается только для аннулированных API-ключей.
username
Имя пользователя владельца API-ключа.
realm
Имя домена владельца API-ключа.
metadata
Поле метаданных, связанное с API-ключом, например, metadata.my_field. Метаданные индексируются как тип поля сглаженный. Это означает, что все поля ведут себя как поля keyword при поиске и сортировке. Невозможно сослаться на подмножество полей метаданных с использованием шаблонов подстановок, например metadata.field*, даже для типов запросов, поддерживающих шаблоны имен полей. Наконец, все поля метаданных можно искать вместе, просто упомянув metadata (без точки и имени подполя).

Вы не можете запросить описания ролей API-ключа.

aggs или aggregations
(Необязательно, объект) Любые агрегации для запуска над корпусом возвращенных API-ключей. Агрегации и запросы работают вместе. Агрегации вычисляются только для API-ключей, которые соответствуют запросу. Это поддерживает только подмножество типов агрегаций, а именно: terms, range, диапазон дат, missing, cardinality, подсчет значений, composite, фильтр и фильтры. Кроме того, агрегации выполняются только над тем же подмножеством полей, с которым работает query.
from

(Необязательно, целое число) Смещение начального документа. Должно быть неотрицательным и по умолчанию равно 0.

По умолчанию вы не можете просмотреть более 10 000 совпадений с помощью параметров from и size. Чтобы просмотреть больше совпадений, используйте параметр search_after.

size

(Необязательно, целое число) Количество возвращаемых совпадений. Не должно быть отрицательным и по умолчанию равно 10. Параметр size может быть установлен на 0, в этом случае не возвращаются совпадения API-ключей, а только результаты агрегаций.

По умолчанию вы не можете просмотреть более 10 000 совпадений с помощью параметров from и size. Чтобы просмотреть больше совпадений, используйте параметр search_after.

sort
(Необязательно, объект) Определение сортировки. Помимо id, все общедоступные поля API-ключа могут быть использованы для сортировки. Кроме того, сортировка также может быть применена к полю _doc для сортировки по порядку индекса.
search_after
(Необязательно, массив) Определение поиска после.

Тело ответа

Этот API возвращает следующие поля верхнего уровня:

total
Общее количество найденных API-ключей.
count
Количество API-ключей, возвращенных в ответе.
api_keys
Список информации об API-ключах.

Примеры

Следующий запрос перечисляет все API-ключи, предполагая, что у вас есть привилегия manage_api_key:

resp = client.security.query_api_keys()
print(resp)
const response = await client.security.queryApiKeys();
console.log(response);
GET /_security/_query/api_key

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

{
  "total": 3,
  "count": 3,
  "api_keys": [ 
    {
      "id": "nkvrGXsB8w290t56q3Rg",
      "name": "my-api-key-1",
      "creation": 1628227480421,
      "expiration": 1629091480421,
      "invalidated": false,
      "username": "elastic",
      "realm": "reserved",
      "realm_type": "reserved",
      "metadata": {
        "letter": "a"
      },
      "role_descriptors": { 
        "role-a": {
          "cluster": [
            "monitor"
          ],
          "indices": [
            {
              "names": [
                "index-a"
              ],
              "privileges": [
                "read"
              ],
              "allow_restricted_indices": false
            }
          ],
          "applications": [ ],
          "run_as": [ ],
          "metadata": { },
          "transient_metadata": {
            "enabled": true
          }
        }
      }
    },
    {
      "id": "oEvrGXsB8w290t5683TI",
      "name": "my-api-key-2",
      "creation": 1628227498953,
      "expiration": 1628313898953,
      "invalidated": false,
      "username": "elastic",
      "realm": "reserved",
      "metadata": {
        "letter": "b"
      },
      "role_descriptors": { } 
    }
  ]
}

Список API-ключей, полученных для этого запроса

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

Пустое описание ролей означает, что API-ключ наследует разрешения пользователя-владельца.

Если вы создаете API-ключ со следующими деталями:

resp = client.security.create_api_key(
    name="application-key-1",
    metadata={
        "application": "my-application"
    },
)
print(resp)
const response = await client.security.createApiKey({
  name: "application-key-1",
  metadata: {
    application: "my-application",
  },
});
console.log(response);
POST /_security/api_key
{
  "name": "application-key-1",
  "metadata": { "application": "my-application"}
}

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

{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "application-key-1",
  "api_key": "ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

Используйте информацию из ответа для получения API-ключа по ID:

resp = client.security.query_api_keys(
    with_limited_by=True,
    query={
        "ids": {
            "values": [
                "VuaCfGcBCdbkQm-e5aOx"
            ]
        }
    },
)
print(resp)
const response = await client.security.queryApiKeys({
  with_limited_by: "true",
  query: {
    ids: {
      values: ["VuaCfGcBCdbkQm-e5aOx"],
    },
  },
});
console.log(response);
GET /_security/_query/api_key?with_limited_by=true
{
  "query": {
    "ids": {
      "values": [
        "VuaCfGcBCdbkQm-e5aOx"
      ]
    }
  }
}

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

{
  "api_keys": [
    {
      "id": "VuaCfGcBCdbkQm-e5aOx",
      "name": "application-key-1",
      "creation": 1548550550158,
      "expiration": 1548551550158,
      "invalidated": false,
      "username": "myuser",
      "realm": "native1",
      "realm_type": "native",
      "metadata": {
        "application": "my-application"
      },
      "role_descriptors": { },
      "limited_by": [ 
        {
          "role-power-user": {
            "cluster": [
              "monitor"
            ],
            "indices": [
              {
                "names": [
                  "*"
                ],
                "privileges": [
                  "read"
                ],
                "allow_restricted_indices": false
              }
            ],
            "applications": [ ],
            "run_as": [ ],
            "metadata": { },
            "transient_metadata": {
              "enabled": true
            }
          }
        }
      ]
    }
  ]
}

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

Вы также можете получить API-ключ по имени:

resp = client.security.query_api_keys(
    query={
        "term": {
            "name": {
                "value": "application-key-1"
            }
        }
    },
)
print(resp)
const response = await client.security.queryApiKeys({
  query: {
    term: {
      name: {
        value: "application-key-1",
      },
    },
  },
});
console.log(response);
GET /_security/_query/api_key
{
  "query": {
    "term": {
      "name": {
        "value": "application-key-1"
      }
    }
  }
}

Используйте запрос с bool, чтобы выполнить сложные логические условия, и используйте from, size, sort для помощи в постраничном отображении результата:

GET /_security/_query/api_key
{
  "query": {
    "bool": {
      "must": [
        {
          "prefix": {
            "name": "app1-key-" 
          }
        },
        {
          "term": {
            "invalidated": "false" 
          }
        }
      ],
      "must_not": [
        {
          "term": {
            "name": "app1-key-01" 
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "username": "org-*-user" 
          }
        },
        {
          "term": {
            "metadata.environment": "production" 
          }
        }
      ]
    }
  },
  "from": 20, 
  "size": 10, 
  "sort": [ 
    { "creation": { "order": "desc", "format": "date_time" } },
    "name"
  ]
}

Имя API-ключа должно начинаться с app1-key-

API-ключ должен оставаться действительным

Имя API-ключа не должно быть app1-key-01

API-ключ должен принадлежать пользователю с именем, соответствующим шаблону шаблона org-*-user

API-ключ должен иметь поле метаданных environment со значением production

Смещение для начала поиска результата — 20-й API-ключ (индекс с нуля)

Размер страницы ответа — 10 API-ключей

Результат сначала сортируется по дате creation в порядке убывания, затем по имени в порядке возрастания

Ответ содержит список соответствующих API-ключей вместе с их значениями сортировки:

{
  "total": 100,
  "count": 10,
  "api_keys": [
    {
      "id": "CLXgVnsBOGkf8IyjcXU7",
      "name": "app1-key-79",
      "creation": 1629250154811,
      "invalidated": false,
      "username": "org-admin-user",
      "realm": "native1",
      "metadata": {
        "environment": "production"
      },
      "role_descriptors": { },
      "_sort": [
        "2021-08-18T01:29:14.811Z",  
        "app1-key-79"  
      ]
    },
    {
      "id": "BrXgVnsBOGkf8IyjbXVB",
      "name": "app1-key-78",
      "creation": 1629250153794,
      "invalidated": false,
      "username": "org-admin-user",
      "realm": "native1",
      "metadata": {
        "environment": "production"
      },
      "role_descriptors": { },
      "_sort": [
        "2021-08-18T01:29:13.794Z",
        "app1-key-78"
      ]
    },
    ...
  ]
}

Первое значение сортировки — время создания, отображаемое в формате date_time формате, определенном в запросе

Второе значение сортировки — имя API-ключа

Пример агрегаций

Например, у нас есть 2 пользователя "june" и "king", каждый из которых владеет 3 API-ключами:

  • один, который никогда не истекает (аннулирован для пользователя "king")
  • один, который истекает через 10 дней
  • и один, который истекает через 100 дней (аннулирован для пользователя "june")

следующий запрос возвращает имена действительных (не истекших и не аннулированных) API-ключей, срок действия которых скоро истекает (через 30 дней), сгруппированных по имени пользователя-владельца.

Запрос

resp = client.security.query_api_keys(
    size=0,
    query={
        "bool": {
            "must": {
                "term": {
                    "invalidated": False
                }
            },
            "should": [
                {
                    "range": {
                        "expiration": {
                            "gte": "now"
                        }
                    }
                },
                {
                    "bool": {
                        "must_not": {
                            "exists": {
                                "field": "expiration"
                            }
                        }
                    }
                }
            ],
            "minimum_should_match": 1
        }
    },
    aggs={
        "keys_by_username": {
            "composite": {
                "sources": [
                    {
                        "usernames": {
                            "terms": {
                                "field": "username"
                            }
                        }
                    }
                ]
            },
            "aggs": {
                "expires_soon": {
                    "filter": {
                        "range": {
                            "expiration": {
                                "lte": "now+30d/d"
                            }
                        }
                    },
                    "aggs": {
                        "key_names": {
                            "terms": {
                                "field": "name"
                            }
                        }
                    }
                }
            }
        }
    },
)
print(resp)
const response = await client.security.queryApiKeys({
  size: 0,
  query: {
    bool: {
      must: {
        term: {
          invalidated: false,
        },
      },
      should: [
        {
          range: {
            expiration: {
              gte: "now",
            },
          },
        },
        {
          bool: {
            must_not: {
              exists: {
                field: "expiration",
              },
            },
          },
        },
      ],
      minimum_should_match: 1,
    },
  },
  aggs: {
    keys_by_username: {
      composite: {
        sources: [
          {
            usernames: {
              terms: {
                field: "username",
              },
            },
          },
        ],
      },
      aggs: {
        expires_soon: {
          filter: {
            range: {
              expiration: {
                lte: "now+30d/d",
              },
            },
          },
          aggs: {
            key_names: {
              terms: {
                field: "name",
              },
            },
          },
        },
      },
    },
  },
});
console.log(response);
POST /_security/_query/api_key
{
  "size": 0,
  "query": {
    "bool": {
      "must": {
        "term": {
          "invalidated": false  
        }
      },
      "should": [  
        {
          "range": { "expiration": { "gte": "now" } }
        },
        {
          "bool": { "must_not": { "exists": { "field": "expiration" } } }
        }
      ],
      "minimum_should_match": 1
    }
  },
  "aggs": {
    "keys_by_username": {
      "composite": {
        "sources": [ { "usernames": { "terms": { "field": "username" } } } ]  
      },
      "aggs": {
        "expires_soon": {
          "filter": {
            "range": { "expiration": { "lte": "now+30d/d" } }  
          },
          "aggs": {
            "key_names": { "terms": { "field": "name" } }
          }
        }
      }
    }
  }
}

Соответствующие API-ключи не должны быть аннулированы

Соответствующие API-ключи должны либо не истечь, либо не иметь даты истечения

Агрегировать все соответствующие ключи (т.е. все действительные ключи) по имени пользователя-владельца

Далее агрегировать действительные ключи на пользователя в группу с коротким сроком действия

Ответ

{
  "total" : 4,  
  "count" : 0,
  "api_keys" : [ ],
  "aggregations" : {
    "keys_by_username" : {
      "after_key" : {
        "usernames" : "king"
      },
      "buckets" : [
        {
          "key" : {
            "usernames" : "june"
          },
          "doc_count" : 2,  
          "expires_soon" : {
            "doc_count" : 1,
            "key_names" : {
              "doc_count_error_upper_bound" : 0,
              "sum_other_doc_count" : 0,
              "buckets" : [
                {
                  "key" : "june-key-10",
                  "doc_count" : 1
                }
              ]
            }
          }
        },
        {
          "key" : {
            "usernames" : "king"
          },
          "doc_count" : 2,
          "expires_soon" : {
            "doc_count" : 1,  
            "key_names" : {
              "doc_count_error_upper_bound" : 0,
              "sum_other_doc_count" : 0,
              "buckets" : [  
                {
                  "key" : "king-key-10",
                  "doc_count" : 1
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Общее количество действительных API-ключей (2 для каждого пользователя)

Количество действительных API-ключей для пользователя "june"

Количество действительных API-ключей, срок действия которых скоро истекает, для пользователя "king"

Имена API-ключей с коротким сроком действия для пользователя "king"

Для получения аннулированных (но еще не удаленных) API-ключей, сгруппированных по имени пользователя-владельца и имени API-ключа, выполните следующий запрос:

Запрос

resp = client.security.query_api_keys(
    size=0,
    query={
        "bool": {
            "filter": {
                "term": {
                    "invalidated": True
                }
            }
        }
    },
    aggs={
        "invalidated_keys": {
            "composite": {
                "sources": [
                    {
                        "username": {
                            "terms": {
                                "field": "username"
                            }
                        }
                    },
                    {
                        "key_name": {
                            "terms": {
                                "field": "name"
                            }
                        }
                    }
                ]
            }
        }
    },
)
print(resp)
const response = await client.security.queryApiKeys({
  size: 0,
  query: {
    bool: {
      filter: {
        term: {
          invalidated: true,
        },
      },
    },
  },
  aggs: {
    invalidated_keys: {
      composite: {
        sources: [
          {
            username: {
              terms: {
                field: "username",
              },
            },
          },
          {
            key_name: {
              terms: {
                field: "name",
              },
            },
          },
        ],
      },
    },
  },
});
console.log(response);
POST /_security/_query/api_key
{
  "size": 0,
  "query": {
    "bool": {
      "filter": {
        "term": {
          "invalidated": true
        }
      }
    }
  },
  "aggs": {
    "invalidated_keys": {
      "composite": {
        "sources": [
          { "username": { "terms": { "field": "username" } } },
          { "key_name": { "terms": { "field": "name" } } }
        ]
      }
    }
  }
}

Ответ

{
  "total" : 2,
  "count" : 0,
  "api_keys" : [ ],
  "aggregations" : {
    "invalidated_keys" : {
      "after_key" : {
        "username" : "king",
        "key_name" : "king-key-no-expire"
      },
      "buckets" : [
        {
          "key" : {
            "username" : "june",
            "key_name" : "june-key-100"
          },
          "doc_count" : 1
        },
        {
          "key" : {
            "username" : "king",
            "key_name" : "king-key-no-expire"
          },
          "doc_count" : 1
        }
      ]
    }
  }
}

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API