elasticsearch-authn

Name: elasticsearch-authn
Author: elastic

github.com/elasticセキュリティ6023.0k 回インストール今日更新

elasticsearch-authn について

設定済みの組み込み・外部 Realm を使った Elasticsearch クラスター認証と、API key のライフサイクルを扱うスキルです。ユーザー、サービス、自動化の認証方式を選ぶチーム向けで、シークレットの扱いとデプロイ環境ごとの対応状況も説明します。

主な機能

01複数の認証 Realm に対応
02認証済みの ID と方式を確認
03API key の作成・照会・無効化
04サービスアカウントトークンと証明書認証
05デプロイ環境ごとの対応状況を説明
06環境変数による認証情報の保護

活用シーン

01ユーザーを認証した Realm の確認
02自動化向けの権限を限定した API key の作成
03サービス間の証明書認証の設定
04ID プロバイダーに合う認証方式の選定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/elastic/agent-skills --skill elasticsearch-authn

インストール後、Claude Code で/elasticsearch-authnを入力して読み込まれたか確認します。

同梱ファイルreferences/api-reference.md

詳細

Elasticsearch の認証

すでに設定されているサポート対象の任意の認証レルムを使用して、Elasticsearch クラスターに対して認証します。このスキルでは、すべての組み込みレルム、認証情報の検証、API キーのライフサイクル全体について説明します。

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

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

デプロイに関する注意: すべてのレルムをあらゆるデプロイタイプで利用できるわけではありません。セルフマネージド、ECH、Serverless の詳細については、デプロイの互換性を参照してください。

重要な原則

チャットで認証情報を尋ねないでください。 ユーザーにパスワード、API キー、トークン、その他の秘密情報を会話に貼り付けるよう求めないでください。秘密情報を会話履歴に残してはいけません。
必ず環境変数を使用してください。 このスキルのコード例では、環境変数（例：ELASTICSEARCH_PASSWORD、ELASTICSEARCH_API_KEY）を参照します。必須の変数がない場合は、値を直接尋ねるのではなく、プロジェクトのルートにある .env ファイルに設定するようユーザーに案内してください。
ターミナルでのエクスポートより .env を優先してください。 エージェントがサンドボックス化されたシェルセッションでコマンドを実行すると、ユーザーのターミナル環境を引き継がない場合があります。作業ディレクトリにある .env ファイルなら、あらゆる実行環境で確実に利用できます。ユーザーが明示的に希望する場合に限り、代替手段として export を提案してください。

実現したいこと

ユーザー名とパスワードを使ってクラスターに認証する（native レルム）
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 システムに処理を委任します。

内部レルム

Native（ユーザー名とパスワード）

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

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

File

各クラスターのノード上にあるフラットファイルで定義されるユーザーです（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 グループをロールに変換するためにロールマッピングと組み合わせて使用します。

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

SAML 2.0 Web ブラウザー SSO を有効にします。主に Kibana の認証に使用されます。セルフマネージド環境では、elasticsearch.yml で設定します。ECH では、Cloud デプロイ設定 UI から設定します。Serverless では、SAML は組織レベルで処理され、プロジェクトごとの設定はできません。標準的な REST クライアントでは使用できません。ブラウザーベースのリダイレクトフローは Kibana が処理します。プログラムから API にアクセスする場合は、SAML と併せて別のレルム（ネイティブまたは API キーなど）を設定してください。

OIDC（OpenID Connect）

OpenID Connect SSO を有効にします。主に Kibana の認証に使用されます。セルフマネージド環境では、elasticsearch.yml で設定します。ECH では、Cloud デプロイ設定 UI から設定します。Serverless では利用できません。SAML と同様、ブラウザーのリダイレクトに依存するため、REST クライアントからの直接利用には適していません。OIDC と併せてプログラムからアクセスする場合は、API キーまたはネイティブユーザーを使用してください。

カスタムアプリケーションでは、OIDC トークンを POST /_security/oidc/authenticate を介して Elasticsearch アクセストークンと交換できますが、そのためには OIDC リダイレクトフロー全体を実装する必要があります。

JWT（JSON Web Tokens）

外部 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 を有効にします。curl では -u : が必要ですが、ユーザー名は無視され、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 の値（id:api_key を Base64 でエンコードしたもの）です。

認証を確認する

先に進む前に、必ず認証情報を確認してください。

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

username、roles、authentication_realm.type を確認して、ユーザーの身元と認証方法を確かめます。

`authentication_realm.type`	Realm
`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 アクセス用の補助レルム（native、file、または API キー）を必ず設定してください。

デプロイメントの互換性

すべての認証レルムが、すべてのデプロイメントタイプで利用できるわけではありません。セルフマネージドクラスターはすべてのレルムをサポートします。**Elastic Cloud Hosted（ECH）**は Elastic が管理し、ノードレベルのアクセスはできません。Serverlessはフルマネージドの SaaS です。

レルム	セルフマネージド	ECH	Serverless
Native	はい	はい	利用不可
File	はい	利用不可	利用不可
LDAP	はい	利用不可	利用不可
Active Directory	はい	利用不可	利用不可
PKI	はい	制限あり	利用不可
SAML	はい	はい（デプロイメント設定）	組織レベル
OIDC	はい	はい（デプロイメント設定）	利用不可
JWT	はい	はい（デプロイメント設定）	利用不可
Kerberos	はい	利用不可	利用不可
API キー	はい	はい	はい

ECH に関する注意事項：

ノードにアクセスできないため、file レルムと elasticsearch-users CLI は利用できません。
ECH では LDAP、Active Directory、Kerberos を設定できません。
SAML、OIDC、JWT は、Cloud のデプロイメント設定 UI から設定できます。
elastic スーパーユーザーは利用できますが、通常の用途では引き続き使用を避けてください。

Serverless に関する注意事項：

API キーが主な認証方法です。
ネイティブユーザーは存在しません。ユーザーは Elastic Cloud の組織レベルで管理されます。
SAML SSO はプロジェクトごとではなく、組織レベルで設定します。

Markdown 対応

ログインしてコメント

基本情報

作者: elastic
リポジトリ: elastic/agent-skills
カテゴリ: セキュリティ
インストール数: 3,045
GitHub スター: 602

問題を報告