diff --git a/docs/src/main/asciidoc/secret-management.adoc b/docs/src/main/asciidoc/secret-management.adoc index 9d3784b01..3c4eb223c 100644 --- a/docs/src/main/asciidoc/secret-management.adoc +++ b/docs/src/main/asciidoc/secret-management.adoc @@ -9,8 +9,8 @@ spring-cloud-azure-starter-keyvault-secrets adds Azure Key Vault as one of the S [source,xml] ---- - com.azure.spring - spring-cloud-azure-starter-keyvault-secrets + com.azure.spring + spring-cloud-azure-starter-keyvault-secrets ---- @@ -36,9 +36,10 @@ NOTE: If you choose to use a security principal to authenticate and authorize wi === Basic Usage -==== One property source +==== One Property Source -===== Property configuration +===== Property Configuration +If you want to authenticate by `client-id` and `client-secret`, the following properties are required: [source,yml] ---- @@ -56,30 +57,32 @@ spring: endpoint: ${AZURE_KEYVAULT_ENDPOINT} ---- -===== Java code +If your application is authenticated by other methods like Managed Identity or Azure CLI, properties like `tenant-id`, `client-id`, `client-secret` are not necessary. But if these properties are configured, then these properties have higher priority. Please refer to link:authentication.html[Authentication section] to get more information. + +===== Java Code [source,java] ---- @SpringBootApplication -public class KeyVaultSample implements CommandLineRunner { +public class SampleApplication implements CommandLineRunner { - @Value("${your-property-name}") - private String mySecretProperty; + @Value("${sampleProperty}") + private String sampleProperty; public static void main(String[] args) { - SpringApplication.run(KeyVaultSample.class, args); + SpringApplication.run(SampleApplication.class, args); } @Override public void run(String... args) { - System.out.println("property your-property-name value is: " + mySecretProperty); + System.out.println("sampleProperty: " + sampleProperty); } } ---- -==== Multiple property source +==== Multiple Property Source -===== Property configuration +===== Property Configuration [source,yml] ---- @@ -90,53 +93,83 @@ spring: secret: property-source-enabled: true property-sources: - - - name: key-vault-1 - endpoint: ${ENDPOINT_1} - profile: - tenant-id: ${AZURE_TENANT_ID_1} - credential: - client-id: ${AZURE_CLIENT_ID_1} - client-secret: ${AZURE_CLIENT_SECRET_1} - - - name: key-vault-2 - endpoint: ${ENDPOINT_2} - profile: - tenant-id: ${AZURE_TENANT_ID_2} - credential: - client-id: ${AZURE_CLIENT_ID_2} - client-secret: ${AZURE_CLIENT_SECRET_2} + - + name: key-vault-1 + endpoint: ${ENDPOINT_1} + profile: + tenant-id: ${AZURE_TENANT_ID_1} + credential: + client-id: ${AZURE_CLIENT_ID_1} + client-secret: ${AZURE_CLIENT_SECRET_1} + - + name: key-vault-2 + endpoint: ${ENDPOINT_2} + profile: + tenant-id: ${AZURE_TENANT_ID_2} + credential: + client-id: ${AZURE_CLIENT_ID_2} + client-secret: ${AZURE_CLIENT_SECRET_2} ---- +Same as above, properties like `tenant-id`, `client-id`, `client-secret` are not necessary if authenticate by other methods. -===== Java code +===== Java Code [source,java] ---- @SpringBootApplication public class SampleApplication implements CommandLineRunner { - @Value("${secret-name-in-key-vault-1}") - private String secretNameInKeyVault1; - @Value("${secret-name-in-key-vault-2}") - private String secretNameInKeyVault2; - @Value("${secret-name-in-key-vault-both}") - private String secretNameInKeyVaultBoth; + @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("secretNameInKeyVault1: " + secretNameInKeyVault1); - System.out.println("secretNameInKeyVault2: " + secretNameInKeyVault2); - System.out.println("secretNameInKeyVaultBoth: " + secretNameInKeyVaultBoth); + System.out.println("sampleProperty1: " + sampleProperty1); + System.out.println("sampleProperty2: " + sampleProperty2); + System.out.println("samplePropertyInMultipleKeyVault: " + samplePropertyInMultipleKeyVault); } } ---- +=== Advanced Usage + +==== Special characters in property name +Key Vault secret name only support characters in `[0-9a-zA-Z-]`. Refs: link:https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name[Vault-name and Object-name]. If your property name contains other characters, you can use these workarounds: + +===== Use `-` Instead of `.` In Secret Name + +`.` is not supported in secret name. If your application have property name which contain `.`, like `spring.datasource.url`, just replace `.` to `-` when save secret in Azure Key Vault. For example: Save `spring-datasource-url` in Azure Key Vault. In your application, you can still use `spring.datasource.url` to retrieve property value. + +===== Use Property Placeholders + +For example: setting this property in your application.properties: +[source,properties] +---- +property.with.special.character__=${propertyWithoutSpecialCharacter} +---- + +The application will get `propertyWithoutSpecialCharacter` key name and assign its value to `property.with.special.character__`. + +==== Case Sensitive + +To enable case-sensitive mode, you can set the following property: + +[source,properties] +---- +spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive=true +---- + + === Samples -Please refer to link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_4.0[azure-spring-boot-samples] for more details. +Please refer to link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_4.0.0-beta.3/keyvault/spring-cloud-azure-starter-keyvault-secrets[spring-cloud-azure-starter-keyvault-secrets samples] for more details.