Elasticsearch database plugin HTTP API

The Elasticsearch database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for Elasticsearch, and is also compatible with OpenSearch clusters since OpenSearch's security API exposes the same native-realm users endpoints.

Configure connection

In addition to the parameters defined by the Database Secrets Engine, this plugin has a number of parameters to further configure a connection.

Method	Path
POST	/database/config/:name

Parameters

• url (string: <required>) – Specifies the full URL, including scheme and port, used to reach the Elasticsearch or OpenSearch cluster, e.g. https://es.example.com:9200.

• username (string: <required>) – Specifies the root credential username OpenBao uses to log into the cluster and issue/revoke native-realm users.

• password (string: <required>) – Specifies the root credential password corresponding to username.

• ca_cert (string: "") – Specifies the PEM contents of a CA certificate bundle used to verify the cluster's TLS certificate.

• ca_path (string: "") – Specifies a filesystem path to a CA certificate bundle (PEM) used to verify the cluster's TLS certificate. May be combined with ca_cert; both are added to the trust pool.

• client_cert (string: "") – Specifies the PEM contents of a client certificate to use for mutual TLS. Must be set together with client_key.

• client_key (string: "") – Specifies the PEM contents of the private key corresponding to client_cert. Must be set together with client_cert.

• tls_server_name (string: "") – Specifies the server name to use for TLS SNI and certificate verification instead of the hostname in url.

• insecure (bool: false) – Specifies whether to skip verification of the cluster's TLS certificate. Not recommended outside of development.

• use_old_xpack (bool: false) – Specifies whether to use the legacy Elasticsearch 6 /_xpack/security/ API path prefix instead of the default /_security/ prefix used by Elasticsearch 7+ and OpenSearch.

• username_template (string) - Template describing how dynamic usernames are generated.

Default Username Template

{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | replace "." "-" | truncate 100 }}

Example Usernames:

Example
DisplayName	token
RoleName	myrolename
Username	v-token-myrolename-uszt1n4cyhal4m0xtgx3-1614294836

Sample payload

{
  "plugin_name": "elasticsearch-database-plugin",
  "allowed_roles": "reader",
  "url": "https://es.example.com:9200",
  "username": "elastic",
  "password": "changeme"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/my-elasticsearch

Statements

Unlike SQL-style database plugins, Elasticsearch does not use semicolon-separated statement lists. Instead creation_statements is a single JSON document describing the roles (and optional profile fields) to apply, matching the shape Elasticsearch's PUT /_security/user/<name> API expects. For more information on configuring roles see the Role API in the database secrets engine docs.

Parameters

The following are the statements used by this plugin. If not mentioned in this list the plugin does not support that statement type.

• creation_statements (string: <required>) – Specifies a single JSON document describing the user to create:

  {
    "elasticsearch_roles": ["readonly", "kibana_user"],
    "full_name": "Bao Reader",
    "email": "reader@example.com",
    "metadata": { "managed_by": "openbao" }
  }

  • 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 (optional) is passed through as the user's full_name.
  • email (optional) is passed through as the user's email.
  • metadata (optional) is passed through as the user's metadata object.

  There is no built-in default; a role without creation_statements fails to issue credentials.

revocation_statements, rollback_statements, and root_rotation_statements are accepted by the database secrets engine framework but are not used by this plugin. User deletion always issues DELETE /_security/user/<name> (treating a 404 as success), and root/static credential rotation always issues POST /_security/user/<name>/_password rather than a configurable statement.

Root credential rotation

$ bao write -force database/rotate-root/my-elasticsearch

Rotates the root user's password (the username/password pair configured on database/config/:name) via POST /_security/user/<name>/_password. The old password is not recoverable afterward.

Static roles

Static roles rotate the password of an existing Elasticsearch native-realm user on a schedule, via POST /_security/user/<name>/_password:

$ bao write database/static-roles/svc \
    db_name=my-elasticsearch \
    username=svc \
    rotation_period=24h

Elasticsearch has no native VALID UNTIL clause on users, so dynamic-role lease expiry is enforced by OpenBao revoking the lease (DELETE /_security/user/<name>), not by the cluster itself.