Secret Backends

Key-Value Backend

Spring Cloud Vault supports both Key-Value secret backends, the versioned (v2) and unversioned (v1). The key-value backend allows storage of arbitrary values as key-value store. A single context can store one or many key-value tuples. Contexts can be organized hierarchically. Spring Cloud Vault determines itself whether a secret is using versioning and maps the path to its appropriate URL. Spring Cloud Vault allows using the Application name, and a default context name (application) in combination with active profiles.spring-doc.cn

/secret/{application}/{profile}
/secret/{application}
/secret/{default-context}/{profile}
/secret/{default-context}

The application name is determined by the properties:spring-doc.cn

The profiles are determined by the properties:spring-doc.cn

Secrets can be obtained from other contexts within the key-value backend by adding their paths to the application name, separated by commas. For example, given the application name usefulapp,mysql1,projectx/aws, each of these folders will be used:spring-doc.cn

Spring Cloud Vault adds all active profiles to the list of possible context paths. No active profiles will skip accessing contexts with a profile name.spring-doc.cn

Properties are exposed like they are stored (i.e. without additional prefixes).spring-doc.cn

Spring Cloud Vault adds the data/ context between the mount path and the actual context path depending on whether the mount uses the versioned key-value backend. 
spring.cloud.vault:
    kv:
        enabled: true
        backend: secret
        profile-separator: '/'
        default-context: application
        application-name: my-app
        profiles: local, cloud

  • enabled setting this value to false disables the secret backend config usagespring-doc.cn

  • backend sets the path of the secret mount to usespring-doc.cn

  • default-context sets the context name used by all applicationsspring-doc.cn

  • application-name overrides the application name for use in the key-value backendspring-doc.cn

  • profiles overrides the active profiles for use in the key-value backendspring-doc.cn

  • profile-separator separates the profile name from the context in property sources with profilesspring-doc.cn

The key-value secret backend can be operated in versioned (v2) and non-versioned (v1) modes.

See also:spring-doc.cn

Consul

Spring Cloud Vault can obtain credentials for HashiCorp Consul. The Consul integration requires the spring-cloud-vault-config-consul dependency.spring-doc.cn

pom.xml
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-vault-config-consul</artifactId>
        <version>4.1.4</version>
    </dependency>
</dependencies>

The integration can be enabled by setting spring.cloud.vault.consul.enabled=true (default false) and providing the role name with spring.cloud.vault.consul.role=….spring-doc.cn

The obtained token is stored in spring.cloud.consul.token so using Spring Cloud Consul can pick up the generated credentials without further configuration. You can configure the property name by setting spring.cloud.vault.consul.token-property.spring-doc.cn

spring.cloud.vault:
    consul:
        enabled: true
        role: readonly
        backend: consul
        token-property: spring.cloud.consul.token

  • enabled setting this value to true enables the Consul backend config usagespring-doc.cn

  • role sets the role name of the Consul role definitionspring-doc.cn

  • backend sets the path of the Consul mount to usespring-doc.cn

  • token-property sets the property name in which the Consul ACL token is storedspring-doc.cn

See also: Vault Documentation: Setting up Consul with Vaultspring-doc.cn

RabbitMQ

Spring Cloud Vault can obtain credentials for RabbitMQ.spring-doc.cn

The RabbitMQ integration requires the spring-cloud-vault-config-rabbitmq dependency.spring-doc.cn

pom.xml
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
        <version>4.1.4</version>
    </dependency>
</dependencies>

The integration can be enabled by setting spring.cloud.vault.rabbitmq.enabled=true (default false) and providing the role name with spring.cloud.vault.rabbitmq.role=….spring-doc.cn

Username and password are stored in spring.rabbitmq.username and spring.rabbitmq.password so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.rabbitmq.username-property and spring.cloud.vault.rabbitmq.password-property.spring-doc.cn

spring.cloud.vault:
    rabbitmq:
        enabled: true
        role: readonly
        backend: rabbitmq
        username-property: spring.rabbitmq.username
        password-property: spring.rabbitmq.password

  • enabled setting this value to true enables the RabbitMQ backend config usagespring-doc.cn

  • role sets the role name of the RabbitMQ role definitionspring-doc.cn

  • backend sets the path of the RabbitMQ mount to usespring-doc.cn

  • username-property sets the property name in which the RabbitMQ username is storedspring-doc.cn

  • password-property sets the property name in which the RabbitMQ password is storedspring-doc.cn

See also: Vault Documentation: Setting up RabbitMQ with Vaultspring-doc.cn

AWS

Spring Cloud Vault can obtain credentials for AWS.spring-doc.cn

The AWS integration requires the spring-cloud-vault-config-aws dependency.spring-doc.cn

pom.xml
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-vault-config-aws</artifactId>
        <version>4.1.4</version>
    </dependency>
</dependencies>

The integration can be enabled by setting spring.cloud.vault.aws=true (default false) and providing the role name with spring.cloud.vault.aws.role=….spring-doc.cn

Supported AWS credential Types:spring-doc.cn

The access key and secret key are stored in cloud.aws.credentials.accessKey and cloud.aws.credentials.secretKey. So using Spring Cloud AWS will pick up the generated credentials without further configuration.spring-doc.cn

You can configure the property names by setting spring.cloud.vault.aws.access-key-property and spring.cloud.vault.aws.secret-key-property.spring-doc.cn

For STS security token, you can configure the property name by setting spring.cloud.vault.aws.session-token-key-property. The security token is stored under cloud.aws.credentials.sessionToken (defaults).spring-doc.cn

Example: iam_userspring-doc.cn

spring.cloud.vault:
    aws:
        enabled: true
        role: readonly
        backend: aws
        access-key-property: cloud.aws.credentials.accessKey
        secret-key-property: cloud.aws.credentials.secretKey

Example: assumed_role (STS)spring-doc.cn

spring.cloud.vault:
    aws:
        enabled: true
        role: sts-vault-role
        backend: aws
        credential-type: assumed_role
        access-key-property: cloud.aws.credentials.accessKey
        secret-key-property: cloud.aws.credentials.secretKey
        session-token-key-property: cloud.aws.credentials.sessionToken
        ttl: 3600s
        role-arn: arn:aws:iam::${AWS_ACCOUNT}:role/sts-app-role

  • enabled setting this value to true enables the AWS backend config usagespring-doc.cn

  • role sets the role name of the AWS role definitionspring-doc.cn

  • backend sets the path of the AWS mount to usespring-doc.cn

  • access-key-property sets the property name in which the AWS access key is storedspring-doc.cn

  • secret-key-property sets the property name in which the AWS secret key is storedspring-doc.cn

  • session-token-key-property sets the property name in which the AWS STS security token is stored.spring-doc.cn

  • credential-type sets the aws credential type to use for this backend. Defaults to iam_userspring-doc.cn

  • ttl sets the ttl for the STS token when using assumed_role or federation_token. Defaults to the ttl specified by the vault role. Min/Max values are also limited to what AWS would support for STS.spring-doc.cn

  • role-arn sets the IAM role to assume if more than one are configured for the vault role when using assumed_role.spring-doc.cn

See also: Vault Documentation: Setting up AWS with Vaultspring-doc.cn

Database backends

Vault supports several database secret backends to generate database credentials dynamically based on configured roles. This means services that need to access a database no longer need to configure credentials: they can request them from Vault, and use Vault’s leasing mechanism to more easily roll keys.spring-doc.cn

Spring Cloud Vault integrates with these backends:spring-doc.cn

Using a database secret backend requires to enable the backend in the configuration and the spring-cloud-vault-config-databases dependency.spring-doc.cn

Vault ships since 0.7.1 with a dedicated database secret backend that allows database integration via plugins. You can use that specific backend by using the generic database backend. Make sure to specify the appropriate backend path, e.g. spring.cloud.vault.mysql.role.backend=database.spring-doc.cn

pom.xml
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-vault-config-databases</artifactId>
        <version>4.1.4</version>
    </dependency>
</dependencies>
Enabling multiple JDBC-compliant databases will generate credentials and store them by default in the same property keys hence property names for JDBC secrets need to be configured separately.

Database

Spring Cloud Vault can obtain credentials for any database listed at www.vaultproject.io/api/secret/databases/index.html. The integration can be enabled by setting spring.cloud.vault.database.enabled=true (default false) and providing the role name with spring.cloud.vault.database.role=….spring-doc.cn

While the database backend is a generic one, spring.cloud.vault.database specifically targets JDBC databases. Username and password are available from spring.datasource.username and spring.datasource.password properties so using Spring Boot will pick up the generated credentials for your DataSource without further configuration. You can configure the property names by setting spring.cloud.vault.database.username-property and spring.cloud.vault.database.password-property.spring-doc.cn

spring.cloud.vault:
    database:
        enabled: true
        role: readonly
        backend: database
        username-property: spring.datasource.username
        password-property: spring.datasource.password

Multiple Databases

Sometimes, credentials for a single database isn’t sufficient because an application might connect to two or more databases of the same kind. Beginning with version 3.0.5, Spring Vault supports the configuration of multiple database secret backends under the spring.cloud.vault.databases.* namespace.spring-doc.cn

The configuration accepts multiple database backends to materialize credentials into the specified properties. Make sure to configure username-property and password-property appropriately.spring-doc.cn

spring.cloud.vault:
    databases:
        primary:
            enabled: true
            role: readwrite
            backend: database
            username-property: spring.primary-datasource.username
            password-property: spring.primary-datasource.password
        other-database:
            enabled: true
            role: readonly
            backend: database
            username-property: spring.secondary-datasource.username
            password-property: spring.secondary-datasource.password

  • <name> descriptive name of the database configuration.spring-doc.cn

  • <name>.enabled setting this value to true enables the Database backend config usagespring-doc.cn

  • <name>.role sets the role name of the Database role definitionspring-doc.cn

  • <name>.backend sets the path of the Database mount to usespring-doc.cn

  • <name>.username-property sets the property name in which the Database username is stored. Make sure to use unique property names to avoid property shadowing.spring-doc.cn

  • <name>.password-property sets the property name in which the Database password is stored Make sure to use unique property names to avoid property shadowing.spring-doc.cn

See also: Vault Documentation: Database Secrets backendspring-doc.cn

Spring Cloud Vault does not support getting new credentials and configuring your DataSource with them when the maximum lease time has been reached. That is, if max_ttl of the Database role in Vault is set to 24h that means that 24 hours after your application has started it can no longer authenticate with the database.

Apache Cassandra

The cassandra backend has been deprecated in Vault 0.7.1 and it is recommended to use the database backend and mount it as cassandra.

Spring Cloud Vault can obtain credentials for Apache Cassandra. The integration can be enabled by setting spring.cloud.vault.cassandra.enabled=true (default false) and providing the role name with spring.cloud.vault.cassandra.role=….spring-doc.cn

Username and password are available from spring.data.cassandra.username and spring.data.cassandra.password properties so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.cassandra.username-property and spring.cloud.vault.cassandra.password-property.spring-doc.cn

spring.cloud.vault:
    cassandra:
        enabled: true
        role: readonly
        backend: cassandra
        username-property: spring.data.cassandra.username
        password-property: spring.data.cassandra.password

  • enabled setting this value to true enables the Cassandra backend config usagespring-doc.cn

  • role sets the role name of the Cassandra role definitionspring-doc.cn

  • backend sets the path of the Cassandra mount to usespring-doc.cn

  • username-property sets the property name in which the Cassandra username is storedspring-doc.cn

  • password-property sets the property name in which the Cassandra password is storedspring-doc.cn

See also: Vault Documentation: Setting up Apache Cassandra with Vaultspring-doc.cn

Couchbase Database

Spring Cloud Vault can obtain credentials for Couchbase. The integration can be enabled by setting spring.cloud.vault.couchbase.enabled=true (default false) and providing the role name with spring.cloud.vault.couchbase.role=….spring-doc.cn

Username and password are available from spring.couchbase.username and spring.couchbase.password properties so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.couchbase.username-property and spring.cloud.vault.couchbase.password-property.spring-doc.cn

spring.cloud.vault:
    couchbase:
        enabled: true
        role: readonly
        backend: database
        username-property: spring.couchbase.username
        password-property: spring.couchbase.password

  • enabled setting this value to true enables the Couchbase backend config usagespring-doc.cn

  • role sets the role name of the Couchbase role definitionspring-doc.cn

  • backend sets the path of the Couchbase mount to usespring-doc.cn

  • username-property sets the property name in which the Couchbase username is storedspring-doc.cn

  • password-property sets the property name in which the Couchbase password is storedspring-doc.cn

See also: Couchbase Database Plugin Documentationspring-doc.cn

Elasticsearch

Spring Cloud Vault can obtain since version 3.0 credentials for Elasticsearch. The integration can be enabled by setting spring.cloud.vault.elasticsearch.enabled=true (default false) and providing the role name with spring.cloud.vault.elasticsearch.role=….spring-doc.cn

Username and password are available from spring.elasticsearch.rest.username and spring.elasticsearch.rest.password properties so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.elasticsearch.username-property and spring.cloud.vault.elasticsearch.password-property.spring-doc.cn

spring.cloud.vault:
    elasticsearch:
        enabled: true
        role: readonly
        backend: mongodb
        username-property: spring.elasticsearch.rest.username
        password-property: spring.elasticsearch.rest.password

  • enabled setting this value to true enables the Elasticsearch database backend config usagespring-doc.cn

  • role sets the role name of the Elasticsearch role definitionspring-doc.cn

  • backend sets the path of the Elasticsearch mount to usespring-doc.cn

  • username-property sets the property name in which the Elasticsearch username is storedspring-doc.cn

  • password-property sets the property name in which the Elasticsearch password is storedspring-doc.cn

See also: Vault Documentation: Setting up Elasticsearch with Vaultspring-doc.cn

MongoDB

The mongodb backend has been deprecated in Vault 0.7.1 and it is recommended to use the database backend and mount it as mongodb.

Spring Cloud Vault can obtain credentials for MongoDB. The integration can be enabled by setting spring.cloud.vault.mongodb.enabled=true (default false) and providing the role name with spring.cloud.vault.mongodb.role=….spring-doc.cn

Username and password are stored in spring.data.mongodb.username and spring.data.mongodb.password so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.mongodb.username-property and spring.cloud.vault.mongodb.password-property.spring-doc.cn

spring.cloud.vault:
    mongodb:
        enabled: true
        role: readonly
        backend: mongodb
        username-property: spring.data.mongodb.username
        password-property: spring.data.mongodb.password

  • enabled setting this value to true enables the MongodB backend config usagespring-doc.cn

  • role sets the role name of the MongoDB role definitionspring-doc.cn

  • backend sets the path of the MongoDB mount to usespring-doc.cn

  • username-property sets the property name in which the MongoDB username is storedspring-doc.cn

  • password-property sets the property name in which the MongoDB password is storedspring-doc.cn

See also: Vault Documentation: Setting up MongoDB with Vaultspring-doc.cn

MySQL

The mysql backend has been deprecated in Vault 0.7.1 and it is recommended to use the database backend and mount it as mysql. Configuration for spring.cloud.vault.mysql will be removed in a future version.

Spring Cloud Vault can obtain credentials for MySQL. The integration can be enabled by setting spring.cloud.vault.mysql.enabled=true (default false) and providing the role name with spring.cloud.vault.mysql.role=….spring-doc.cn

Username and password are available from spring.datasource.username and spring.datasource.password properties so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.mysql.username-property and spring.cloud.vault.mysql.password-property.spring-doc.cn

spring.cloud.vault:
    mysql:
        enabled: true
        role: readonly
        backend: mysql
        username-property: spring.datasource.username
        password-property: spring.datasource.password

  • enabled setting this value to true enables the MySQL backend config usagespring-doc.cn

  • role sets the role name of the MySQL role definitionspring-doc.cn

  • backend sets the path of the MySQL mount to usespring-doc.cn

  • username-property sets the property name in which the MySQL username is storedspring-doc.cn

  • password-property sets the property name in which the MySQL password is storedspring-doc.cn

See also: Vault Documentation: Setting up MySQL with Vaultspring-doc.cn

PostgreSQL

The postgresql backend has been deprecated in Vault 0.7.1 and it is recommended to use the database backend and mount it as postgresql. Configuration for spring.cloud.vault.postgresql will be removed in a future version.

Spring Cloud Vault can obtain credentials for PostgreSQL. The integration can be enabled by setting spring.cloud.vault.postgresql.enabled=true (default false) and providing the role name with spring.cloud.vault.postgresql.role=….spring-doc.cn

Username and password are available from spring.datasource.username and spring.datasource.password properties so using Spring Boot will pick up the generated credentials without further configuration. You can configure the property names by setting spring.cloud.vault.postgresql.username-property and spring.cloud.vault.postgresql.password-property.spring-doc.cn

spring.cloud.vault:
    postgresql:
        enabled: true
        role: readonly
        backend: postgresql
        username-property: spring.datasource.username
        password-property: spring.datasource.password

  • enabled setting this value to true enables the PostgreSQL backend config usagespring-doc.cn

  • role sets the role name of the PostgreSQL role definitionspring-doc.cn

  • backend sets the path of the PostgreSQL mount to usespring-doc.cn

  • username-property sets the property name in which the PostgreSQL username is storedspring-doc.cn

  • password-property sets the property name in which the PostgreSQL password is storedspring-doc.cn

See also: Vault Documentation: Setting up PostgreSQL with Vaultspring-doc.cn

Customize which secret backends to expose as PropertySource

Spring Cloud Vault uses property-based configuration to create PropertySources for key-value and discovered secret backends.spring-doc.cn

Discovered backends provide VaultSecretBackendDescriptor beans to describe the configuration state to use secret backend as PropertySource. A SecretBackendMetadataFactory is required to create a SecretBackendMetadata object which contains path, name and property transformation configuration.spring-doc.cn

SecretBackendMetadata is used to back a particular PropertySource.spring-doc.cn

You can register a VaultConfigurer for customization. Default key-value and discovered backend registration is disabled if you provide a VaultConfigurer. You can however enable default registration with SecretBackendConfigurer.registerDefaultKeyValueSecretBackends() and SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends().spring-doc.cn

public class CustomizationBean implements VaultConfigurer {

    @Override
    public void addSecretBackends(SecretBackendConfigurer configurer) {

        configurer.add("secret/my-application");

        configurer.registerDefaultKeyValueSecretBackends(false);
        configurer.registerDefaultDiscoveredSecretBackends(true);
    }
}
SpringApplication application = new SpringApplication(MyApplication.class);
application.addBootstrapper(VaultBootstrapper.fromConfigurer(new CustomizationBean()));

Custom Secret Backend Implementations

Spring Cloud Vault ships with secret backend support for the most common backend integrations. You can integrate with any kind of backend by providing an implementation that describes how to obtain data from the backend you want to use and how to surface data provided by that backend by providing a PropertyTransformer.spring-doc.cn

Adding a custom implementation for a backend requires implementation of two interfaces:spring-doc.cn

  • org.springframework.cloud.vault.config.VaultSecretBackendDescriptorspring-doc.cn

  • org.springframework.cloud.vault.config.SecretBackendMetadataFactoryspring-doc.cn

VaultSecretBackendDescriptor is typically an object that holds configuration data, such as VaultDatabaseProperties. Spring Cloud Vault requires that your type is annotated with @ConfigurationProperties to materialize the class from the configuration.spring-doc.cn

SecretBackendMetadataFactory accepts VaultSecretBackendDescriptor to create the actual SecretBackendMetadata object which holds the context path within your Vault server, any path variables required to resolve parametrized context paths and PropertyTransformer.spring-doc.cn

Both, VaultSecretBackendDescriptor and SecretBackendMetadataFactory types must be registered in spring.factories which is an extension mechanism provided by Spring, similar to Java’s ServiceLoader.spring-doc.cn