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キーサービス設定を参照してください。

成功したリクエストは、APIキー、そのユニークID、およびその名前を含むJSON構造を返します。該当する場合、APIキーのミリ秒単位の有効期限情報も返されます。

デフォルトでは、APIキーは期限切れになりません。APIキーを作成する際に有効期限情報を指定できます。

APIキーサービスに関連する設定については、APIキーサービス設定を参照してください。

リクエストボディ

POSTまたはPUTリクエストのボディに指定できるパラメータは次のとおりです：

  • name

  • (必須、文字列) このAPIキーの名前を指定します。

  • role_descriptors
  • (オプション、オブジェクト) このAPIキーのロール記述子。このパラメータはオプションです。指定されていない場合や空の配列の場合、APIキーは認証されたユーザーの権限のスナップショットを持ちます。ロール記述子を提供すると、結果として得られる権限はAPIキーの権限と認証されたユーザーの権限の交差となり、APIキーのアクセス範囲が制限されます。
    この権限の交差が計算される方法のため、他のAPIキーの子であるAPIキーを作成することはできません。派生キーが権限なしで作成される場合を除きます。この場合、権限のないロール記述子を明示的に指定する必要があります。派生APIキーは認証に使用できますが、Elasticsearch APIを呼び出す権限はありません。
    • 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キーを作成します：

Python

  1. resp = client.security.create_api_key(
  2.    name="my-api-key",
  3.    expiration="1d",
  4.    role_descriptors={
  5.    "role-a": {
  6.    "cluster": [
  7.    "all"
  8.    ],
  9.    "indices": [
  10.    {
  11.    "names": [
  12.    "index-a*"
  13.    ],
  14.    "privileges": [
  15.    "read"
  16.    ]
  17.    }
  18.    ]
  19.    },
  20.    "role-b": {
  21.    "cluster": [
  22.    "all"
  23.    ],
  24.    "indices": [
  25.    {
  26.    "names": [
  27.    "index-b*"
  28.    ],
  29.    "privileges": [
  30.    "all"
  31.    ]
  32.    }
  33.    ]
  34.    }
  35.    },
  36.    metadata={
  37.    "application": "my-application",
  38.    "environment": {
  39.    "level": 1,
  40.    "trusted": True,
  41.    "tags": [
  42.    "dev",
  43.    "staging"
  44.    ]
  45.    }
  46.    },
  47. )
  48. print(resp)

Js

  1. const response = await client.security.createApiKey({
  2.   name: "my-api-key",
  3.   expiration: "1d",
  4.   role_descriptors: {
  5.    "role-a": {
  6.    cluster: ["all"],
  7.    indices: [
  8.    {
  9.    names: ["index-a*"],
  10.    privileges: ["read"],
  11.    },
  12.    ],
  13.    },
  14.    "role-b": {
  15.    cluster: ["all"],
  16.    indices: [
  17.    {
  18.    names: ["index-b*"],
  19.    privileges: ["all"],
  20.    },
  21.    ],
  22.    },
  23.   },
  24.   metadata: {
  25.    application: "my-application",
  26.    environment: {
  27.    level: 1,
  28.    trusted: true,
  29.    tags: ["dev", "staging"],
  30.    },
  31.   },
  32. });
  33. console.log(response);

コンソール

  1. POST /_security/api_key
  2. {
  3.   "name": "my-api-key",
  4.   "expiration": "1d",
  5.   "role_descriptors": {
  6.    "role-a": {
  7.    "cluster": ["all"],
  8.    "indices": [
  9.    {
  10.    "names": ["index-a*"],
  11.    "privileges": ["read"]
  12.    }
  13.    ]
  14.    },
  15.    "role-b": {
  16.    "cluster": ["all"],
  17.    "indices": [
  18.    {
  19.    "names": ["index-b*"],
  20.    "privileges": ["all"]
  21.    }
  22.    ]
  23.    }
  24.   },
  25.   "metadata": {
  26.    "application": "my-application",
  27.    "environment": {
  28.    "level": 1,
  29.    "trusted": true,
  30.    "tags": ["dev", "staging"]
  31.    }
  32.   }
  33. }
生成されるAPIキーのオプションの有効期限。期限が指定されていない場合、APIキーは期限切れになりません。
このAPIキーのオプションのロール記述子。指定されていない場合、認証されたユーザーの権限が適用されます。

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

コンソール-結果

  1. {
  2.   "id": "VuaCfGcBCdbkQm-e5aOx",
  3.   "name": "my-api-key",
  4.   "expiration": 1544068612110,
  5.   "api_key": "ui2lp2axTNmsyakw9tvNnw",
  6.   "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
  7. }
このAPIキーのユニークid
このAPIキーのミリ秒単位のオプションの有効期限
生成されたAPIキー
idとapi_keyをコロン(:)で結合したUTF-8のBase64エンコーディングであるAPIキー資格情報。

生成されたAPIキーを使用するには、Authorizationヘッダーを含むリクエストを送信し、APIキー資格情報（レスポンスのencoded値）をApiKeyプレフィックスの後に続けます。

シェル

  1. curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" \
  2. http://localhost:9200/_cluster/health\?pretty
ノードにxpack.security.http.ssl.enabledがtrueに設定されている場合、APIキーを作成する際にhttpsを指定する必要があります。

Unix系システムでは、次のコマンドでencoded値を作成できます：

シェル

  1. echo -n "VuaCfGcBCdbkQm-e5aOx:ui2lp2axTNmsyakw9tvNnw" | base64<br>``````<br><br>
  2. |     |     |
  3. | --- | --- |
  4. |  | `````-n`````を使用して、`````echo`````コマンドが末尾の改行文字を印刷しないようにします。 |
  7. 次の例は、[制限](/read/elasticsearch-8-15/7b35463db0d2274b.md)を`````search_application_query`````ワークフローに適用してAPIキーを作成します。これにより、[Search Application Search API](/read/elasticsearch-8-15/e5fa8e999386c615.md)のみを呼び出すことができます：
  10. #### Python
  12. ``````python
  13. resp = client.security.create_api_key(
  14.    name="my-restricted-api-key",
  15.    role_descriptors={
  16.    "my-restricted-role-descriptor": {
  17.    "indices": [
  18.    {
  19.    "names": [
  20.    "my-search-app"
  21.    ],
  22.    "privileges": [
  23.    "read"
  24.    ]
  25.    }
  26.    ],
  27.    "restriction": {
  28.    "workflows": [
  29.    "search_application_query"
  30.    ]
  31.    }
  32.    }
  33.    },
  34. )
  35. print(resp)

Js

  1. const response = await client.security.createApiKey({
  2.   name: "my-restricted-api-key",
  3.   role_descriptors: {
  4.    "my-restricted-role-descriptor": {
  5.    indices: [
  6.    {
  7.    names: ["my-search-app"],
  8.    privileges: ["read"],
  9.    },
  10.    ],
  11.    restriction: {
  12.    workflows: ["search_application_query"],
  13.    },
  14.    },
  15.   },
  16. });
  17. console.log(response);

コンソール

  1. POST /_security/api_key
  2. {
  3.   "name": "my-restricted-api-key",
  4.   "role_descriptors": {
  5.    "my-restricted-role-descriptor": {
  6.    "indices": [
  7.    {
  8.    "names": ["my-search-app"],
  9.    "privileges": ["read"]
  10.    }
  11.    ],
  12.    "restriction":  {
  13.    "workflows": ["search_application_query"]
  14.    }
  15.    }
  16.   }
  17. }