Apache Kafka database plugin HTTP API

The Kafka database plugin is one of the supported plugins for the database secrets engine. This plugin generates dynamic SCRAM-SHA-256/512 credentials against an Apache Kafka cluster using the AdminClient 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

• brokers (list: <required>) – Specifies a set of comma-delineated bootstrap brokers to connect to, e.g. broker1.example.com:9092,broker2.example.com:9092.

• username (string: <required>) – Specifies the root credential username OpenBao uses to authenticate to Kafka and issue/revoke SCRAM credentials. This user must already exist on the cluster with permission to alter other users' SCRAM credentials.

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

• mechanism (string: "SCRAM-SHA-256") – Specifies the SASL mechanism used both for OpenBao's own connection to the cluster and as the default mechanism for credentials it issues. One of SCRAM-SHA-256 or SCRAM-SHA-512. PLAIN is not supported by this plugin's SCRAM AdminClient flow.

• use_tls (bool: false) – Specifies whether to dial the brokers with TLS. Automatically implied if tls_ca, tls_ca_path, or tls_certificate is set.

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

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

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

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

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

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

Default Username Template

{{ printf "v-%s-%s-%s" (.DisplayName | truncate 10) (.RoleName | truncate 10) (random 10) | replace "." "-" | truncate 64 }}

Example Usernames:

Example
DisplayName	token
RoleName	producer
Username	v-token-producer-uszt1n4cyh

Sample payload

{
  "plugin_name": "kafka-database-plugin",
  "allowed_roles": "producer",
  "brokers": "broker1.example.com:9092,broker2.example.com:9092",
  "username": "admin",
  "password": "admin",
  "mechanism": "SCRAM-SHA-256"
}

Sample request

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

Statements

Unlike SQL-style database plugins, this plugin does not use semicolon-separated statement lists. creation_statements is a single JSON document describing the SCRAM credential to create. 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 describing the SCRAM credential to create:

  {
    "mechanism": "SCRAM-SHA-256",
    "iterations": 4096,
    "acls": []
  }

  • mechanism – One of SCRAM-SHA-256 or SCRAM-SHA-512. Defaults to SCRAM-SHA-256 when omitted.
  • iterations – The SCRAM iteration count. Defaults to 4096 when omitted.
  • acls – Optional array of ACL objects to grant to the generated user:
    • resource_type – Resource type (TOPIC, GROUP, CLUSTER, TRANSACTIONAL_ID, DELEGATION_TOKEN).
    • resource_name – Target resource name (required unless resource type is CLUSTER).
    • pattern_type – Pattern type (LITERAL or PREFIXED). Defaults to LITERAL.
    • operation – Kafka operation (READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS, IDEMPOTENT_WRITE, ALL).
    • permission – ALLOW (default) or DENY.

  On the wire the plugin issues:

  AlterUserSCRAMs(upsert: [{User: "<name>", Mechanism: <mechanism>, Iterations: <iterations>, Password: "<password>"}])
  CreateACLs(...)

revocation_statements and rollback_statements are accepted by the database secrets engine framework but are not used by this plugin. Revocation always issues AlterUserSCRAMs deletes for both SCRAM-SHA-256 and SCRAM-SHA-512 against the username, so the credential is removed regardless of which mechanism it was created with; a missing record is not treated as an error. root_rotation_statements are similarly unused — root rotation and static-role rotation query the user's existing SCRAM credentials via DescribeUserSCRAMs and preserve their existing mechanism(s) and iteration count. If no SCRAM credentials exist, it falls back to the configured or default mechanism (SCRAM-SHA-256, 4096 iterations).

Root credential rotation

$ bao write -force database/rotate-root/kafka

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

Static roles

Static roles rotate the SCRAM credential of an existing Kafka user on a schedule, via the same AlterUserSCRAMs upsert call:

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