Gestione dei segreti di Spring Cloud di Azure

Spring Cloud Azure costruisce PropertySource che contiene i segreti archiviati nei segreti di Azure Key Vault.

Configurazione delle dipendenze

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

Suggerimento

È anche disponibile spring-cloud-azure-starter-keyvault per supportare tutte le funzionalità di Key Vault. Se si sceglie di usarlo, spring.cloud.azure.keyvault.enable è la proprietà da configurare e il valore predefinito è true. È quindi possibile usare spring.cloud.azure.keyvault.<keyvault-service>.enable per disabilitare i servizi non necessario.

Utilizzo di base

Se si vuole eseguire l'autenticazione tramite client-id e client-secret, sono necessarie le proprietà seguenti:

Proprietà di configurazione

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}

Codice 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);
    }
}

Utilizzo avanzato

Caratteri speciali nel nome della proprietà

I nomi dei segreti di Key Vault supportano solo i caratteri in [0-9a-zA-Z-]. Per altre informazioni, vedere la sezionevault-name e Object-name di panoramica di chiavi, segreti e certificati di Azure Key Vault. Se il nome della proprietà contiene altri caratteri, è possibile usare le soluzioni alternative descritte nelle sezioni seguenti.

Usare - anziché . nei nomi dei segreti

Il carattere . non è supportato nei nomi dei segreti. Se l'applicazione ha un nome di proprietà contenente ., ad esempio spring.datasource.url, sostituire . con - quando si salva il segreto in Azure Key Vault. Ad esempio, salvare spring-datasource-url in Azure Key Vault. Nell'applicazione è comunque possibile usare spring.datasource.url per recuperare il valore della proprietà.

Nota

Questo metodo non può soddisfare un requisito come spring.datasource-url. Quando si salva spring-datasource-url in Key Vault, è supportato solo spring.datasource.url e spring-datasource-url per recuperare il valore della proprietà, ma spring.datasource-url non è supportato. Per gestire questo caso, consultare la sezione Usare i segnaposto delle proprietà.

Utilizza segnaposto di proprietà

Si supponga, ad esempio, di impostare questa proprietà nel file application.properties:

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

L'applicazione otterrà un nome di chiave propertyWithoutSpecialCharacter e assegnerà il relativo valore a property.with.special.character__.

Distinzione tra maiuscole e minuscole

Per abilitare la modalità di distinzione tra maiuscole e minuscole, è possibile impostare la proprietà seguente:

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

Non recuperare tutti i segreti presenti in Key Vault

Se hai archiviato 1000 segreti nel Key Vault e vuoi usarne solo 3. È possibile elencare i 3 nomi dei segreti tramite spring.cloud.azure.keyvault.secret.property-sources[].secret-keys.

Impostazione dell'intervallo di aggiornamento

Per impostazione predefinita, i segreti in KeyVaultPropertySource verranno aggiornati ogni 30 minuti. È possibile configurare l'ora tramite spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval. Ad esempio: spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval=60m significa aggiornare ogni 60 minuti. Impostare su 0 per disabilitare l'aggiornamento automatico.

Priorità di PropertySource

Se la chiave esiste in più PropertySources, che avrà effetto viene deciso in base alla priorità.

• Se nell'elenco SystemEnvironmentPropertySource non sono presenti PropertySource, KeyVaultPropertySource avrà la priorità più alta.
• Se nell'elenco SystemEnvironmentPropertySource sono presenti PropertySource, SystemEnvironmentPropertySource avere una priorità più alta rispetto a KeyVaultPropertySource, il che significa che è possibile usare una variabile di ambiente per eseguire l'override del valore del segreto di Key Vault nell'applicazione.
• Se nell'elenco PropertySource sono presenti più origini delle proprietà dell'insieme di credenziali delle chiavi, l'ordine di definizione corrisponde all'ordine di priorità. Prendendo l'esempio precedente come esempio, key-vault-property-source-1 ha una priorità più alta rispetto a key-vault-property-source-2.

Configurare le credenziali del token per l'origine delle proprietà di Key Vault

Se devi usare una credenziale token specifica per Key Vault PropertySource, puoi registrare il bean TokenCredential in ConfigurableBootstrapContext per KeyVaultEnvironmentPostProcessor; questa funzionalità è supportata a partire da Spring Cloud Azure 5.16.0. Di seguito è riportato un esempio per usare 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);
}

Tutte le proprietà configurabili

Proprietà	Valore predefinito	Descrizione
spring.cloud.azure.keyvault.secret.property-source-enabled	vero	Indica se abilitare l'origine della proprietà Key Vault.
spring.cloud.azure.keyvault.secret.property-sources[].name		Nome di questa sorgente di proprietà.
spring.cloud.azure.keyvault.secret.property-sources[].endpoint		Endpoint di Azure Key Vault.
spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive	falso	Indica se le chiavi segrete fanno distinzione tra maiuscole e minuscole.
spring.cloud.azure.keyvault.secret.property-sources[].secret-keys		Chiavi segrete supportate per questa origine di proprietà. Tutte le chiavi vengono recuperate se questa proprietà non è presente.
spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval	30 metri	Intervallo di tempo per aggiornare tutti i segreti di Key Vault.
spring.cloud.azure.keyvault.secret.property-sources[].service-version		Versione del servizio segreto usata durante l'esecuzione di richieste API.
spring.cloud.azure.keyvault.secret.property-sources[].client		Proprietà correlate al client.
spring.cloud.azure.keyvault.secret.property-sources[].credential		Proprietà relative alle credenziali.
spring.cloud.azure.keyvault.secret.property-sources[].profile		Proprietà correlate al profilo.
spring.cloud.azure.keyvault.secret.property-sources[].proxy		Proprietà relative al proxy.
spring.cloud.azure.keyvault.secret.property-sources[].retry		Riprovare le proprietà correlate.

• Vedere Autorizzare l'accesso con Microsoft Entra ID per assicurarsi che all'entità di sicurezza sia stata concessa l'autorizzazione sufficiente per accedere ai segreti di Azure Key Vault.
• Se proprietà comuni come client, credential, profile, proxy, retry non sono configurate in spring.cloud.azure.keyvault.secret.property-sources[].xxx, verrà usato spring.cloud.azure.xxx. Per altre informazioni su queste proprietà comuni, vedere configurazione di Azure Spring Cloud.
• Per altre informazioni sulle proprietà annidate, vedere proprietà di configurazione di Azure Spring Cloud.

Campioni

Vedere gli spring-cloud-azure-starter-keyvault-secrets esempi in GitHub.