Elasticsearch database secrets engine

Elasticsearch is one of the supported plugins for the database secrets engine. This plugin generates Elasticsearch native-realm user credentials dynamically based on configured roles, and also supports Static Roles. Because OpenSearch's security API is wire compatible with Elasticsearch's native realm users API, this same plugin also works against OpenSearch clusters without any additional configuration.

See the database secrets engine docs for more information about setting up the database secrets engine.

Unlike the SQL-style database plugins, Elasticsearch's creation_statements is a single JSON document describing the roles (and optional profile fields) to grant, rather than a semicolon-separated list of SQL statements. The plugin talks directly to the cluster's /_security/user API (or, when use_old_xpack=true, the legacy Elasticsearch 6 /_xpack/security/user API) using HTTP basic auth — there is no bundled Elasticsearch or OpenSearch client SDK dependency.

Capabilities

Plugin Name	Root Credential Rotation	Dynamic Roles	Static Roles	Username Customization
elasticsearch-database-plugin	Yes	Yes	Yes	Yes

Setup

1. Enable the database secrets engine if it is not already enabled:

   $ bao secrets enable database
   Success! Enabled the database secrets engine at: database/

   By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

2. Configure OpenBao with the proper plugin and connection information:

   $ bao write database/config/my-elasticsearch \
       plugin_name="elasticsearch-database-plugin" \
       allowed_roles="reader" \
       url="https://es.example.com:9200" \
       username="elastic" \
       password="changeme"
   Success! Data written to: database/config/my-elasticsearch

3. Configure a role that maps a name in OpenBao to an Elasticsearch role document to apply when creating the database credential:

   $ bao write database/roles/reader \
       db_name="my-elasticsearch" \
       creation_statements='{"elasticsearch_roles":["readonly","kibana_user"],"full_name":"Bao Reader"}' \
       default_ttl="1h" \
       max_ttl="24h"
   Success! Data written to: database/roles/reader

   creation_statements is a single JSON document, not a list of SQL statements:

   • elasticsearch_roles (required) is an array of role names that must already exist on the cluster. They are assigned to the generated user as-is.
   • full_name, email, metadata (all optional) are passed straight through to the native realm users API.

Usage

After the secrets engine is configured and a user/machine has an OpenBao token with the proper permission, it can generate credentials.

1. Generate a new credential by reading from the /creds endpoint with the name of the role:

   $ bao read database/creds/reader
   Key                Value
   ---                -----
   lease_id           database/creds/reader/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
   lease_duration     1h
   lease_renewable    true
   password           FSREZ1S0kFsZtLat-y94
   username           v-token-reader-uszt1n4cyhal4m0xtgx3-1717000000

Elasticsearch-specific notes

• OpenSearch compatibility: OpenSearch's security plugin exposes the same /_security/user API shape as Elasticsearch's native realm, so elasticsearch-database-plugin works unmodified against OpenSearch clusters. No separate config flag is needed.
• Legacy Elasticsearch 6: Set use_old_xpack=true on database/config/:name to target the older /_xpack/security/user path instead of /_security/user.
• No native credential expiry: Elasticsearch has no VALID UNTIL concept for native-realm users, so lease expiry for dynamic roles is enforced purely by OpenBao revoking the lease (which deletes the user via DELETE /_security/user/<name>), not by the cluster itself.
• Static roles: Password rotation for static roles is performed with Elasticsearch's POST /_security/user/<name>/_password API against an existing native-realm user.
• Roles must pre-exist: The plugin does not create Elasticsearch roles — elasticsearch_roles in creation_statements must already exist on the cluster (for example, created ahead of time via PUT /_security/role/...).

API

The full list of configurable options can be seen in the Elasticsearch database plugin API page.

For more information on the database secrets engine's HTTP API please see the Database secrets engine API page.