HashiCorp Vault Properties Provider 1.0

HashiCorp Vault Properties Provider is a configuration that enables Mule applications to retrieve secrets from HashiCorp Vault before the Mule app runs.

For information about compatibility and fixed issues, refer to the HashiCorp Vault Properties Provider Release Notes.

Before You Begin

To use this properties provider, you must be familiar with:

HashiCorp Vault and its key-value version 2 (KV v2) secrets engine
Mule runtime engine (Mule)
Elements and global elements in a Mule flow
How to create a Mule app using Anypoint Studio

Before creating an app, you must have:

The URL of your Vault server and credentials to access it (a token, AppRole credentials, or LDAP credentials)
A Vault identity with read permission on the KV v2 data/ paths of the secrets that your app uses. Permission on only the metadata paths is not sufficient.
Anypoint Platform
Anypoint Studio or Anypoint Code Builder

Common Use Cases for the Properties Provider

With HashiCorp Vault Properties Provider, secrets are retrieved when Mule parses the app configuration, before any flow runs. This allows you to avoid storing API keys, passwords, or tokens in plaintext property files or deployment descriptors.

Configure the Properties Provider

Select exactly one authentication type: Token, AppRole, or LDAP.

The credentials for the properties provider must resolve from a source that Mule evaluates before this properties provider, such as a deployment property or a JVM system property. Don’t use a ${hashicorp::…} placeholder for the credentials of the properties provider itself.

This example uses token authentication:

<hashicorp-vault-properties:config
    name="Hashicorp_Vault_Properties_Config"
    address="https://vault.example.internal:8200"
    mount="secret"
    namespace="admin">
    <hashicorp-vault-properties:authentication>
        <hashicorp-vault-properties:token-authentication token="${vault.token}"/>
    </hashicorp-vault-properties:authentication>
</hashicorp-vault-properties:config>

This example uses AppRole authentication. authMount defaults to approle:

<hashicorp-vault-properties:config
    name="Hashicorp_Vault_Properties_Config"
    address="https://vault.example.internal:8200"
    mount="secret"
    namespace="admin">
    <hashicorp-vault-properties:authentication>
        <hashicorp-vault-properties:approle-authentication
            roleId="${vault.roleId}" secretId="${vault.secretId}" authMount="approle"/>
    </hashicorp-vault-properties:authentication>
</hashicorp-vault-properties:config>

This example uses LDAP authentication. ldapAuthMount defaults to ldap:

<hashicorp-vault-properties:config
    name="Hashicorp_Vault_Properties_Config"
    address="https://vault.example.internal:8200"
    mount="secret"
    namespace="admin">
    <hashicorp-vault-properties:authentication>
        <hashicorp-vault-properties:ldap-authentication
            ldapUsername="${vault.ldapUsername}" ldapPassword="${vault.ldapPassword}" ldapAuthMount="ldap"/>
    </hashicorp-vault-properties:authentication>
</hashicorp-vault-properties:config>

For all configuration fields, refer to HashiCorp Vault Properties Provider Reference.

Reference Secrets

Use the ${hashicorp::path#field} structure to retrieve a string field from a secret, where path is the path of the secret in the Vault secrets mount and field is the name of the field in that secret. For example, with the default secret mount, ${hashicorp::applications/orders#apiKey} reads the apiKey field of the secret at applications/orders.

To retrieve a nested value, use a JSON Pointer after the , for example ${hashicorp::applications/orders/credentials/0/key}. In a JSON Pointer, use ~1 to represent / and ~0 to represent ~.

The placeholder must follow these rules:

It contains exactly one #.
The path isn’t empty, doesn’t start or end with /, and doesn’t contain //, ., or .. segments.
The value it resolves to is a string.

The properties provider doesn’t cache values. Each resolution reads the latest version of the secret from Vault.

Known Limitations

The properties provider supports only the Vault KV v2 secrets engine and can read only the latest version of a secret.
The properties provider can read only string values. Non-string values cause an error.
You can define only one HashiCorp Vault Properties Provider configuration in a Mule app because the hashicorp:: prefix is fixed and placeholders can’t reference a configuration by name.
SAML authentication isn’t supported.
The nested tls:context element must be the first child of the configuration, before authentication. Setting only a tlsContext attribute doesn’t apply the TLS context.