Elasticsearch 認証

既に構成されている任意の認証レルムを使用して Elasticsearch クラスターに認証します。このスキルは、すべての組み込みレルム、認証情報の検証、および完全な API キーのライフサイクルをカバーしています。

ロール、ユーザー、ロール割り当て、ロール マッピングについては、elasticsearch-authz スキルを参照してください。

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

デプロイメント注記: すべてのレルムが全てのデプロイメント タイプで利用可能とは限りません。自己管理対 ECH 対 Serverless の詳細については、デプロイメント互換性 を参照してください。

重要な原則

• チャットで認証情報を要求しない。 パスワード、API キー、トークン、またはシークレットをチャットに貼り付けるよう要求しないでください。シークレットはチャット履歴に表示されてはいけません。
• 常に環境変数を使用する。 このスキルのすべてのコード例は環境変数を参照します (例：ELASTICSEARCH_PASSWORD、ELASTICSEARCH_API_KEY)。必要な変数が不足している場合は、プロジェクト ルートの .env ファイルに設定するよう指示してください。決して直接値の入力を促さないでください。
• .env をターミナル エクスポートより優先する。 エージェントはサンドボックス化されたシェル セッションで実行される場合があり、ユーザーのターミナル環境を継承しません。ワーキング ディレクトリの .env ファイルは、すべての実行コンテキストで確実に機能します。export を提案するのはユーザーが明示的に優先する場合のみです。

実現すべき仕事

• ユーザー名とパスワード (ネイティブ レルム) を使用してクラスターに認証する
• API キー (ベアラー トークン) を使用して接続する
• 現在認証されているユーザーを確認する (_authenticate)
• デプロイメントに適切な認証レルムを選択する
• オートメーションまたはサービス アクセス用に特定の権限を持つ API キーを作成する
• 既存の API キーをローテーションまたは無効化する
• Elastic スタック コンポーネント用のサービス アカウント トークンを設定する
• PKI/TLS の設定後、PKI/相互 TLS 証明書ベースの認証を使用して認証する
• 構成された外部 ID プロバイダー (SAML、OIDC、LDAP、AD、Kerberos) を使用して認証する
• 他のユーザーに代わって API キーを付与する

前提条件

項目	説明
Elasticsearch URL	クラスター エンドポイント (例：https://localhost:9200 または Cloud デプロイメント URL)
認証情報	レルムに依存 — 以下のメソッドを参照
レルム構成済み	認証レルムと ID バックエンドが既に構成されている (レルム チェーン、IdP、LDAP/AD、Kerberos、PKI/TLS)

必要な値が不足している場合は、プロジェクト ルートの .env ファイルに追加するよう指示してください。ターミナル エクスポートは別のシェル セッションで実行されているエージェントには表示されない場合があります — .env ファイルが信頼できるデフォルトです。チャットに認証情報を貼り付けるようユーザーに要求しないでください — シークレットはチャット履歴に表示されてはいけません。

認証レルム

Elasticsearch は構成された順序 (レルム チェーン) でレルムを評価します。リクエストを認証できる最初のレルムが機能します。内部レルムは Elasticsearch により管理されます。外部レルムはエンタープライズ ID システムに委譲します。

内部レルム

ネイティブ (ユーザー名とパスワード)

専用の Elasticsearch インデックスに保存されたユーザー。対話的な使用に最も簡単な方法です。Kibana またはユーザー管理 API を使用して管理されます (elasticsearch-authz スキルを参照)。

curl -u "${ELASTICSEARCH_USERNAME}:${ELASTICSEARCH_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

ファイル

各クラスター ノード上のフラット ファイルで定義されたユーザー (elasticsearch-users CLI)。ライセンス状態に関係なく常にアクティブで、有償レルムが無効になっている場合のディザスター リカバリーのフォールバックになります。自己管理デプロイメントでのみ利用可能です。

curl -u "${FILE_USER}:${FILE_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

外部レルム

LDAP

外部 LDAP ディレクトリに対してユーザー名とパスワードを使用して認証します。自己管理のみ — ECH または Serverless では利用できません。通常、LDAP グループを Elasticsearch ロールに変換するためのロール マッピングと組み合わせて使用されます。

curl -u "${LDAP_USER}:${LDAP_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

このリクエストはネイティブと同じです — Elasticsearch はレルム チェーン経由で LDAP レルムにルーティングします。

Active Directory

Active Directory ドメインに対して認証します。自己管理のみ — ECH または Serverless では利用できません。LDAP に似ていますが、AD 固有のデフォルト (ユーザー プリンシパル名、sAMAccountName) を使用します。通常、AD グループから Elasticsearch ロールへの変換用のロール マッピングと組み合わせて使用されます。

curl -u "${AD_USER}:${AD_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

PKI (TLS クライアント証明書)

TLS ハンドシェイク中に提示される X.509 クライアント証明書を使用して認証します。PKI レルムと HTTP レイヤーの TLS が必要です。ECH では PKI サポートが限定されているため、デプロイメント設定を確認してください。Serverless では利用できません。相互 TLS 環境でのサービス間通信に最適です。

curl --cert "${CLIENT_CERT}" --key "${CLIENT_KEY}" --cacert "${CA_CERT}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

SAML

主に Kibana 認証用の SAML 2.0 Web ブラウザー SSO を有効にします。自己管理では、elasticsearch.yml で構成します。ECH では、Cloud デプロイメント設定 UI を通じて構成します。Serverless では、SAML は組織レベルで処理され、プロジェクトごとに構成することはできません。標準 REST クライアントでは使用できません — ブラウザー ベースのリダイレクト フローは Kibana によって処理されます。プログラマティック API アクセス用に別のレルム (ネイティブまたは API キーなど) を SAML 並びに構成してください。

OIDC (OpenID Connect)

主に Kibana 認証用の OpenID Connect SSO を有効にします。自己管理では、elasticsearch.yml で構成します。ECH では、Cloud デプロイメント設定 UI を通じて構成します。Serverless では利用できません。SAML と同様に、ブラウザー リダイレクトに依存しており、直接 REST クライアントの使用には適していません。OIDC に並びプログラマティック アクセス用に、API キーまたはネイティブ ユーザーを使用してください。

カスタム アプリケーションは POST /_security/oidc/authenticate を使用して OIDC トークンを Elasticsearch アクセス トークンに交換できますが、これには完全な OIDC リダイレクト フローを実装する必要があります。

JWT (JSON Web トークン)

外部 ID プロバイダーによって発行された JWT をベアラー トークンとして受け入れます。自己管理では、elasticsearch.yml で構成します。ECH では、Cloud デプロイメント設定 UI を通じて構成します。Serverless では利用できません。2 つのトークン タイプをサポートしています。

• id_token (デフォルト) — ユーザーベースのフローに対する OpenID Connect ID トークン。
• access_token — アプリケーション ID フロー用の OAuth2 クライアント認証情報。

curl -H "Authorization: Bearer ${JWT_TOKEN}" "${ELASTICSEARCH_URL}/_security/_authenticate"

各 JWT レルムは 1 つのトークン タイプを処理します。両方が必要な場合は、id_token と access_token 用の個別のレルムを構成します。

Kerberos

SPNEGO メカニズム経由の Kerberos チケットを使用して認証します。自己管理のみ — ECH または Serverless では利用できません。機能する KDC インフラストラクチャ、適切な DNS、および時間同期が必要です。

kinit "${KERBEROS_PRINCIPAL}"
curl --negotiate -u : "${ELASTICSEARCH_URL}/_security/_authenticate"

--negotiate フラグは SPNEGO を有効にします。-u : は curl で必須ですが、ユーザー名は無視されます — kinit からのプリンシパルが使用されます。GSS-API/SPNEGO サポート付きの curl 7.49 以上が必要です。

API キー

レルムではなく、個別の認証メカニズムです。Base64 エンコードされた API キーを Authorization ヘッダーで渡してください。プログラマティックおよび自動化されたアクセスに推奨されます。

curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" "${ELASTICSEARCH_URL}/_security/_authenticate"

ELASTICSEARCH_API_KEY は、キーが作成されたときに返される encoded 値です (Base64 の id:api_key)。

認証の検証

常に認証情報を検証してから進めてください。

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

username、roles、authentication_realm.type を確認して、ID とメソッドを検証します。

authentication_realm.type	レルム
native	ネイティブ
file	ファイル
ldap	LDAP
active_directory	Active Directory
pki	PKI
saml	SAML
oidc	OpenID Connect
jwt	JWT
kerberos	Kerberos

API キーの場合、authentication_type は "api_key" です (レルム タイプではありません)。

API キーの管理

API キーを作成する

curl -X POST "${ELASTICSEARCH_URL}/_security/api_key" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"${KEY_NAME}"'",
    "expiration": "30d",
    "role_descriptors": {
      "'"${ROLE_NAME}"'": {
        "cluster": [],
        "indices": [
          {
            "names": ["'"${INDEX_PATTERN}"'"],
            "privileges": ["read"]
          }
        ]
      }
    }
  }'

レスポンスは id、api_key、encoded を含みます。encoded を安全に保存してください — 後で取得することはできません。

role_descriptors を省略して、認証されたユーザーの現在の権限のスナップショットを継承します。

制限事項: API キーは権限で別の API キーを作成できません。派生キーは有効なアクセスなしで作成されます。代わりにユーザー認証情報で POST /_security/api_key/grant を使用してください。

API キーを取得および無効化する

curl "${ELASTICSEARCH_URL}/_security/api_key?name=${KEY_NAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/api_key" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{"name": "'"${KEY_NAME}"'"}'

例

スコープ付き API キーを作成する

リクエスト: "metrics-* からのみ読み取ることができる API キーを作成します。"

POST /_security/api_key
{
  "name": "metrics-reader-key",
  "expiration": "90d",
  "role_descriptors": {
    "metrics-reader": {
      "indices": [
        {
          "names": ["metrics-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}

ユーザーを認証したレルムを確認する

GET /_security/_authenticate

{
  "username": "joe",
  "authentication_realm": { "name": "ldap1", "type": "ldap" },
  "authentication_type": "realm"
}

JWT ベアラー トークンで認証する

curl -H "Authorization: Bearer ${JWT_TOKEN}" "https://my-cluster:9200/_security/_authenticate"

レスポンスが authentication_realm.type として "jwt" を表示していることを確認してください。

ガイドライン

認証方法を選択する

メソッド	最適用途	トレードオフ
ネイティブ ユーザー	対話的な使用、シンプルなセットアップ	パスワードを保存するか、促す必要がある
ファイル ユーザー	ディザスター リカバリー、ブートストラップ	すべてのノードで構成する必要がある
API キー	プログラマティック アクセス、CI/CD、スコープ付きアクセス	作成後に取得することはできない
LDAP / AD	エンタープライズ ディレクトリ統合	ディレクトリ サーバーへのネットワーク アクセスが必要
PKI 証明書	サービス間、相互 TLS 環境	PKI インフラストラクチャと PKI レルムが必要
SAML	エンタープライズ IdP 経由の Kibana SSO	ブラウザーのみ。REST クライアント向けではない
OIDC	OpenID Connect プロバイダー経由の Kibana SSO	ブラウザーのみ。REST クライアント向けではない
JWT	トークン ベースのサービスとユーザー認証	外部トークン発行者とレルム構成が必要
Kerberos	Windows/エンタープライズ Kerberos 環境	KDC、DNS、時間同期インフラが必要

自動化ワークフロー向けに API キーを優先してください — 微粒度スコープと独立した有効期限をサポートします。Kibana SSO には SAML または OIDC を使用してください。エンタープライズ ディレクトリ統合には LDAP または AD をロール マッピング (elasticsearch-authz 参照) で使用してください。

スーパーユーザー認証情報を避ける

日常的な操作、オートメーション、またはアプリケーション アクセスに、組み込み elastic スーパーユーザーまたは superuser ロール アカウントを使用しないでください。代わりに、タスクに必要な権限のみを持つ専用ユーザーまたは API キーを作成してください。elastic ユーザーは初期クラスター セットアップと緊急回復のみに予約する必要があります。

セキュリティ

• API キーは権限で別の API キーを作成できません。プログラマティック キー作成にはユーザー認証情報または POST /_security/api_key/grant を使用してください。
• 常に API キーに expiration を設定してください。本番環境では無期限のキーを避けてください。
• role_descriptors を使用して API キーをスコープしてください。自動化されたシステム用にスコープなしのキーを作成しないでください。
• チャットでパスワード、API キー、トークン、またはいかなる認証情報も受け取ったり、エコーしたり、ログしたりしないでください。ユーザーにターミナル、環境変数、またはファイルでシークレットを直接管理するよう指示してください。
• シークレットをコード、スクリプト、またはバージョン管理に保存しないでください。環境変数から読み込んでください。
• GET /_security/_authenticate を使用して管理操作を実行する前に認証情報を検証してください。
• ネイティブ ユーザー用のパスワードを生成する場合は、大文字、小文字、数字、記号を混ぜた最低 16 文字を使用してください。changeme や password123 などのプレースホルダー値を使用しないでください。
• SAML と OIDC はブラウザー ベースの SSO のみです。常に REST API アクセス用の付属レルム (ネイティブ、ファイル、または API キー) を並びに構成してください。

デプロイメント互換性

すべての認証レルムが全てのデプロイメント タイプで利用可能とは限りません。自己管理クラスターはすべてのレルムをサポートしています。Elastic Cloud Hosted (ECH) は Elastic により管理され、ノード レベルのアクセスはありません。Serverless は完全に管理された SaaS です。

レルム	自己管理	ECH	Serverless
ネイティブ	はい	はい	利用不可
ファイル	はい	利用不可	利用不可
LDAP	はい	利用不可	利用不可
Active Directory	はい	利用不可	利用不可
PKI	はい	限定	利用不可
SAML	はい	はい (デプロイメント構成)	組織レベル
OIDC	はい	はい (デプロイメント構成)	利用不可
JWT	はい	はい (デプロイメント構成)	利用不可
Kerberos	はい	利用不可	利用不可
API キー	はい	はい	はい

ECH 注記:

• ノード アクセスがないため、ファイル レルムと elasticsearch-users CLI は利用できません。
• LDAP、Active Directory、Kerberos は ECH で構成することはできません。
• SAML、OIDC、JWT は Cloud デプロイメント設定 UI を使用して構成できます。
• elastic スーパーユーザーは利用可能ですが、定期的な使用でも避けるべきです。

Serverless 注記:

• API キーが主な認証方法です。
• ネイティブ ユーザーは存在しません — ユーザーは Elastic Cloud 組織レベルで管理されます。
• SAML SSO は組織レベルで構成され、プロジェクト単位ではありません。