Apache Druid database plugin HTTP API

The Apache Druid database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles against a Druid cluster's BasicSecurity Coordinator API.

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 Druid Coordinator base URL, e.g. http://druid.example.com:8081. All BasicSecurity REST calls are issued relative to this URL.

• username (string: <required>) – Specifies the root credential username OpenBao uses to authenticate to the BasicSecurity API (via HTTP Basic Auth) and issue/revoke dynamic users.

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

• authenticator (string: "MyBasicMetadataAuthenticator") – Specifies the name of the Druid BasicSecurity authenticator (as configured in common.runtime.properties) that dynamic users are created against.

• authorizer (string: "MyBasicMetadataAuthorizer") – Specifies the name of the Druid BasicSecurity authorizer (as configured in common.runtime.properties) that dynamic users and role bindings are created against.

• ca_cert (string: "") – Specifies a PEM-encoded CA certificate (or bundle) to use when validating the Druid Coordinator's TLS certificate.

• ca_path (string: "") – Specifies a filesystem path to a PEM-encoded CA certificate (or bundle) to use when validating the Druid Coordinator's TLS certificate.

• client_cert (string: "") – Specifies a PEM-encoded client certificate to present for mTLS. Must be set together with client_key.

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

• insecure (bool: false) – Skips TLS certificate verification when connecting to Druid. Intended for development only.

• 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-uszt1n4cyhal4-1614294836

Sample payload

{
  "plugin_name": "druid-database-plugin",
  "allowed_roles": "reader",
  "url": "http://druid.example.com:8081",
  "username": "admin",
  "password": "admin",
  "authenticator": "MyBasicMetadataAuthenticator",
  "authorizer": "MyBasicMetadataAuthorizer"
}

Sample request

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

Statements

Unlike SQL-style database plugins, this plugin does not use semicolon-separated statement lists. creation_statements is a single JSON document listing pre-existing Druid role names to bind to the new user. For more information on configuring roles see the Role API in the database secrets engine docs.

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 listing the Druid roles to bind to the new user:

  { "roles": ["datasourceReadAccess", "viewer"] }

  roles is an array of bare role name strings that must already exist in the cluster's configured authorizer; this plugin does not create roles. On the wire the plugin issues, in order:

  POST .../authentication/db/<authenticator>/users/<name>
  POST .../authentication/db/<authenticator>/users/<name>/credentials   {"password":"<password>"}
  POST .../authorization/db/<authorizer>/users/<name>
  POST .../authorization/db/<authorizer>/users/<name>/roles/<role>      (once per role)

  If any call after the initial user creation fails (for example, an unknown role name), the plugin issues DELETE .../authentication/db/<authenticator>/users/<name> before returning the error, so no half-configured user is left behind. There is no built-in default; a role without creation_statements, or with an empty 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. Revocation always issues DELETE .../authorization/db/<authorizer>/users/<name> followed by DELETE .../authentication/db/<authenticator>/users/<name>; a 404 response from either is treated as success, making the operation idempotent. Password rotation for static roles always issues POST .../authentication/db/<authenticator>/users/<name>/credentials with the new password.

Static roles

Static roles rotate the password of an existing Druid user on a schedule, via the same /credentials endpoint:

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