Spring Cloud Azure 机密管理

本文 适用于：✅ 版本 4.19.0 ✅ 版本 5.19.0

Spring Cloud Azure 构造 PropertySource，用于保存存储在 Azure Key Vault 机密中的机密。

依赖项设置

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-keyvault-secrets</artifactId>
</dependency>

提示

我们还提供 spring-cloud-azure-starter-keyvault 来支持 Key Vault 的所有功能。 如果选择使用它，spring.cloud.azure.keyvault.enable 是要配置的属性，默认值 true。 然后，可以使用 spring.cloud.azure.keyvault.<keyvault-service>.enable 禁用不需要的服务。

基本用法

如果要通过 client-id 和 client-secret进行身份验证，则需要以下属性：

配置属性

spring:
  cloud:
    azure:
      keyvault:
        secret:
          property-sources:
            - name: key-vault-property-source-1
              endpoint: ${ENDPOINT_1}
            - name: key-vault-property-source-2
              endpoint: ${ENDPOINT_2}

Java 代码

@SpringBootApplication
public class SampleApplication implements CommandLineRunner {

    @Value("${sampleProperty1}")
    private String sampleProperty1;
    @Value("${sampleProperty2}")
    private String sampleProperty2;
    @Value("${samplePropertyInMultipleKeyVault}")
    private String samplePropertyInMultipleKeyVault;

    public static void main(String[] args) {
        SpringApplication.run(SampleApplication.class, args);
    }

    public void run(String[] args) {
        System.out.println("sampleProperty1: " + sampleProperty1);
        System.out.println("sampleProperty2: " + sampleProperty2);
        System.out.println("samplePropertyInMultipleKeyVault: " + samplePropertyInMultipleKeyVault);
    }
}

高级用法

属性名称中的特殊字符

Key Vault 机密名称仅支持 [0-9a-zA-Z-]中的字符。 有关详细信息，请参阅 Azure Key Vault 密钥、机密和证书的Vault 名称和对象名称 部分。 如果属性名称包含其他字符，则可以使用以下部分中所述的解决方法。

在机密名称中使用 - 而不是 .

机密名称不支持 .。 如果应用程序具有包含 .（如 spring.datasource.url）的属性名称，请在 Azure Key Vault 中保存机密时将 . 替换为 -。 例如，在 Azure Key Vault 中保存 spring-datasource-url。 在应用程序中，仍可以使用 spring.datasource.url 来检索属性值。

注意

此方法不能满足 spring.datasource-url等要求。 在 Key Vault 中保存 spring-datasource-url 时，仅支持 spring.datasource.url 和 spring-datasource-url 来检索属性值，但不支持 spring.datasource-url。 若要处理这种情况，请参阅 使用属性占位符 部分。

使用属性占位符

例如，假设你在 application.properties 文件中设置此属性：

property.with.special.character__=${propertyWithoutSpecialCharacter}

应用程序将获取 propertyWithoutSpecialCharacter 密钥名称，并将其值分配给 property.with.special.character__。

区分大小写

若要启用区分大小写的模式，可以设置以下属性：

spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive=true

不检索 Key Vault 中的所有机密

如果在 Key Vault 中存储了 1000 个机密，并且只想使用其中 3 个机密。 可以通过 spring.cloud.azure.keyvault.secret.property-sources[].secret-keys列出 3 个机密名称。

设置刷新间隔

默认情况下，KeyVaultPropertySource 中的机密每 30 分钟刷新一次。 可以通过 spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval来配置时间。 例如：spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval=60m 意味着每 60 分钟刷新一次。 设置为 0 以禁用自动刷新。

PropertySource 优先级

如果多个 PropertySources 中存在键，则会由优先级决定。

• 如果 PropertySource 列表中没有 SystemEnvironmentPropertySource，则 KeyVaultPropertySource 将采用最高优先级。
• 如果 PropertySource 列表中存在 SystemEnvironmentPropertySource，则 SystemEnvironmentPropertySource 优先级高于 KeyVaultPropertySource，这意味着可以使用环境变量替代应用程序中的 Key Vault 机密值。
• 如果 PropertySource 列表中有多个 Key Vault 属性源，则定义顺序为优先级顺序。 以上述示例为例，key-vault-property-source-1 优先级高于 key-vault-property-source-2。

为 Key Vault 属性源配置令牌凭据

如果需要为 Key Vault PropertySource使用指定的令牌凭据，可以在 KeyVaultEnvironmentPostProcessor的 ConfigurableBootstrapContext 中注册 TokenCredential bean，则 Spring Cloud Azure 5.19.0 支持此功能。 下面是使用 AzureCliCredential的示例：

public static void main(String[] args) {
    SpringApplication application = new SpringApplication(PropertySourceApplication.class);
    application.addBootstrapRegistryInitializer(registry -> 
            registry.register(TokenCredential.class, context -> new AzureCliCredentialBuilder().build()));

    application.run(args);
}

所有可配置属性

财产	默认值	描述
spring.cloud.azure.keyvault.secret.property-source-enabled	真	是否启用 Key Vault 属性源。
spring.cloud.azure.keyvault.secret.property-sources[].name		此属性源的名称。
spring.cloud.azure.keyvault.secret.property-sources[].endpoint		Azure Key Vault 终结点。
spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive	假	密钥是否区分大小写。
spring.cloud.azure.keyvault.secret.property-sources[].secret-keys		此属性源支持的密钥。 如果缺少此属性，则检索所有密钥。
spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval	30m	刷新所有 Key Vault 机密的时间间隔。
spring.cloud.azure.keyvault.secret.property-sources[].service-version		发出 API 请求时使用的机密服务版本。
spring.cloud.azure.keyvault.secret.property-sources[].client		客户端相关属性。
spring.cloud.azure.keyvault.secret.property-sources[].credential		凭据相关属性。
spring.cloud.azure.keyvault.secret.property-sources[].profile		配置文件相关属性。
spring.cloud.azure.keyvault.secret.property-sources[].proxy		代理相关属性。
spring.cloud.azure.keyvault.secret.property-sources[].retry		重试相关属性。

• 请参阅 使用 Microsoft Entra ID 授权访问，以确保 安全主体 已授予访问 Azure Key Vault 机密的足够权限。
• 如果未在 spring.cloud.azure.keyvault.secret.property-sources[].xxx中配置通用属性（如 client、credential、profile、proxy）retry，则使用 spring.cloud.azure.xxx。 请参阅 Spring Cloud Azure 配置，获取有关这些常见属性的详细信息。
• 请参阅 Spring Cloud Azure 配置属性，获取有关嵌套属性的详细信息。

样品

请参阅 GitHub 上的 spring-cloud-azure-starter-keyvault-secrets 示例。