› › ›

查询 API 密钥信息 API

编辑

查询 API 密钥信息 API编辑

以查询 DSL的方式，以分页的方式检索 API 密钥的信息。

请求编辑

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 密钥无法检索任何 API 密钥的 limited-by 角色描述符（包括自身），除非它具有 manage_api_key 或更高权限。
with_profile_uid: (可选，布尔值) 确定是否还检索用户配置文件 uid，用于 API 密钥拥有者用户。如果存在，则配置文件 uid 将在每个 API 密钥的 profile_uid 响应字段下返回。默认为 false。
typed_keys: (可选，布尔值) 如果为 true，则在响应中，聚合名称将以其各自的类型为前缀。默认为 false。

请求主体编辑

您可以在请求主体中指定以下参数

query

(可选，对象) 一个查询，用于过滤要返回的 API 密钥。如果查询参数缺失，则等效于 match_all 查询。该查询支持查询类型的子集，包括 match_all、bool、term、terms、match、ids、prefix、wildcard、exists、range 和 简单查询字符串

您可以查询与 API 密钥关联的以下公共值。

与 API 密钥关联的可查询字符串值在内部映射为关键字。因此，如果未为分析器参数指定匹配查询，则提供的匹配查询字符串将被解释为单个关键字值。因此，此类匹配查询等效于术语查询。

query 的有效值

id: API 密钥的 ID。注意 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。元数据在内部被索引为扁平化字段类型。这意味着所有字段在查询和排序时都像 关键字 字段一样。即使对于支持字段名称模式的查询类型，也不可能使用通配符模式（例如 metadata.field*）引用元数据字段的子集。最后，当仅提及 metadata（不带任何点和子字段名称）时，可以搜索所有元数据字段。

您无法查询 API 密钥的角色描述符。

aggs 或 aggregations

(可选，对象) 在返回的 API 密钥语料库上运行的任何聚合。聚合和查询协同工作。聚合仅针对与查询匹配的 API 密钥计算。这仅支持聚合类型的子集，即：术语、范围、日期范围、缺失、基数、值计数、复合、过滤器和过滤器。此外，聚合仅针对与 query 相同的字段子集运行。

from

(可选，整数) 起始文档偏移量。必须为非负数，默认为 0。

默认情况下，您无法使用 from 和 size 参数遍历超过 10,000 个命中项。要遍历更多命中项，请使用search_after 参数。

size

(可选，整数) 要返回的命中项数量。必须为非负数，默认为 10。 size 参数可以设置为 0，在这种情况下，不会返回任何 API 密钥匹配项，只会返回聚合结果。

默认情况下，您无法使用 from 和 size 参数遍历超过 10,000 个命中项。要遍历更多命中项，请使用search_after 参数。

sort

(可选，对象) 排序定义。除了 id 之外，API 密钥的所有公共字段都符合排序条件。此外，还可以对 _doc 字段应用排序，以按索引顺序排序。

search_after

(可选，数组) 搜索后定义。

响应主体编辑

此 API 返回以下顶级字段

total: 找到的 API 密钥总数。
count: 响应中返回的 API 密钥数量。
api_keys: API 密钥信息的列表。

示例编辑

以下请求列出所有 API 密钥，假设您拥有 manage_api_key 权限

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 密钥

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

使用响应中的信息按 ID 检索 API 密钥

GET /_security/_query/api_key?with_limited_by=true
{
  "query": {
    "ids": {
      "values": [
        "VuaCfGcBCdbkQm-e5aOx"
      ]
    }
  }
}

成功调用将返回一个 JSON 结构，用于 API 密钥信息，包括其 limited-by 角色描述符

{
  "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 密钥

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 密钥名称。

聚合示例编辑

例如，假设有两个用户“june”和“king”，每个用户拥有 3 个 API 密钥。

一个永不过期（对用户“king”无效）
一个在 10 天后过期
一个在 100 天后过期（对用户“june”无效）

以下请求返回有效（未过期且未失效）的 API 密钥名称，这些密钥即将过期（30 天内），并按所有者用户名分组。

请求编辑

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 个）。
	用户“june”的有效 API 密钥数量。
	用户“king”的即将过期的有效 API 密钥数量。
	用户“king”的即将过期的 API 密钥名称。

要检索失效（但尚未删除）的 API 密钥，并按所有者用户名和 API 密钥名称分组，请发出以下请求。

请求编辑

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

« OpenID Connect 注销 API 查询用户 API »