# Hashicorp Vault

Secure secrets in Hashicorp Vault and use them in Kafka Connect.

{% hint style="danger" %}
Secrets will only be reloaded if the Connector restarts.
{% endhint %}

{% hint style="info" %}
From Version 2.2.0, the secret provider does not write secrets to files by default. If you require this behaviour (for trust stores, key stores or certs) you can enable this by adding the property **`file.write=true`**.
{% endhint %}

## Authentication

Multiple authentication methods are supported:

* approle
* userpass
* kubernetes
* cert
* token
* ldap
* gcp
* awsiam
* jwt
* github

## Configuring the plugin <a href="#configuring-the-plugin" id="configuring-the-plugin"></a>

<table data-full-width="false"><thead><tr><th width="286">Name</th><th>Description</th></tr></thead><tbody><tr><td>file.dir</td><td>The base location for any files to be stored</td></tr><tr><td>file.write</td><td>Writes secrets to file on path. Required for Java trust stores, key stores, certs that need to be loaded from file. For ease of use for the secret provider, this is disabled by default.</td></tr><tr><td>vault.auth.method</td><td>Available values are <code>approle</code>, <code>userpass</code>, <code>kubernetes</code>, <code>cert</code>, <code>token</code>, <code>ldap</code>, <code>gcp</code>, <code>awsiam</code>, <code>jwt</code>, <code>github</code>, <code>token</code></td></tr><tr><td>vault.addr</td><td>Address of the Vault server</td></tr><tr><td>vault.token</td><td>Use when ‘vault.auth.method’ is ‘token’ to specify the token value</td></tr><tr><td>vault.namespace</td><td>Set a global namespace to the Vault server instance. Requires <strong>Vault Enterprise Pro</strong></td></tr><tr><td>vault.pem</td><td>File containing the Vault Server certificate content as string</td></tr><tr><td>vault.client.pem</td><td>File containing the Client certificate string content as string</td></tr><tr><td>vault.engine.version</td><td>KV Secrets Engine version of the Vault server instance. Default is <strong>2</strong></td></tr><tr><td>vault.ssl.truststore.location</td><td>The location of the trust store file</td></tr><tr><td>vault.ssl.keystore.location</td><td>The location of the key store file</td></tr><tr><td>vault.ssl.keystore.password</td><td>The password for the key store file</td></tr><tr><td>secret.default.ttl</td><td>If no TTL is configured in Vault, apply a default TTL.</td></tr><tr><td>app.role.id</td><td>Use when vault.auth.method is <code>approle</code> or <code>kubernetes</code> to specify the Vault App role id</td></tr><tr><td>app.role.secret.id</td><td>Use when vault.auth.method is <code>approle</code> tp specify the Vault App role name secret id</td></tr><tr><td>app.role.path</td><td>Use when vault.auth.method is <code>approle</code> to specify the Vault App role path</td></tr><tr><td>username</td><td>Use when vault.auth.method is <code>userpass</code> to specify the username to connect to Vault</td></tr><tr><td>password</td><td>Use when vault.auth.method is <code>userpass</code> to specify the password to connect to Vault</td></tr><tr><td>mount</td><td>Use when vault.auth.method is <code>userpass</code> to specify the mount name of the userpass authentication back end</td></tr><tr><td>ldap.username</td><td>Use when vault.auth.method is <code>ldap</code> to specify the LDAP username to connect to Vault with</td></tr><tr><td>ldap.password</td><td>Use when vault.auth.method is <code>ldap</code> to specify the LDAP password to connect to Vault with</td></tr><tr><td>mount</td><td>Use when vault.auth.method is <code>ldap</code> to specify the mount name of the ldap authentication back end</td></tr><tr><td>jwt.role</td><td>Use when vault.auth.method is <code>jwt</code> to specify the role the JWT token belongs to</td></tr><tr><td>jwt.provider</td><td>Use when vault.auth.method is <code>jwt</code> to specify the provider of the JWT token</td></tr><tr><td>jwt</td><td>Use when vault.auth.method is <code>jwt</code> to specify the JWT token</td></tr><tr><td>gcp.role</td><td>Use when vault.auth.method is <code>gcp</code> to specify the gcp role used for authentication</td></tr><tr><td>gcp.jwt</td><td>Use when vault.auth.method is <code>gcp</code> to specify the JWT token</td></tr><tr><td>cert.mount</td><td>Use when vault.auth.method is <code>cert</code> to specify the mount name of the cert authentication back end</td></tr><tr><td>github.token</td><td>Use when vault.auth.method is <code>github</code> to specify the github app-id to use for authentication</td></tr><tr><td>github.mount</td><td>Use when vault.auth.method is <code>github</code> to specify the mount name of the github authentication back end</td></tr><tr><td>kubernetes.role</td><td>Use when vault.auth.method is <code>kubernetes</code> to specify the kubernetes role for authentication</td></tr><tr><td>kubernetes.token.path</td><td>Use when vault.auth.method is <code>kubernetes</code> to specify the path to the service account token . Default is /var/run/secrets/kubernetes.io/serviceaccount/token</td></tr><tr><td>kubernetes.auth.path</td><td>Use when vault.auth.method is <code>kubernetes</code> to specify a custom mount path</td></tr><tr><td>aws.role</td><td>Use when vault.auth.method is <code>awsiam</code>.<br>Name of the role to login. If role is not specified, the login endpoint uses the role bearing the name of the AMI ID of the EC2 instance or if using the ec2 auth method the friendly name (i.e., role name or username) of the IAM authenticated principal</td></tr><tr><td>aws.request.url</td><td>Use when vault.auth.method is <code>awsiam</code>.<br>PKCS7 signature of the identity document with all n characters removed. Base64-encoded HTTP URL used in the signed request (i.e. base64-encoding of <code>https://sts.amazonaws.com</code>) as most requests will probably use POST with an empty URI</td></tr><tr><td>aws.request.body</td><td>Use when vault.auth.method is <code>awsiam</code>.<br>Base64-encoded body of the signed request i.e. base64 of Action=GetCallerIdentity&#x26;Version=2011-06-15</td></tr><tr><td>aws.request.headers</td><td>Use when vault.auth.method is <code>awsiam</code> to specify any request headers</td></tr><tr><td>aws.mount</td><td>Use when vault.auth.method is <code>awsiam</code>. The AWS auth mount. Default is “aws”</td></tr></tbody></table>

Example Worker Properties

{% code title="worker.props" %}

```properties
config.providers=vault
config.providers.vault.class=io.lenses.connect.secrets.providers.VaultSecretProvider
config.providers.vault.param.vault.addr=http://localhost:8200
config.providers.vault.param.vault.auth.method=token
config.providers.vault.param.vault.token=my-token
config.providers.vault.param.file.dir=/connector-files/vault
```

{% endcode %}

## Usage  <a href="#usage" id="usage"></a>

To use this provider in a connector, reference the Hashicorp Vault containing the secret and the key name for the value of the connector property.

The indirect reference is in the form **${provider:path:key}** where:

* **provider** is the name of the provider in the worker property file set above
* **path** is the path of the secret in Hashicorp Vault
* **key** is the name of the secret key in secret to retrieve. Vault can store multiple keys under a path.

For example, if we store two secrets as keys:

* my\_username\_key with the value lenses and
* my\_password\_key with the value my-secret-password

in a secret called secret/my-vault-secret we would set:

{% code title="connector.props" %}

```properties
name=my-sink
class=my-class
topics=mytopic
username=${vault:secret/my-vault-secret:my_username_key}
password=${vault:secret/my-vault-secret:my_password_key}
```

{% endcode %}

This would resolve at runtime to:

```properties
name=my-sink
class=my-class
topics=mytopic
username=lenses
password=my-secret-password
```

## Data encoding  <a href="#data-encoding" id="data-encoding"></a>

The provider handles the following types:

* utf\_8
* base64

The provider will look for keys prefixed with:

* UTF8
* UTF\_FILE
* BASE64
* BASE64\_FILE

The **`UTF8`** means the value returned is the string retrieved for the secret key. The **`BASE64`** means the value returned is the base64 decoded string retrieved for the secret key.

If the value for the tag is **`UTF8_FILE`** the string contents are written to a file. The returned value from the connector configuration key will be the location of the file. The file location is determined by the file.dir configuration option is given to the provider via the Connect **`worker.properties`** file.

If the value for the tag is **`BASE64_FILE`** the string contents are based64 decoded and are written to a file. The returned value from the connector configuration key will be the location of the file. For example, if a connector needs a PEM file on disk set the prefix as **`BASE64_FILE`**. The file location is determined by the file.dir configuration option is given to the provider via the Connect **`worker.properties`** file.

If no prefix is found the contents of the secret string are returned.