Elasticsearch 認可

ロールベースアクセス制御 (RBAC): ネイティブユーザー、ロール、ロール割り当て、および外部レルムのロールマッピングを管理します。

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

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

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

実現すべきこと

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

前提条件

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

不足している値についてはユーザーに入力を促します。

アクセス リクエストの分解

ユーザーが自然言語でアクセスについて説明する場合 (例: "logs-* への読み取り専用アクセスを持つユーザーを作成")、実行する前にリクエストを個別のタスクに分解します。次のワークフローに従います:

ステップ 1 — コンポーネントを特定する

プロンプトから抽出します:

コンポーネント	回答すべき質問
Who (誰)	新しいネイティブユーザー、既存ユーザー、または外部レルム ユーザー (LDAP、SAML など)
What (何)	どのインデックス、データ ストリーム、または Kibana フィーチャー
Access level (アクセス レベル)	読み取り、書き込み、管理、または特定の権限セット
Scope (スコープ)	すべてのドキュメント/フィールド、または地域、部門、機密度で制限?
Kibana?	リクエストは Kibana フィーチャー (ダッシュボード、Discover など) に言及していますか?
Deployment?	セルフマネージド、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. ユーザーを作成: POST /_security/user/analyst で roles: ["logs-metrics-dashboard-viewer"]。

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

ネイティブ ユーザー管理はセルフマネージドおよび 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、ダッシュボード、マップ、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 に等しいドキュメントのみを表示します。同じロールがすべての部門で機能します — 部門ごとのロールは不要です。

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

DLS と FLS の組み合わせ

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

ユーザーが複数のロールを保有する場合、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-access-management スキルを、完全なワークフロー (ユーザーの招待、ロール割り当て、Cloud API キー管理、アクセスの検証) に使用してください。このスキルはロール定義のみを処理し、cloud-access-management はユーザー割り当てを処理します。

例

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

リクエスト: "ユーザー joe を作成し、logs-* への読み取り専用アクセスを許可。"

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. indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }] を使用して apm-reader ロールを作成します。
3. PUT /_security/user/alice で "roles": ["viewer", "apm-reader"] (すべてのロールを含める) を使用します。

Serverless ユーザーに Kibana ダッシュボードを備えた読み取り/書き込みアクセスを付与する

リクエスト: "alice@example.com に、colors インデックスへの読み取り/書き込みアクセスと、ダッシュボードと Discover の使用を許可。"

1. Kibana API 経由でカスタム ロールを作成: PUT <KIBANA_URL>/api/security/role/colors-rw-kibana で elasticsearch.indices で colors への read、write、view_index_metadata と kibana[].feature で dashboard、discover を使用します。
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 を参照してください。