Secret Backends

DeepSeek V3 中英对照 Secret Backends

键值存储后端

Spring Cloud Vault 同时支持版本化（v2）和非版本化（v1）的键值对（Key-Value）密钥后端。键值对后端允许将任意值作为键值对存储。单个上下文可以存储一个或多个键值对元组。上下文可以按层次结构组织。Spring Cloud Vault 会自行判断密钥是否使用版本控制，并将路径映射到相应的 URL。Spring Cloud Vault 允许使用应用程序名称，以及结合活动配置文件的默认上下文名称（application）。

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

应用程序名称由以下属性决定：

• spring.cloud.vault.kv.application-name

• spring.cloud.vault.application-name

• spring.application.name

配置文件由以下属性决定：

• spring.cloud.vault.kv.profiles

• spring.profiles.active

可以通过在应用程序名称后添加其他路径（以逗号分隔）来从键值存储后端中的其他上下文获取密钥。例如，给定应用程序名称 usefulapp,mysql1,projectx/aws，将使用以下每个文件夹：

• /secret/usefulapp

• /secret/mysql1

• /secret/projectx/aws

Spring Cloud Vault 将所有活跃配置文件添加到可能的上下文路径列表中。若没有活跃配置文件，则会跳过访问带有配置文件名称的上下文。

属性会按照它们存储的方式暴露（即不添加额外的前缀）。

备注

Spring Cloud Vault 根据挂载是否使用版本化键值后端，在挂载路径和实际上下文路径之间添加了 data/ 上下文。

spring.cloud.vault:
    kv:
        enabled: true
        backend: secret
        profile-separator: '/'
        default-context: application
        application-name: my-app
        profiles: local, cloud

• enabled 将此值设为 false 将禁用密钥后端配置的使用

• backend 设置要使用的密钥挂载路径

• default-context 设置所有应用程序使用的上下文名称

• application-name 覆盖用于键值后端的应用程序名称

• profiles 覆盖用于键值后端的活动配置文件

• profile-separator 在使用配置文件的属性源中，将配置文件名称与上下文分隔开

备注

键值对密钥后端可以在版本化（v2）和非版本化（v1）两种模式下运行。

另请参阅：

• Vault 文档：使用 KV 密钥引擎 - 版本 1（通用密钥后端）

• Vault 文档：使用 KV 密钥引擎 - 版本 2（版本化键值后端）

Consul

Spring Cloud Vault 可以获取 HashiCorp Consul 的凭据。Consul 集成需要 spring-cloud-vault-config-consul 依赖。

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

可以通过设置 spring.cloud.vault.consul.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.consul.role=… 来启用该集成。

获取到的令牌存储在 spring.cloud.consul.token 中，因此 Spring Cloud Consul 无需额外配置即可使用生成的凭据。您可以通过设置 spring.cloud.vault.consul.token-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 Consul 后端配置的使用

• role 设置 Consul 角色定义的名称

• backend 设置要使用的 Consul 挂载路径

• token-property 设置存储 Consul ACL 令牌的属性名称

另请参阅：Vault 文档：使用 Vault 设置 Consul

RabbitMQ

Spring Cloud Vault 可以获取 RabbitMQ 的凭证。

RabbitMQ 集成需要 spring-cloud-vault-config-rabbitmq 依赖。

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

可以通过设置 spring.cloud.vault.rabbitmq.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.rabbitmq.role=… 来启用该集成。

用户名和密码存储在 spring.rabbitmq.username 和 spring.rabbitmq.password 中，因此使用 Spring Boot 将自动获取生成的凭据，无需额外配置。您可以通过设置 spring.cloud.vault.rabbitmq.username-property 和 spring.cloud.vault.rabbitmq.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 RabbitMQ 后端配置使用

• role 设置 RabbitMQ 角色定义的角色名称

• backend 设置要使用的 RabbitMQ 挂载路径

• username-property 设置存储 RabbitMQ 用户名的属性名称

• password-property 设置存储 RabbitMQ 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 RabbitMQ

AWS

Spring Cloud Vault 可以获取 AWS 的凭据。

AWS 集成需要 spring-cloud-vault-config-aws 依赖项。

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

可以通过设置 spring.cloud.vault.aws=true（默认为 false）并提供角色名称 spring.cloud.vault.aws.role=… 来启用该集成。

支持的 AWS 凭证类型：

• iam_user (默认)

• assumed_role (STS)

• federation_token (STS)

访问密钥和密钥存储在 cloud.aws.credentials.accessKey 和 cloud.aws.credentials.secretKey 中。因此，使用 Spring Cloud AWS 将自动获取生成的凭证，无需额外配置。

你可以通过设置 spring.cloud.vault.aws.access-key-property 和 spring.cloud.vault.aws.secret-key-property 来配置属性名称。

对于STS安全令牌，您可以通过设置spring.cloud.vault.aws.session-token-key-property来配置属性名称。安全令牌存储在cloud.aws.credentials.sessionToken下（默认值）。

示例：iam_user

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

示例：assumed_role (STS)

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 将此值设置为 true 可启用 AWS 后端配置的使用

• role 设置 AWS 角色定义的角色名称

• backend 设置要使用的 AWS 挂载路径

• access-key-property 设置存储 AWS 访问密钥的属性名称

• secret-key-property 设置存储 AWS 密钥的属性名称

• session-token-key-property 设置存储 AWS STS 安全令牌的属性名称

• credential-type 设置用于此后端的 AWS 凭证类型。默认为 iam_user

• ttl 在使用 assumed_role 或 federation_token 时设置 STS 令牌的 ttl。默认为 vault 角色指定的 ttl。最小/最大值也受限于 AWS 对 STS 的支持范围

• role-arn 在使用 assumed_role 时，如果为 vault 角色配置了多个 IAM 角色，则设置要承担的 IAM 角色

另请参阅：Vault 文档：使用 Vault 设置 AWS

数据库后端

Vault 支持多种数据库密钥后端，可根据配置的角色动态生成数据库凭据。这意味着需要访问数据库的服务不再需要配置凭据：它们可以向 Vault 请求凭据，并利用 Vault 的租约机制更轻松地轮换密钥。

Spring Cloud Vault 集成了以下后端：

• 数据库

• Apache Cassandra

• Couchbase 数据库

• Elasticsearch

• MongoDB

• MySQL

• PostgreSQL

使用数据库密钥后端需要在配置中启用后端以及 spring-cloud-vault-config-databases 依赖项。

自 0.7.1 版本起，Vault 内置了一个专用的 database 密钥后端，允许通过插件进行数据库集成。您可以通过使用通用的数据库后端来使用该特定后端。请确保指定适当的后端路径，例如 spring.cloud.vault.mysql.role.backend=database。

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-vault-config-databases</artifactId>
        <version>5.0.1</version>
    </dependency>
</dependencies>

备注

启用多个符合 JDBC 标准的数据库将生成凭据，并默认将它们存储在相同的属性键中，因此需要单独配置 JDBC 密钥的属性名称。

数据库

Spring Cloud Vault 能够获取 www.vaultproject.io/api/secret/databases/index.html 上列出的任何数据库的凭据。通过设置 spring.cloud.vault.database.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.database.role=…，即可启用该集成功能。

虽然数据库后端是通用的，但 spring.cloud.vault.database 专门针对 JDBC 数据库。用户名和密码可以从 spring.datasource.username 和 spring.datasource.password 属性中获取，因此使用 Spring Boot 时，无需额外配置即可为你的 DataSource 获取生成的凭据。你可以通过设置 spring.cloud.vault.database.username-property 和 spring.cloud.vault.database.password-property 来配置属性名称。

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

多数据库

有时，单个数据库的凭据可能不够用，因为应用程序可能需要连接到两个或更多同类型的数据库。从 3.0.5 版本开始，Spring Vault 支持在 spring.cloud.vault.databases.* 命名空间下配置多个数据库密钥后端。

配置支持多种数据库后端，可将凭据具体化到指定属性中。请确保正确配置 username-property 和 password-property。

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> 数据库配置的描述性名称。

• <name>.enabled 将此值设置为 true 可启用数据库后端配置的使用。

• <name>.role 设置数据库角色定义的角色名称。

• <name>.backend 设置要使用的数据库挂载路径。

• <name>.username-property 设置存储数据库用户名的属性名称。请确保使用唯一的属性名称以避免属性遮蔽。

• <name>.password-property 设置存储数据库密码的属性名称。请确保使用唯一的属性名称以避免属性遮蔽。

另请参阅：Vault 文档：数据库密钥后端

注意

Spring Cloud Vault 不支持在达到最大租约时间时获取新凭证并使用它们配置你的 DataSource。也就是说，如果 Vault 中数据库角色的 max_ttl 设置为 24h，这意味着你的应用程序启动 24 小时后，它将无法再与数据库进行身份验证。

Apache Cassandra

备注

cassandra 后端已在 Vault 0.7.1 中弃用，建议使用 database 后端并将其挂载为 cassandra。

Spring Cloud Vault 能够获取 Apache Cassandra 的凭据。通过设置 spring.cloud.vault.cassandra.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.cassandra.role=…，即可启用该集成功能。

用户名和密码可通过 spring.data.cassandra.username 和 spring.data.cassandra.password 属性获取，因此使用 Spring Boot 将自动获取生成的凭据而无需额外配置。您可以通过设置 spring.cloud.vault.cassandra.username-property 和 spring.cloud.vault.cassandra.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 Cassandra 后端配置的使用

• role 设置 Cassandra 角色定义的名称

• backend 设置要使用的 Cassandra 挂载路径

• username-property 设置存储 Cassandra 用户名的属性名称

• password-property 设置存储 Cassandra 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 Apache Cassandra

Couchbase 数据库

Spring Cloud Vault 可以获取 Couchbase 的凭据。通过设置 spring.cloud.vault.couchbase.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.couchbase.role=… 即可启用该集成。

用户名和密码可通过 spring.couchbase.username 和 spring.couchbase.password 属性获取，因此使用 Spring Boot 将自动获取生成的凭据而无需额外配置。您可以通过设置 spring.cloud.vault.couchbase.username-property 和 spring.cloud.vault.couchbase.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 Couchbase 后端配置使用

• role 设置 Couchbase 角色定义的名称

• backend 设置要使用的 Couchbase 挂载路径

• username-property 设置存储 Couchbase 用户名的属性名称

• password-property 设置存储 Couchbase 密码的属性名称

另请参阅：Couchbase 数据库插件文档

Elasticsearch

自 3.0 版本起，Spring Cloud Vault 可以获取 Elasticsearch 的凭据。通过设置 spring.cloud.vault.elasticsearch.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.elasticsearch.role=… 即可启用该集成。

用户名和密码可通过 spring.elasticsearch.rest.username 和 spring.elasticsearch.rest.password 属性获取，因此使用 Spring Boot 将自动获取生成的凭据而无需额外配置。您可以通过设置 spring.cloud.vault.elasticsearch.username-property 和 spring.cloud.vault.elasticsearch.password-property 来配置属性名称。

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

• enabled 将此值设为 true 可启用 Elasticsearch 数据库后端配置

• role 设置 Elasticsearch 角色定义的名称

• backend 设置要使用的 Elasticsearch 挂载路径

• username-property 设置存储 Elasticsearch 用户名的属性名称

• password-property 设置存储 Elasticsearch 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 Elasticsearch

MongoDB

备注

mongodb 后端已在 Vault 0.7.1 中弃用，建议使用 database 后端并将其挂载为 mongodb。

Spring Cloud Vault 可以获取 MongoDB 的凭据。通过设置 spring.cloud.vault.mongodb.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.mongodb.role=…，即可启用此集成。

用户名和密码存储在 spring.data.mongodb.username 和 spring.data.mongodb.password 中，因此使用 Spring Boot 将自动获取生成的凭据，无需额外配置。您可以通过设置 spring.cloud.vault.mongodb.username-property 和 spring.cloud.vault.mongodb.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 MongoDB 后端配置的使用

• role 设置 MongoDB 角色定义的名称

• backend 设置要使用的 MongoDB 挂载路径

• username-property 设置存储 MongoDB 用户名的属性名称

• password-property 设置存储 MongoDB 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 MongoDB

MySQL

备注

mysql 后端已在 Vault 0.7.1 中弃用，建议使用 database 后端并将其挂载为 mysql。spring.cloud.vault.mysql 的配置将在未来版本中移除。

Spring Cloud Vault 可以获取 MySQL 的凭据。通过设置 spring.cloud.vault.mysql.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.mysql.role=… 即可启用该集成。

用户名和密码可通过 spring.datasource.username 和 spring.datasource.password 属性获取，因此使用 Spring Boot 将自动获取生成的凭据，无需额外配置。您可以通过设置 spring.cloud.vault.mysql.username-property 和 spring.cloud.vault.mysql.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 MySQL 后端配置的使用

• role 设置 MySQL 角色定义的名称

• backend 设置要使用的 MySQL 挂载路径

• username-property 设置存储 MySQL 用户名的属性名称

• password-property 设置存储 MySQL 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 MySQL

PostgreSQL

备注

postgresql 后端已在 Vault 0.7.1 中弃用，建议使用 database 后端并将其挂载为 postgresql。spring.cloud.vault.postgresql 的配置将在未来版本中移除。

Spring Cloud Vault 能够获取 PostgreSQL 的凭据。通过设置 spring.cloud.vault.postgresql.enabled=true（默认为 false）并提供角色名称 spring.cloud.vault.postgresql.role=…，即可启用该集成功能。

用户名和密码可通过 spring.datasource.username 和 spring.datasource.password 属性获取，因此使用 Spring Boot 将自动获取生成的凭据，无需额外配置。您可以通过设置 spring.cloud.vault.postgresql.username-property 和 spring.cloud.vault.postgresql.password-property 来配置属性名称。

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

• enabled 将此值设置为 true 可启用 PostgreSQL 后端配置的使用

• role 设置 PostgreSQL 角色定义的角色名称

• backend 设置要使用的 PostgreSQL 挂载路径

• username-property 设置存储 PostgreSQL 用户名的属性名称

• password-property 设置存储 PostgreSQL 密码的属性名称

另请参阅：Vault 文档：使用 Vault 设置 PostgreSQL

自定义要暴露为 PropertySource 的密钥后端

Spring Cloud Vault 使用基于属性的配置来为键值存储和已发现的密钥后端创建 PropertySource。

已发现的后端通过提供 VaultSecretBackendDescriptor bean 来描述配置状态，以便将密钥后端用作 PropertySource。需要 SecretBackendMetadataFactory 来创建包含路径、名称和属性转换配置的 SecretBackendMetadata 对象。

SecretBackendMetadata 用于支持特定的 PropertySource。

你可以注册一个 VaultConfigurer 进行自定义。如果提供了 VaultConfigurer，默认的键值对和已发现的后端注册将被禁用。不过，你可以通过 SecretBackendConfigurer.registerDefaultKeyValueSecretBackends() 和 SecretBackendConfigurer.registerDefaultDiscoveredSecretBackends() 来启用默认注册。

public class MyConfigurer 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.addBootstrapRegistryInitializer(VaultBootstrapper.fromConfigurer(new MyConfigurer()));

自定义密钥后端实现

Spring Cloud Vault 内置了对最常见后端集成的密钥后端支持。您可以通过提供实现来与任何类型的后端集成，该实现描述了如何从您想要使用的后端获取数据，以及如何通过提供 PropertyTransformer 来展示该后端提供的数据。

为后端添加自定义实现需要实现两个接口：

• org.springframework.cloud.vault.config.VaultSecretBackendDescriptor

• org.springframework.cloud.vault.config.SecretBackendMetadataFactory

VaultSecretBackendDescriptor 通常是一个持有配置数据的对象，例如 VaultDatabaseProperties。Spring Cloud Vault 要求您的类型使用 @ConfigurationProperties 进行注解，以便从配置中实例化该类。

SecretBackendMetadataFactory 接受 VaultSecretBackendDescriptor 来创建实际的 SecretBackendMetadata 对象，该对象持有 Vault 服务器内的上下文路径、解析参数化上下文路径所需的任何路径变量以及 PropertyTransformer。

VaultSecretBackendDescriptor 和 SecretBackendMetadataFactory 类型都必须在 spring.factories 中注册，这是 Spring 提供的一种扩展机制，类似于 Java 的 ServiceLoader。