Spring Cloud Azure 秘密管理

本文適用於：✅ 4.19.0 版 ✅ 5.20.1 版

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 中儲存密碼時，將 . 取代為 -。 例如，將 spring-datasource-url 儲存在 Azure Key Vault 中。 在您的應用程式中，您仍然可以使用 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 中的所有秘密

如果您將 1000 個秘密儲存在 Key Vault 中，而您只想使用其中 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 中，則會由優先順序決定。

• 如果 SystemEnvironmentPropertySource 清單中沒有 PropertySource，則 KeyVaultPropertySource 會採用最高優先順序。
• 如果 SystemEnvironmentPropertySource 清單中有 PropertySource，則 SystemEnvironmentPropertySource 優先順序高於 KeyVaultPropertySource，這表示您可以使用環境變數來覆寫應用程式中的 Key Vault 秘密值。
• 如果 PropertySource 清單中有多個金鑰保存庫屬性來源，則定義順序是優先順序。 以上述範例為例，key-vault-property-source-1 的優先順序高於 key-vault-property-source-2。

設定 Key Vault 屬性來源的令牌認證

如果您需要針對 Key Vault PropertySource使用指定的令牌認證，您可以在 KeyVaultEnvironmentPostProcessor的 ConfigurableBootstrapContext 中註冊 TokenCredential 豆，則 Spring Cloud Azure 5.20.1 支援此功能。 以下是使用 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		Proxy 相關屬性。
spring.cloud.azure.keyvault.secret.property-sources[].retry		重試相關的屬性。

• 請參閱 使用 Microsoft Entra ID 授權存取權，以確定 安全性主體 已獲得存取 Azure Key Vault 秘密的足夠許可權。
• 如果 client、credential、profile、proxy、retry 等通用屬性未在 spring.cloud.azure.keyvault.secret.property-sources[].xxx中設定，則會使用 spring.cloud.azure.xxx。 請參閱 Spring Cloud Azure 組態，以取得這些通用屬性的詳細資訊。
• 如需巢狀屬性的詳細資訊，請參閱 Spring Cloud Azure 組態屬性。

樣品

請參閱 gitHub 上的 spring-cloud-azure-starter-keyvault-secrets 範例。