Управление секретами Spring Cloud Azure

Конструкция Spring Cloud Azure PropertySource, которая содержит секреты, хранящиеся в Azure Key Vault Secrets.

Настройка зависимостей

<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-]. Дополнительные сведения см. в разделе Vault-name and Object-name статьи Обзор ключей, секретов и сертификатов Azure Key Vault. Если имя свойства содержит другие символы, можно использовать обходные пути, описанные в следующих разделах.

Используйте - вместо . в именах секретов

. не поддерживается в именах секретов. Если у приложения есть имя свойства, содержащее ., например spring.datasource.url, замените . на - при сохранении секрета в Azure Key Vault. Например, сохраните spring-datasource-url в Azure Key Vault. В приложении можно по-прежнему использовать spring.datasource.url для получения значения свойства.

Заметка

Этот метод не может удовлетворить требование, например spring.datasource-url. При сохранении spring-datasource-url в Key Vault поддерживается только 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 из них. Вы можете перечислить 3 названия секретов с помощью spring.cloud.azure.keyvault.secret.property-sources[].secret-keys.

Настройка интервала обновления

По умолчанию секреты в 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, вы можете зарегистрировать bean TokenCredential в ConfigurableBootstrapContext для KeyVaultEnvironmentPostProcessor. Эта функция поддерживается, начиная с Spring Cloud Azure 5.16.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	30 м	Интервал времени для обновления всех секретов 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.
• Если общие свойства, такие как client, credential, profile, proxy, retry не настроены в spring.cloud.azure.keyvault.secret.property-sources[].xxx, будут использоваться spring.cloud.azure.xxx. Дополнительные сведения об этих общих свойствах см. в конфигурации Spring Cloud Azure.
• Дополнительные сведения о вложенных свойствах см. в разделе Свойства конфигурации Azure Spring Cloud.

Образцы

См. примерыspring-cloud-azure-starter-keyvault-secrets на сайте GitHub.