Query API key information API

APIキーに関する情報を取得します。これは、Query DSLを使用して、ページネーション形式で行われます。

Request

GET /_security/_query/api_key

POST /_security/_query/api_key

Prerequisites

  • このAPIを使用するには、少なくともmanage_own_api_keyまたはread_securityのクラスター権限が必要です。
  • manage_own_api_key権限のみを持っている場合、このAPIはあなたが所有するAPIキーのみを返します。read_security、manage_api_key、またはそれ以上の権限（manage_securityを含む）を持っている場合、このAPIは所有権に関係なくすべてのAPIキーを返します。

Description

このAPIを使用して、create API key APIで作成されたAPIキーをページネーション形式で取得します。オプションで、クエリを使用して結果をフィルタリングできます。

Path parameters

  • with_limited_by
  • （オプション、ブール値）APIキーに関連付けられた所有者ユーザーのロール記述子のスナップショットを返すためのブールフラグ。APIキーの実際の権限は、その割り当てられたロール記述子と所有者ユーザーのロール記述子の交差点です（実質的にそれによって制限されます）。APIキーは、manage_api_keyまたはそれ以上の権限を持っていない限り、他のAPIキーの制限されたロール記述子（自身を含む）を取得できません。
  • with_profile_uid
  • （オプション、ブール値）APIキーの所有者ユーザーのユーザープロファイルuidも取得するかどうかを決定します。存在する場合、プロファイルのUIDは各APIキーのprofile_uid応答フィールドに返されます。デフォルトはfalseです。
  • typed_keys
  • （オプション、ブール値）trueの場合、応答内の集約名はそれぞれのタイプによってプレフィックスされます。デフォルトはfalseです。

Request body

リクエストボディに次のパラメータを指定できます：

  • query
  • （オプション、オブジェクト）返すAPIキーをフィルタリングするためのクエリ。クエリパラメータが欠落している場合、それはmatch_allクエリと同等です。クエリは、match_all、bool、term、terms、match、ids、prefix、wildcard、exists、range、およびsimple query stringを含むクエリタイプのサブセットをサポートします。
    APIキーに関連付けられた次の公開値をクエリできます。
    APIキーに関連付けられたクエリ可能な文字列値は、内部的にkeywordsとしてマッピングされています。したがって、analyzerパラメータがmatchクエリに指定されていない場合、提供されたマッチクエリ文字列は単一のキーワード値として解釈されます。そのため、matchクエリはtermクエリと同等です。 
    1. - `````id
    • APIキーのID。注意：idはidsクエリでクエリする必要があります。
    • type
    • APIキーは、Create API keyまたはGrant API key APIを介して作成された場合はrestタイプ、またはCreate Cross-Cluster API key APIを介して作成された場合はcross_clusterタイプです。
    • 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、date range、missing、cardinality、value count、composite、filter、およびfiltersを含む集約タイプのサブセットのみをサポートします。さらに、集約は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
  • （オプション、配列）Search after定義。

Response body

このAPIは次のトップレベルフィールドを返します：

  • total
  • 見つかったAPIキーの総数。
  • count
  • 応答で返されたAPIキーの数。
  • api_keys
  • APIキー情報のリスト。

Examples

次のリクエストは、manage_api_key権限を持っていると仮定して、すべてのAPIキーをリストします：

Python

  1. resp = client.security.query_api_keys()
  2. print(resp)

Js

  1. const response = await client.security.queryApiKeys();
  2. console.log(response);

Console

  1. GET /_security/_query/api_key

成功した呼び出しは、1つ以上のAPIキーから取得した情報を含むJSON構造を返します：

Js

  1. {
  2.   "total": 3,
  3.   "count": 3,
  4.   "api_keys": [
  5.    {
  6.    "id": "nkvrGXsB8w290t56q3Rg",
  7.    "name": "my-api-key-1",
  8.    "creation": 1628227480421,
  9.    "expiration": 1629091480421,
  10.    "invalidated": false,
  11.    "username": "elastic",
  12.    "realm": "reserved",
  13.    "realm_type": "reserved",
  14.    "metadata": {
  15.    "letter": "a"
  16.    },
  17.    "role_descriptors": {
  18.    "role-a": {
  19.    "cluster": [
  20.    "monitor"
  21.    ],
  22.    "indices": [
  23.    {
  24.    "names": [
  25.    "index-a"
  26.    ],
  27.    "privileges": [
  28.    "read"
  29.    ],
  30.    "allow_restricted_indices": false
  31.    }
  32.    ],
  33.    "applications": [ ],
  34.    "run_as": [ ],
  35.    "metadata": { },
  36.    "transient_metadata": {
  37.    "enabled": true
  38.    }
  39.    }
  40.    }
  41.    },
  42.    {
  43.    "id": "oEvrGXsB8w290t5683TI",
  44.    "name": "my-api-key-2",
  45.    "creation": 1628227498953,
  46.    "expiration": 1628313898953,
  47.    "invalidated": false,
  48.    "username": "elastic",
  49.    "realm": "reserved",
  50.    "metadata": {
  51.    "letter": "b"
  52.    },
  53.    "role_descriptors": { }
  54.    }
  55.   ]
  56. }
このリクエストのために取得されたAPIキーのリスト
作成時にこのAPIキーに割り当てられたロール記述子。APIキーの有効な権限は、割り当てられた権限と所有者ユーザーの権限の時点でのスナップショットの交差点です。
空のロール記述子は、APIキーが所有者ユーザーの権限を継承していることを意味します。

次の詳細でAPIキーを作成した場合：

Python

  1. resp = client.security.create_api_key(
  2.    name="application-key-1",
  3.    metadata={
  4.    "application": "my-application"
  5.    },
  6. )
  7. print(resp)

Js

  1. const response = await client.security.createApiKey({
  2.   name: "application-key-1",
  3.   metadata: {
  4.    application: "my-application",
  5.   },
  6. });
  7. console.log(response);

Console

  1. POST /_security/api_key
  2. {
  3.   "name": "application-key-1",
  4.   "metadata": { "application": "my-application"}
  5. }

成功した呼び出しは、APIキー情報を提供するJSON構造を返します。例えば：

Console-Result

  1. {
  2.   "id": "VuaCfGcBCdbkQm-e5aOx",
  3.   "name": "application-key-1",
  4.   "api_key": "ui2lp2axTNmsyakw9tvNnw",
  5.   "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
  6. }

応答からの情報を使用して、IDでAPIキーを取得します：

Python

  1. resp = client.security.query_api_keys(
  2.    with_limited_by=True,
  3.    query={
  4.    "ids": {
  5.    "values": [
  6.    "VuaCfGcBCdbkQm-e5aOx"
  7.    ]
  8.    }
  9.    },
  10. )
  11. print(resp)

Js

  1. const response = await client.security.queryApiKeys({
  2.   with_limited_by: "true",
  3.   query: {
  4.    ids: {
  5.    values: ["VuaCfGcBCdbkQm-e5aOx"],
  6.    },
  7.   },
  8. });
  9. console.log(response);

Console

  1. GET /_security/_query/api_key?with_limited_by=true
  2. {
  3.   "query": {
  4.    "ids": {
  5.    "values": [
  6.    "VuaCfGcBCdbkQm-e5aOx"
  7.    ]
  8.    }
  9.   }
  10. }

成功した呼び出しは、制限されたロール記述子を含むAPIキー情報のJSON構造を返します：

Js

  1. {
  2.   "api_keys": [
  3.    {
  4.    "id": "VuaCfGcBCdbkQm-e5aOx",
  5.    "name": "application-key-1",
  6.    "creation": 1548550550158,
  7.    "expiration": 1548551550158,
  8.    "invalidated": false,
  9.    "username": "myuser",
  10.    "realm": "native1",
  11.    "realm_type": "native",
  12.    "metadata": {
  13.    "application": "my-application"
  14.    },
  15.    "role_descriptors": { },
  16.    "limited_by": [
  17.    {
  18.    "role-power-user": {
  19.    "cluster": [
  20.    "monitor"
  21.    ],
  22.    "indices": [
  23.    {
  24.    "names": [
  25.    "*"
  26.    ],
  27.    "privileges": [
  28.    "read"
  29.    ],
  30.    "allow_restricted_indices": false
  31.    }
  32.    ],
  33.    "applications": [ ],
  34.    "run_as": [ ],
  35.    "metadata": { },
  36.    "transient_metadata": {
  37.    "enabled": true
  38.    }
  39.    }
  40.    }
  41.    ]
  42.    }
  43.   ]
  44. }
APIキーに関連付けられた所有者ユーザーの権限。
それは作成時にキャプチャされた時点でのスナップショットであり、
その後の更新です。APIキーの有効な権限は、割り当てられた権限と
所有者ユーザーの権限の交差点です。

APIキーを名前で取得することもできます：

Python

  1. resp = client.security.query_api_keys(
  2.    query={
  3.    "term": {
  4.    "name": {
  5.    "value": "application-key-1"
  6.    }
  7.    }
  8.    },
  9. )
  10. print(resp)

Js

  1. const response = await client.security.queryApiKeys({
  2.   query: {
  3.    term: {
  4.    name: {
  5.    value: "application-key-1",
  6.    },
  7.    },
  8.   },
  9. });
  10. console.log(response);

Console

  1. GET /_security/_query/api_key
  2. {
  3.   "query": {
  4.    "term": {
  5.    "name": {
  6.    "value": "application-key-1"
  7.    }
  8.    }
  9.   }
  10. }
  3. #### Js
  5. ``````js
  6. GET /_security/_query/api_key
  7. {
  8.   "query": {
  9.    "bool": {
  10.    "must": [
  11.    {
  12.    "prefix": {
  13.    "name": "app1-key-"
  14.    }
  15.    },
  16.    {
  17.    "term": {
  18.    "invalidated": "false"
  19.    }
  20.    }
  21.    ],
  22.    "must_not": [
  23.    {
  24.    "term": {
  25.    "name": "app1-key-01"
  26.    }
  27.    }
  28.    ],
  29.    "filter": [
  30.    {
  31.    "wildcard": {
  32.    "username": "org-*-user"
  33.    }
  34.    },
  35.    {
  36.    "term": {
  37.    "metadata.environment": "production"
  38.    }
  39.    }
  40.    ]
  41.    }
  42.   },
  43.   "from": 20,
  44.   "size": 10,
  45.   "sort": [
  46.    { "creation": { "order": "desc", "format": "date_time" } },
  47.    "name"
  48.   ]
  49. }
  50. `
APIキー名はapp1-key-で始まる必要があります
APIキーはまだ有効である必要があります
APIキー名はapp1-key-01であってはなりません
APIキーは、ワイルドカードパターンorg-*-userのユーザー名によって所有されている必要があります
APIキーは、environmentのメタデータフィールドを持ち、その値がproductionである必要があります
検索結果のオフセットは20番目（ゼロベースのインデックス）APIキーです
応答のページサイズは10 APIキーです
結果は最初にcreation日付で降順にソートされ、その後名前で昇順にソートされます

応答には、一致したAPIキーのリストとそのソート値が含まれます：

Js

  1. {
  2.   "total": 100,
  3.   "count": 10,
  4.   "api_keys": [
  5.    {
  6.    "id": "CLXgVnsBOGkf8IyjcXU7",
  7.    "name": "app1-key-79",
  8.    "creation": 1629250154811,
  9.    "invalidated": false,
  10.    "username": "org-admin-user",
  11.    "realm": "native1",
  12.    "metadata": {
  13.    "environment": "production"
  14.    },
  15.    "role_descriptors": { },
  16.    "_sort": [
  17.    "2021-08-18T01:29:14.811Z",
  18.    "app1-key-79"
  19.    ]
  20.    },
  21.    {
  22.    "id": "BrXgVnsBOGkf8IyjbXVB",
  23.    "name": "app1-key-78",
  24.    "creation": 1629250153794,
  25.    "invalidated": false,
  26.    "username": "org-admin-user",
  27.    "realm": "native1",
  28.    "metadata": {
  29.    "environment": "production"
  30.    },
  31.    "role_descriptors": { },
  32.    "_sort": [
  33.    "2021-08-18T01:29:13.794Z",
  34.    "app1-key-78"
  35.    ]
  36.    },
  37.    ...
  38.   ]
  39. }
最初のソート値は作成時間で、リクエストで定義されたdate_time形式で表示されます
2番目のソート値はAPIキー名です

Aggregations Example

例えば、2人のユーザー「june」と「king」がそれぞれ3つのAPIキーを所有しているとします：

  • 期限切れにならないもの（ユーザー「king」のために無効化された）
  • 10日後に期限切れになるもの
  • 100日後に期限切れになるもの（ユーザー「june」のために無効化された）

次のリクエストは、すぐに期限切れになる（30日後）有効なAPIキーの名前を、所有者のユーザー名でグループ化して返します。

Request

Python

  1. resp = client.security.query_api_keys(
  2.    size=0,
  3.    query={
  4.    "bool": {
  5.    "must": {
  6.    "term": {
  7.    "invalidated": False
  8.    }
  9.    },
  10.    "should": [
  11.    {
  12.    "range": {
  13.    "expiration": {
  14.    "gte": "now"
  15.    }
  16.    }
  17.    },
  18.    {
  19.    "bool": {
  20.    "must_not": {
  21.    "exists": {
  22.    "field": "expiration"
  23.    }
  24.    }
  25.    }
  26.    }
  27.    ],
  28.    "minimum_should_match": 1
  29.    }
  30.    },
  31.    aggs={
  32.    "keys_by_username": {
  33.    "composite": {
  34.    "sources": [
  35.    {
  36.    "usernames": {
  37.    "terms": {
  38.    "field": "username"
  39.    }
  40.    }
  41.    }
  42.    ]
  43.    },
  44.    "aggs": {
  45.    "expires_soon": {
  46.    "filter": {
  47.    "range": {
  48.    "expiration": {
  49.    "lte": "now+30d/d"
  50.    }
  51.    }
  52.    },
  53.    "aggs": {
  54.    "key_names": {
  55.    "terms": {
  56.    "field": "name"
  57.    }
  58.    }
  59.    }
  60.    }
  61.    }
  62.    }
  63.    },
  64. )
  65. print(resp)

Js

  1. const response = await client.security.queryApiKeys({
  2.   size: 0,
  3.   query: {
  4.    bool: {
  5.    must: {
  6.    term: {
  7.    invalidated: false,
  8.    },
  9.    },
  10.    should: [
  11.    {
  12.    range: {
  13.    expiration: {
  14.    gte: "now",
  15.    },
  16.    },
  17.    },
  18.    {
  19.    bool: {
  20.    must_not: {
  21.    exists: {
  22.    field: "expiration",
  23.    },
  24.    },
  25.    },
  26.    },
  27.    ],
  28.    minimum_should_match: 1,
  29.    },
  30.   },
  31.   aggs: {
  32.    keys_by_username: {
  33.    composite: {
  34.    sources: [
  35.    {
  36.    usernames: {
  37.    terms: {
  38.    field: "username",
  39.    },
  40.    },
  41.    },
  42.    ],
  43.    },
  44.    aggs: {
  45.    expires_soon: {
  46.    filter: {
  47.    range: {
  48.    expiration: {
  49.    lte: "now+30d/d",
  50.    },
  51.    },
  52.    },
  53.    aggs: {
  54.    key_names: {
  55.    terms: {
  56.    field: "name",
  57.    },
  58.    },
  59.    },
  60.    },
  61.    },
  62.    },
  63.   },
  64. });
  65. console.log(response);

Console

  1. POST /_security/_query/api_key
  2. {
  3.   "size": 0,
  4.   "query": {
  5.    "bool": {
  6.    "must": {
  7.    "term": {
  8.    "invalidated": false
  9.    }
  10.    },
  11.    "should": [
  12.    {
  13.    "range": { "expiration": { "gte": "now" } }
  14.    },
  15.    {
  16.    "bool": { "must_not": { "exists": { "field": "expiration" } } }
  17.    }
  18.    ],
  19.    "minimum_should_match": 1
  20.    }
  21.   },
  22.   "aggs": {
  23.    "keys_by_username": {
  24.    "composite": {
  25.    "sources": [ { "usernames": { "terms": { "field": "username" } } } ]
  26.    },
  27.    "aggs": {
  28.    "expires_soon": {
  29.    "filter": {
  30.    "range": { "expiration": { "lte": "now+30d/d" } }
  31.    },
  32.    "aggs": {
  33.    "key_names": { "terms": { "field": "name" } }
  34.    }
  35.    }
  36.    }
  37.    }
  38.   }
  39. }
一致するAPIキーは無効化されてはなりません
一致するAPIキーは、期限切れでないか、期限切れの日付を持たない必要があります
一致するすべてのキー（すなわち、すべての有効なキー）を所有者のユーザー名で集約します
各ユーザー名の有効なキーをすぐに期限切れになるバケットにさらに集約します

Response

Console-Result

  1. {
  2.   "total" : 4,
  3.   "count" : 0,
  4.   "api_keys" : [ ],
  5.   "aggregations" : {
  6.    "keys_by_username" : {
  7.    "after_key" : {
  8.    "usernames" : "king"
  9.    },
  10.    "buckets" : [
  11.    {
  12.    "key" : {
  13.    "usernames" : "june"
  14.    },
  15.    "doc_count" : 2,
  16.    "expires_soon" : {
  17.    "doc_count" : 1,
  18.    "key_names" : {
  19.    "doc_count_error_upper_bound" : 0,
  20.    "sum_other_doc_count" : 0,
  21.    "buckets" : [
  22.    {
  23.    "key" : "june-key-10",
  24.    "doc_count" : 1
  25.    }
  26.    ]
  27.    }
  28.    }
  29.    },
  30.    {
  31.    "key" : {
  32.    "usernames" : "king"
  33.    },
  34.    "doc_count" : 2,
  35.    "expires_soon" : {
  36.    "doc_count" : 1,
  37.    "key_names" : {
  38.    "doc_count_error_upper_bound" : 0,
  39.    "sum_other_doc_count" : 0,
  40.    "buckets" : [
  41.    {
  42.    "key" : "king-key-10",
  43.    "doc_count" : 1
  44.    }
  45.    ]
  46.    }
  47.    }
  48.    }
  49.    ]
  50.    }
  51.   }
  52. }
有効なAPIキーの総数（各ユーザーに対して2）
ユーザー「june」の有効なAPIキーの数
ユーザー「king」のすぐに期限切れになる有効なAPIキーの数
ユーザー「king」のすぐに期限切れになるAPIキーの名前

無効化された（ただしまだ削除されていない）APIキーを、所有者のユーザー名とAPIキー名でグループ化して取得するには、次のリクエストを発行します：

Request

Python

  1. resp = client.security.query_api_keys(
  2.    size=0,
  3.    query={
  4.    "bool": {
  5.    "filter": {
  6.    "term": {
  7.    "invalidated": True
  8.    }
  9.    }
  10.    }
  11.    },
  12.    aggs={
  13.    "invalidated_keys": {
  14.    "composite": {
  15.    "sources": [
  16.    {
  17.    "username": {
  18.    "terms": {
  19.    "field": "username"
  20.    }
  21.    }
  22.    },
  23.    {
  24.    "key_name": {
  25.    "terms": {
  26.    "field": "name"
  27.    }
  28.    }
  29.    }
  30.    ]
  31.    }
  32.    }
  33.    },
  34. )
  35. print(resp)

Js

  1. const response = await client.security.queryApiKeys({
  2.   size: 0,
  3.   query: {
  4.    bool: {
  5.    filter: {
  6.    term: {
  7.    invalidated: true,
  8.    },
  9.    },
  10.    },
  11.   },
  12.   aggs: {
  13.    invalidated_keys: {
  14.    composite: {
  15.    sources: [
  16.    {
  17.    username: {
  18.    terms: {
  19.    field: "username",
  20.    },
  21.    },
  22.    },
  23.    {
  24.    key_name: {
  25.    terms: {
  26.    field: "name",
  27.    },
  28.    },
  29.    },
  30.    ],
  31.    },
  32.    },
  33.   },
  34. });
  35. console.log(response);

Console

  1. POST /_security/_query/api_key
  2. {
  3.   "size": 0,
  4.   "query": {
  5.    "bool": {
  6.    "filter": {
  7.    "term": {
  8.    "invalidated": true
  9.    }
  10.    }
  11.    }
  12.   },
  13.   "aggs": {
  14.    "invalidated_keys": {
  15.    "composite": {
  16.    "sources": [
  17.    { "username": { "terms": { "field": "username" } } },
  18.    { "key_name": { "terms": { "field": "name" } } }
  19.    ]
  20.    }
  21.    }
  22.   }
  23. }

Response

Console-Result

  1. {
  2.   "total" : 2,
  3.   "count" : 0,
  4.   "api_keys" : [ ],
  5.   "aggregations" : {
  6.    "invalidated_keys" : {
  7.    "after_key" : {
  8.    "username" : "king",
  9.    "key_name" : "king-key-no-expire"
  10.    },
  11.    "buckets" : [
  12.    {
  13.    "key" : {
  14.    "username" : "june",
  15.    "key_name" : "june-key-100"
  16.    },
  17.    "doc_count" : 1
  18.    },
  19.    {
  20.    "key" : {
  21.    "username" : "king",
  22.    "key_name" : "king-key-no-expire"
  23.    },
  24.    "doc_count" : 1
  25.    }
  26.    ]
  27.    }
  28.   }
  29. }