elasticsearch-authz

Elasticsearch の認可

Elasticsearch のロールベースのアクセス制御を管理します。ネイティブユーザー、ロール、ロールの割り当て、外部レルム向けのロールマッピングが対象です。

認証方式と API キーの管理については、elasticsearch-authn スキルを参照してください。

詳細な API エンドポイントについては、references/api-reference.md を参照してください。

デプロイに関する注意： 機能の利用可否は、セルフマネージド、ECH、Serverless で異なります。詳細は デプロイの互換性を参照してください。

実行するタスク

• 特定の権限セットを持つネイティブユーザーを作成する
• インデックスとクラスターへのアクセスを最小権限に制限したカスタムロールを定義する
• 既存ユーザーに1つ以上のロールを割り当てる
• Kibana の機能またはスペースの権限を持つロールを作成する
• 外部レルムのユーザー（SAML、LDAP、PKI）向けのロールマッピングを設定する
• ユーザー属性（Mustache テンプレート）からロールの割り当てを動的に導出する
• ユーザーまたは部門ごとにドキュメントの表示範囲を制限する（ドキュメントレベルセキュリティ）
• 特定のロールから PII などの機密フィールドを隠す（フィールドレベルセキュリティ）
• テンプレート化されたロールクエリを使って属性ベースのアクセス制御（ABAC）を実装する
• 自然言語によるアクセス要求を、ユーザー、ロール、ロールマッピングのタスクに変換する

前提条件

項目	説明
Elasticsearch URL	クラスターのエンドポイント（例：https://localhost:9200 または Cloud デプロイ URL）
Kibana URL	Kibana の機能またはスペースの権限を設定する場合にのみ必要
認証	有効な認証情報（elasticsearch-authn スキルを参照）
クラスター権限	ユーザーとロールの管理操作には manage_security が必要

不足している値があれば、ユーザーに確認してください。

アクセス要求の分解

ユーザーが自然言語でアクセス方法を説明した場合（例：「logs-* への読み取り専用アクセス権を持つユーザーを作成して」）、実行前に要求を個別のタスクに分解します。次のワークフローに従ってください。

ステップ 1 — 要素を特定する

プロンプトから次の情報を抽出します。

要素	確認する内容
対象者	新しいネイティブユーザー、既存ユーザー、または外部レルムのユーザー（LDAP、SAML など）
対象	対象となるインデックス、データストリーム、または Kibana の機能
アクセスレベル	読み取り、書き込み、管理、または特定の権限セット
範囲	すべてのドキュメント／フィールドか、地域、部門、機密度による制限があるか
Kibana?	Kibana の機能（ダッシュボード、Discover など）についての要求があるか
デプロイ環境?	セルフマネージド、ECH、または Serverless か。Serverless ではユーザーモデルが異なります。

ステップ 2 — 既存のロールを確認する

新しいロールを作成する前に、既存のロールで必要なアクセス権が付与されているか確認します。

curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>

一致するロールがあれば、ロールの作成を省略してそのロールを再利用します。

ステップ 3 — ロールを作成する（必要な場合）

要求に基づいてロール名と表示名を決めます。インデックス／クラスターのみのロールには Elasticsearch API を使用します。Kibana の機能が関係する場合は、Kibana API を使用します（適切な API の選択を参照）。

ステップ 4 — ユーザーを作成または更新する

シナリオ	操作
新しいネイティブユーザー	ロールと、生成した強力なパスワードを設定してユーザーを作成します。（セルフマネージド／ECH のみ。）
既存のネイティブユーザー	現在のロールを取得して新しいロールを追加し、完全な配列を指定してユーザーを更新します。（セルフマネージド／ECH のみ。）
外部レルムのユーザー	ユーザーのレルム属性とロールが一致するロールマッピングを作成します。（セルフマネージド／ECH のみ。）
Serverless ユーザー	cloud-access-management スキルを使用します。事前定義されたロールを割り当てるか、先にカスタムロールを作成してから、Cloud API 経由で割り当てます。

分解の例

プロンプト：「analyst ユーザーを作成し、logs-* と metrics-* への読み取り専用アクセス、および Kibana のダッシュボード表示権限を付与してください。」

1. 特定します：新規ユーザー analyst、インデックス logs-*／metrics-*、ダッシュボード、読み取りアクセス。
2. ロールを確認します：GET /_security/role — 一致するものはありません。
3. Kibana API 経由でロールを作成します（ダッシュボードが関係するため）：logs-metrics-dashboard-viewer。
4. ユーザーを作成します：roles: ["logs-metrics-dashboard-viewer"] を指定して POST /_security/user/analyst を実行します。

リクエストが曖昧な場合は、各手順をユーザーに確認してください。

ネイティブユーザーを管理する

ネイティブユーザーの管理は、セルフマネージドおよび ECH のデプロイに適用されます。Serverless ではユーザーを組織レベルで管理するため、 このセクションはスキップしてください。

ユーザーを作成する

curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "password": "'"${PASSWORD}"'",
    "roles": ["'"${ROLE_NAME}"'"],
    "full_name": "'"${FULL_NAME}"'",
    "email": "'"${EMAIL}"'",
    "enabled": true
  }'

ユーザーを更新する

変更するフィールドを指定して PUT /_security/user/${USERNAME} を使用します。既存のパスワードを維持するには、password を省略します。

その他のユーザー操作

curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_password" \
  <auth_flags> -H "Content-Type: application/json" \
  -d '{"password": "'"${NEW_PASSWORD}"'"}'
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_disable" <auth_flags>
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_enable" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>

ロールを管理する

適切な API を選択する

ロールに cluster と indices の権限のみが必要な場合は、Elasticsearch API（PUT /_security/role/{name}）を使用します。これがデフォルトであり、Kibana のエンドポイントは必要ありません。

ロールに Kibana の機能またはスペースの権限が含まれる場合は、Kibana ロール API（PUT /api/security/role/{name}）を使用します。Elasticsearch API では、Kibana の機能付与、スペースのスコープ設定、ベース権限を設定できません。そのため、ユーザーが Discover、Dashboards、Maps、Visualize、Canvas、その他の Kibana アプリケーションなどの Kibana 機能に言及した場合は、Kibana API が必要です。

Kibana のエンドポイントを利用できない場合、または Kibana への API キー認証に失敗した場合は、cluster と indices の部分に Elasticsearch API を使用し、Kibana の権限を設定できなかったことをユーザーに伝えてください。あきらめる前に、Kibana の URL または別の認証情報を求めてください。

ロールを作成または更新する（Elasticsearch API）

ロールの権限がインデックスとクラスターのみの場合のデフォルトの選択肢です。

curl -X PUT "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "cluster": [],
    "indices": [
      {
        "names": ["'"${INDEX_PATTERN}"'"],
        "privileges": ["read", "view_index_metadata"]
      }
    ]
  }'

ロールを作成または更新する（Kibana API）

ロールに Kibana の機能またはスペースの権限が含まれる場合に必要です。

curl -X PUT "${KIBANA_URL}/api/security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "elasticsearch": {
      "cluster": [],
      "indices": [
        {
          "names": ["'"${INDEX_PATTERN}"'"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    },
    "kibana": [
      {
        "base": [],
        "feature": {
          "discover": ["read"],
          "dashboard": ["read"]
        },
        "spaces": ["*"]
      }
    ]
  }'

ロールを取得、一覧表示、削除する

curl "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>

ドキュメントレベルおよびフィールドレベルのセキュリティ

ロールでは、インデックスレベルの権限に加えて、インデックス内のドキュメントレベルおよびフィールドレベルでアクセスを制限できます。

フィールドレベルのセキュリティ（FLS）

ロールが表示できるフィールドを制限します。grant を使用して許可リストを指定するか、except を使用して拒否リストを指定します。

curl -X PUT "${ELASTICSEARCH_URL}/_security/role/pii-redacted-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "PII Redacted Reader",
    "indices": [
      {
        "names": ["customers-*"],
        "privileges": ["read"],
        "field_security": {
          "grant": ["*"],
          "except": ["ssn", "credit_card", "date_of_birth"]
        }
      }
    ]
  }'

このロールを持つユーザーには、PII フィールドを除くすべてのフィールドが表示されます。FLS は、検索、取得、集計の結果に適用されます。

ドキュメントレベルのセキュリティ（DLS）

クエリフィルターを設定して、ロールが表示できるドキュメントを制限します。

curl -X PUT "${ELASTICSEARCH_URL}/_security/role/emea-logs-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "EMEA Logs Reader",
    "indices": [
      {
        "names": ["logs-*"],
        "privileges": ["read"],
        "query": "{\"term\": {\"region\": \"emea\"}}"
      }
    ]
  }'

query フィールドは、Query DSL フィルターを含む JSON 文字列です。このロールを持つユーザーには、region が emea と等しいドキュメントのみが表示されます。

テンプレート化された DLS クエリ（ABAC）

DLS クエリは、クエリ時にユーザーメタデータを注入する Mustache テンプレートをサポートしており、RBAC の上に属性ベースのアクセス制御（ABAC）を実現できます。ユーザー固有の属性をユーザーの metadata フィールドに保存し、ロールクエリテンプレート内で {{_user.metadata.<key>}} を使って参照します。

curl -X PUT "${ELASTICSEARCH_URL}/_security/role/department-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Department Reader",
    "indices": [
      {
        "names": ["records-*"],
        "privileges": ["read"],
        "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
      }
    ]
  }'

"metadata": {"department": "engineering"} を持つユーザーは、department が engineering と等しいドキュメントのみを表示できます。同じロールがすべての部門で機能します — 部門ごとのロールは不要です。

複数値の属性（例: 必要なプログラムのリスト）には、minimum_should_match_field を指定した terms_set を使用して、ユーザーがドキュメントに記載されたすべての必須属性を保持していることを保証します。これにより、単一のロールを使って、セキュリティレベル、プログラムリスト、認定日を組み合わせた複雑な ABAC ポリシーを実現できます。複数条件を組み合わせたポリシーやユーザーメタデータの設定を含む terms_set ABAC の完全な例については、references/api-reference.md を参照してください。

DLS と FLS の組み合わせ

単一のインデックス権限エントリに query（DLS）と field_security（FLS）の両方を含めることができます。実用的な組み合わせのユースケースについては、人事部門の例を参照してください。

ユーザーが複数のロールを保持している場合、DLS クエリは OR で結合され、FLS の許可は和集合となります。DLS/FLS のない広範なロールは、意図せずアクセスを広げてしまう可能性があります。ロールを組み合わせる際は、常に実効権限を確認し、無制限のロールが DLS/FLS の意図を上書きしないようにしてください。

ユーザーにロールを割り当てる

セルフマネージドおよび ECH のみ。Serverless では cloud-access-management スキルを使用してください — Serverless ユーザーアクセスを参照。

新しい roles 配列でユーザーを更新します:

curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["role-a", "role-b"]
  }'

roles 配列は完全に置き換えられます — ユーザーが持つべきすべてのロールを含めてください。更新前に、まずユーザーを取得して現在のロールを確認してください。

実効権限を確認する

ロールまたはユーザーの更新後、次のコマンドで実効アクセスを確認します:

curl -X POST "${ELASTICSEARCH_URL}/_security/user/_has_privileges" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "cluster": ["monitor"],
    "index": [
      {
        "names": ["'"${INDEX_PATTERN}"'"],
        "privileges": ["read", "view_index_metadata"]
      }
    ]
  }'

ロールマッピングを管理する

ロールマッピングは Serverless では利用できません（ES API と Kibana UI の両方が無効になっています）。代わりに cloud-access-management スキルを使用してください — Serverless ユーザーアクセスを参照。

ロールマッピングは、外部レルムのユーザー（LDAP、AD、SAML、PKI）を属性ルールに基づいてロールに割り当てます。セルフマネージドおよび ECH のみです。サポートされているルール演算子とリソースフィールドについては、ロールマッピングリソースのプロパティを参照してください。

静的なロールマッピング

curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["viewer"],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "saml1" }
    }
  }'

LDAP グループベースのマッピング

curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-admins" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["superuser"],
    "enabled": true,
    "rules": {
      "all": [
        { "field": { "realm.name": "ldap1" } },
        { "field": { "groups": "cn=admins,ou=groups,dc=example,dc=com" } }
      ]
    }
  }'

Mustache テンプレートによる動的なロール割り当て

roles の代わりに role_templates を使用して、ユーザー属性からロール名を導出します。スクリプトを有効にする必要があります。

curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-group-roles" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "role_templates": [
      {
        "template": { "source": "{{#tojson}}groups{{/tojson}}" },
        "format": "json"
      }
    ],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "ldap1" }
    }
  }'

レルムユーザー名から導出されるロールや階層化されたグループアクセスなど、その他の Mustache パターンについては、references/api-reference.md を参照してください。

ロールマッピングの取得、一覧表示、削除

curl "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role_mapping" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>

Serverless ユーザーアクセス

Serverless には、ネイティブのユーザーやロールマッピングはありません。ユーザーは Cloud レベルのロール割り当てを通じてプロジェクトへのアクセスを取得します。

• 定義済みロール（例: admin、developer、viewer）は一般的なアクセスパターンをカバーします。適合するものがあれば、Cloud API を通じて直接割り当ててください — カスタムロールの作成は不要です。
• カスタムロールは、ユーザーがきめ細かいアクセス（特定のインデックス、Kibana 機能、DLS/FLS）を必要とする場合に必要です。Elasticsearch API または Kibana API を使用してカスタムロールを作成し（セルフマネージドと同じ — ロールを管理するを参照）、Cloud API を通じて定義済みのベースロールとともにユーザーに割り当てます。
• Run-as 権限は Serverless のカスタムロールでは利用できません。

完全なワークフロー（ユーザーの招待、ロールの割り当て、Cloud API キーの管理、アクセスの確認）については、cloud-access-management スキルを使用してください。このスキルはロールの定義のみを扱います。ユーザーの割り当ては cloud-access-management が処理します。

例

ログ用の読み取り専用ユーザーを作成する

リクエスト: 「logs-* への読み取り専用アクセス権を持つユーザー joe を作成してください。」

1. PUT /_security/role/logs-reader でロールを作成します。"description": "Logs Reader" と indices: [{ names: ["logs-*"], privileges: ["read", "view_index_metadata"] }] を指定します。
2. POST /_security/user/joe でユーザーを作成します。"roles": ["logs-reader"] と、生成した強力なパスワードを指定します。

Kibana ダッシュボードアクセス権を持つロールを作成する

リクエスト: 「ユーザーが logs-* を読み取り、Kibana でダッシュボードを閲覧できるようにしてください。」

Kibana API（PUT <KIBANA_URL>/api/security/role/logs-dashboard-viewer）を使用し、データアクセスには elasticsearch.indices を、 すべてのスペースでのダッシュボードと Discover の読み取りアクセスには kibana[].feature を指定します。リクエストの完全な構造については ロールの作成または更新（Kibana API）を参照してください。

既存のユーザーにロールを追加する

リクエスト: 「Alice に現在のロールに加えて apm-* へのアクセス権を付与してください。」

1. GET /_security/user/alice — レスポンスに "roles": ["viewer"] が表示されます。
2. apm-reader ロールを indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }] で作成します。
3. PUT /_security/user/alice を "roles": ["viewer", "apm-reader"] で実行します（すべてのロールを含めます）。

Serverless ユーザーに Kibana ダッシュボード付きの読み書きアクセス権を付与する

リクエスト: 「[email protected] に colors インデックスへの読み書きアクセス権を付与し、ダッシュボードと Discover を使用できるようにしてください。」

1. Kibana API でカスタムロールを作成します: PUT <KIBANA_URL>/api/security/role/colors-rw-kibana に、 colors に対する read、write、view_index_metadata のための elasticsearch.indices と、 dashboard、discover のための kibana[].feature を指定します。
2. cloud-access-management スキルを使用して、ユーザーにカスタムロール colors-rw-kibana を割り当てます。

部門別に HR データを制限する（DLS + FLS）

リクエスト: 「各マネージャーは自分の部門の HR レコードのみを閲覧でき、PII フィールドは非表示にしてください。」

1. 部門メタデータを持つユーザーを作成します: POST /_security/user/manager_a に "metadata": {"department": "engineering"} を指定します。
2. DLS + FLS を持つロールを作成します:

PUT /_security/role/hr-department-viewer
{
  "description": "HR Department Viewer",
  "indices": [
    {
      "names": ["hr-*"],
      "privileges": ["read"],
      "field_security": { "grant": ["*"], "except": ["ssn", "salary", "date_of_birth"] },
      "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
    }
  ]
}

同じロールがすべての部門で機能します — 各ユーザーは PII フィールドが削除された、自分の部門のレコードのみを閲覧します。

ガイドライン

最小権限の原則

• 日々の運用に elastic スーパーユーザーを決して使用しないでください。専用の最小権限ロールを作成し、 elastic は初期セットアップと緊急時の復旧用に取っておいてください。
• 読み取り専用のデータアクセスには read と view_index_metadata を使用してください。明示的に必要でない限り cluster は空のままにしてください。
• インデックス内のアクセスを制限するには DLS（query）と FLS（field_security）を使用してください。

名前付き権限のみ

内部アクション名（例: indices:data/read/search）を決して使用しないでください。常に公式に文書化された名前付き権限を使用してください。 広範な権限（manage、all）よりも細かい権限（manage_ingest_pipelines、monitor）を優先してください。権限の完全なリファレンス表については references/api-reference.mdを参照してください。

ロールの命名規則

• ハイフン付きの短い小文字名を使用してください: logs-reader、apm-data-viewer、metrics-writer。
• custom-role や new-role のような一般的な名前は避けてください。
• description には長い文ではなく、短く人間が読める表示名を設定してください。これは Kibana UI でロールの ラベルとして表示されます。良い例: "Logs Reader"、"APM Data Viewer"。悪い例: "Read-only access to all logs-* indices for the operations team"。

ユーザー管理

• デフォルトで強力なパスワードを生成してください: 大文字、小文字、数字、記号を混ぜた少なくとも 16 文字（例: X9k#mP2vL!qR7wZn）。changeme や password123 のようなプレースホルダー値は決して使用しないでください。
• 監査証跡を保持するため、ユーザーの削除よりも無効化を優先してください。
• ユーザーの roles 配列は更新時に完全に置き換えられます。変更する前に必ず現在のロールを取得してください。

ロールマッピングのベストプラクティス

• 単純で固定された割り当て（例：すべての SAML ユーザーに viewer を付与する場合）には、静的な roles を使用します。
• ユーザー属性からロールを動的に導出する必要がある場合に限り、Mustache を使用した role_templates を使用します。
• all、any、field、except のルールを組み合わせることで、マッピングを重複させずに複雑な条件を表現できます。
• 新しいマッピングはまず enabled: false でテストし、検証が済んでから有効にします。

デプロイの互換性

機能マトリックスと、セルフマネージド、ECH、Serverless のデプロイの違いに関する詳細な説明については、references/deployment-compatibility.md を参照してください。