Vault Connector

1. Overview

The Vault Connector (vault) component allows you to read or write secrets in a HashiCorp Vault or OpenBao Key-Value (KV) engine.

It supports both KV v1 (static) and KV v2 (versioned) engines, handling API differences transparently. The component works only as an output action, meaning it cannot be used as an input trigger.

Use it when the flow needs to retrieve sensitive credentials (database passwords, API keys) or store protected information securely.

2. Prerequisites

• A Vault or OpenBao instance accessible by the platform.
• A Key-Value (KV) secret engine enabled in Vault.
• Credentials (Token or AppRole) with appropriate permissions on the desired path.

3. Authentication and Connection

The connector supports two authentication methods: AppRole (recommended for services) and Token.

Field	Required	Type	Description	Example
address	Yes	Text	Full URL of the Vault/OpenBao instance.	"https://vault.example.com"
authMethod	No	Text	Authentication method: approle or token. Default: "approle".	"approle"
token	Yes*	Text	Vault Token. Required if authMethod is token.	"hvs.CAES..."
roleId	Yes**	Text	AppRole Role ID. Required if authMethod is approle.	"0a52..."
secretId	Yes**	Text	AppRole Secret ID. Required if authMethod is approle.	"1e2b..."
tlsSkipVerify	No	Text	If "true", ignores SSL certificate validation (not recommended in production).	"false"
caCert	No	Text	CA certificate in PEM format to validate HTTPS connections.	"-----BEGIN CERTIFICATE-----..."

Tip: Use platform secrets to store tokens and AppRole credentials, referencing them in the component with {$.secrets.secret_name}.

4. Configuration / Supported Operations

The component has two main operations: read and write.

Common Parameters

Field	Required	Type	Description	Example
operation	No	Text	Operation to perform: read or write. Default: "read".	"read"
mount	Yes	Text	KV engine mount point in Vault.	"secret"
path	Yes	Text	Secret path within the mount.	"myapp/config"
kvVersion	No	Text	KV engine version: v1 or v2. Default: "v2".	"v2"

Operation: Read

Retrieves a secret from Vault.

Field	Required	Type	Description	Example
key	No	Text	If filled, returns only this key's value. If empty, returns the entire secret object.	"password"
cacheTtl	No	Number	Time in seconds to cache the read value, avoiding repetitive calls to Vault.	60

Operation: Write

Creates or updates keys in a secret. Important: Writing in the connector is non-destructive by default (it does not remove keys not listed).

Field	Required	Type	Description	Example
overwrite	No	Text	If "true", updates existing keys. If "false", fails if any listed key already exists. Default: "false".	"true"
dataMode	No	Text	Data sending mode: fields (object) or raw (JSON string). Default: "fields".	"fields"
data	Yes***	Object	Key/value map to write (used in fields mode).	{"api_key": "123"}
dataRaw	Yes***	Text	JSON string representing the object to be written (used in raw mode).	{"db_user": "admin"}

*** Required depending on the chosen dataMode.

5. Practical Examples

Reading a database password

Finds the password key in the secret located at secret/myapp/database.

Component configuration:

{
  "componentName": "vault",
  "configurations": {
    "operation": "read",
    "authMethod": "approle",
    "address": "https://vault.internal:8200",
    "roleId": "{$.secrets.vaultRoleId}",
    "secretId": "{$.secrets.vaultSecretId}",
    "mount": "secret",
    "path": "myapp/database",
    "key": "password",
    "kvVersion": "v2"
  }
}

Response:

{
  "data": {
    "password": "super-secure-password"
  },
  "metadata": {
    "version": 3,
    "created_time": "2024-08-20T15:00:00Z"
  }
}

Writing multiple fields (Upsert)

Updates or creates the token and expires_at keys at the path secret/myapp/integration, preserving other keys already present in the same secret.

Component configuration:

{
  "componentName": "vault",
  "configurations": {
    "operation": "write",
    "overwrite": "true",
    "authMethod": "token",
    "address": "{$.env.vault_url}",
    "token": "{$.secrets.vaultToken}",
    "mount": "secret",
    "path": "myapp/integration",
    "dataMode": "fields",
    "data": {
      "token": "{$.body.newToken}",
      "expires_at": "2024-12-31"
    }
  }
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Solve
Vault is sealed or unavailable	Vault is in the "sealed" state or network unreachable.	Check Vault status and connectivity.
Permission denied	Token or AppRole lacks capabilities (read, create, update, patch) on the path.	Review policies associated with the credential. For overwrite: true in KV v2, patch permission is required.
Key(s) [...] already exist	Write attempt with overwrite: false on existing keys.	Change overwrite to "true" or ensure the key is new.
Configuration 'address' is required	One of the mandatory parameters is missing (address, mount, or path).	Review the component configuration.
A write operation requires at least one key/value	Write attempt without providing data in data or dataRaw.	Provide the fields to be written.