クロスクラスタAPIキーの作成（Create Cross-Cluster API key）

クロスクラスターAPIキーAPIの作成

APIキーのcross_clusterタイプを作成し、APIキーに基づくリモートクラスターへのアクセスを提供します。cross_cluster APIキーは、RESTインターフェースを通じて認証に使用することはできません。逆に、REST APIキーはRESTインターフェースを通じて使用することを目的としており、APIキーに基づくリモートクラスターアクセスには使用できません。

リクエスト

POST /_security/cross_cluster/api_key

前提条件

• このAPIを使用するには、少なくともmanage_securityクラスターの権限が必要です。

このリクエストを認証するには、APIキーではない資格情報を使用する必要があります。必要な権限を持つAPIキーを使用しても、APIはエラーを返します。

説明

クロスクラスターAPIキーは、Elasticsearch APIキーサービスによって作成され、自動的に有効になります。APIキーサービスを無効にする手順については、APIキーサービス設定を参照してください。

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

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

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

クロスクラスターAPIキーは、クロスクラスターAPIキーの更新APIを使用してのみ更新できます。REST APIキーの更新APIやバルク更新REST APIキーAPIを使用して更新しようとするとエラーが発生します。これらは、APIキー取得API、APIキークエリAPI、およびAPIキー無効化APIを使用して取得および無効化できます。

リクエストボディ

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

• name

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

• access
• (必須、オブジェクト) このAPIキーに付与されるアクセス権。アクセス権は、クロスクラスター検索およびクロスクラスターレプリケーションの権限で構成されます。少なくとも1つは指定する必要があります。
  • search
  • (オプション、リスト) クロスクラスター検索のためのインデックス権限エントリのリスト。
    • names
    • (必須、リスト) このエントリの権限が適用されるインデックスまたは名前パターンのリスト。
    • field_security
    • (オプション、オブジェクト) ロールの所有者が読み取りアクセスを持つドキュメントフィールド。replicationフィールドが定義されている場合は設定できません。詳細については、クロスクラスターAPIキーによるフィールドおよびドキュメントレベルのセキュリティを参照してください。
    • query
    • (オプション) ロールの所有者が読み取りアクセスを持つドキュメントを定義する検索クエリ。この指定されたインデックス内のドキュメントは、ロールの所有者がアクセスできるようにするためにこのクエリに一致する必要があります。replicationフィールドが定義されている場合は設定できません。詳細については、クロスクラスターAPIキーによるフィールドおよびドキュメントレベルのセキュリティを参照してください。
    • allow_restricted_indices
    • (オプション、ブール値) namesフィールドのパターンがシステムインデックスをカバーする必要がある場合は、trueに設定する必要があります（デフォルトはfalse）。
  • replication
  • (オプション、リスト) クロスクラスターレプリケーションのためのインデックス権限エントリのリスト。
    • names
    • (必須、リスト) このエントリの権限が適用されるインデックスまたは名前パターンのリスト。

検索またはレプリケーションアクセスのために明示的な権限を指定する必要はありません。作成プロセスは、access仕様をロール記述子に自動的に変換し、関連する権限が適切に割り当てられます。access値とその対応するrole_descriptorsは、APIキー取得APIおよびAPIキークエリAPIのレスポンスに返されます。

REST APIキーとは異なり、クロスクラスターAPIキーは認証されたユーザーの権限をキャプチャしません。APIキーの有効な権限は、accessパラメータで指定されたものと正確に一致します。

• expiration
• (オプション、文字列) APIキーの有効期限。デフォルトでは、APIキーは期限切れになりません。
• metadata
• (オプション、オブジェクト) APIキーに関連付けたい任意のメタデータ。ネストされたデータ構造をサポートします。metadataオブジェクト内では、_で始まるキーはシステム使用のために予約されています。

例

次の例は、クロスクラスターAPIキーを作成します：

Python

resp = client.perform_request(
   "POST",
   "/_security/cross_cluster/api_key",
   headers={"Content-Type": "application/json"},
   body={
   "name": "my-cross-cluster-api-key",
   "expiration": "1d",
   "access": {
   "search": [
   {
   "names": [
   "logs*"
   ]
   }
   ],
   "replication": [
   {
   "names": [
   "archive*"
   ]
   }
   ]
   },
   "metadata": {
   "description": "phase one",
   "environment": {
   "level": 1,
   "trusted": True,
   "tags": [
   "dev",
   "staging"
   ]
   }
   }
   },
)
print(resp)

Js

const response = await client.transport.request({
  method: "POST",
  path: "/_security/cross_cluster/api_key",
  body: {
   name: "my-cross-cluster-api-key",
   expiration: "1d",
   access: {
   search: [
   {
   names: ["logs*"],
   },
   ],
   replication: [
   {
   names: ["archive*"],
   },
   ],
   },
   metadata: {
   description: "phase one",
   environment: {
   level: 1,
   trusted: true,
   tags: ["dev", "staging"],
   },
   },
  },
});
console.log(response);

コンソール

POST /_security/cross_cluster/api_key
{
  "name": "my-cross-cluster-api-key",
  "expiration": "1d",
  "access": {
   "search": [
   {
   "names": ["logs*"]
   }
   ],
   "replication": [
   {
   "names": ["archive*"]
   }
   ]
  },
  "metadata": {
   "description": "phase one",
   "environment": {
   "level": 1,
   "trusted": true,
   "tags": ["dev", "staging"]
   }
  }
}

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

コンソール-結果

{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "my-cross-cluster-api-key",
  "expiration": 1544068612110,
  "api_key": "ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

APIキー情報は、APIキー取得APIを使用して取得できます。

Python

resp = client.security.get_api_key(
   id="VuaCfGcBCdbkQm-e5aOx",
)
print(resp)

Js

const response = await client.security.getApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
});
console.log(response);

コンソール

GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx

成功した呼び出しは、APIキーの情報を含むJSON構造を返します：

Js

{
  "api_keys": [
   {
   "id": "VuaCfGcBCdbkQm-e5aOx",
   "name": "my-cross-cluster-api-key",
   "type": "cross_cluster",
   "creation": 1548550550158,
   "expiration": 1548551550158,
   "invalidated": false,
   "username": "myuser",
   "realm": "native1",
   "metadata": {
   "description": "phase one",
   "environment": {
   "level": 1,
   "trusted": true,
   "tags": ["dev", "staging"]
   }
   },
   "role_descriptors": {
   "cross_cluster": {
   "cluster": [
   "cross_cluster_search", "cross_cluster_replication"
   ],
   "indices": [
   {
   "names": [
   "logs*"
   ],
   "privileges": [
   "read", "read_cross_cluster", "view_index_metadata"
   ],
   "allow_restricted_indices": false
   },
   {
   "names": [
   "archive*"
   ],
   "privileges": [
   "cross_cluster_replication", "cross_cluster_replication_internal"
   ],
   "allow_restricted_indices": false
   }
   ],
   "applications": [ ],
   "run_as": [ ],
   "metadata": { },
   "transient_metadata": {
   "enabled": true
   }
   }
   },
   "access": {
   "search": [
   {
   "names": [
   "logs*"
   ],
   "allow_restricted_indices": false
   }
   ],
   "replication": [
   {
   "names": [
   "archive*"
   ],
   "allow_restricted_indices": false
   }
   ]
   }
   }
  ]
}

生成されたAPIキーを使用するには、APIキーに基づくリモートクラスター構成の一部として、クラスター資格情報として構成します。