Make sure all features are included in secret-management.adoc.
This commit is contained in:
Rujun Chen
Родитель
aec065bb1a
Коммит
98d17d7169
|
|
@ -2,9 +2,14 @@
|
|||
|
||||
== Secret Management
|
||||
|
||||
spring-cloud-azure-starter-keyvault-secrets adds Azure Key Vault as one of the Spring PropertySource, so secrets stored in Azure Key Vault could be easily used and conveniently accessed like other externalized configuration property, e.g. properties in files.
|
||||
About link:https://docs.microsoft.com/azure/key-vault/secrets/about-secrets[Azure Key Vault secrets], 2 features are provided:
|
||||
|
||||
=== Dependency Setup
|
||||
- Construct link:https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-property-source-abstraction[PropertySource] which holds secrets stored in Azure Key Vault secret.
|
||||
- Autoconfigure beans for link:https://docs.microsoft.com/azure/key-vault/secrets/quick-create-java[Azure Key Vault Secret Clients]. This feature is new added for SpringCloudAzure:4.0.
|
||||
|
||||
=== Construct PropertySource Which Holds Secrets Stored in Key Vault Secret
|
||||
|
||||
==== Dependency Setup
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -14,76 +19,11 @@ spring-cloud-azure-starter-keyvault-secrets adds Azure Key Vault as one of the S
|
|||
</dependency>
|
||||
----
|
||||
|
||||
=== Configuration
|
||||
==== Basic Usage
|
||||
|
||||
NOTE: If you choose to use a security principal to authenticate and authorize with Azure Active Directory for accessing an Azure resource, please refer to link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure AD] to make sure the security principal has been granted the sufficient permission to access the Azure resource.
|
||||
|
||||
.Configurable properties of spring-cloud-azure-starter-keyvault-secrets
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Property |Description
|
||||
| *spring.cloud.azure.keyvault.secret*.endpoint | Key Vault uri
|
||||
| *spring.cloud.azure.keyvault.secret*.service-version | Service version
|
||||
| *spring.cloud.azure.keyvault.secret*.property-source-enabled | Enable this property source
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources | Multiple property source
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].name | Name of this property source
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].endpoint | Key Vault uri
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].service-version | Service version
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].case-sensitive | Whether the secret name is case-sensitive
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].secret-keys | The supported secret names. If not configured, it will retrieve all secret names.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].refresh-interval | Refresh interval
|
||||
|===
|
||||
|
||||
=== Basic Usage
|
||||
|
||||
==== One Property Source
|
||||
|
||||
===== Property Configuration
|
||||
If you want to authenticate by `client-id` and `client-secret`, the following properties are required:
|
||||
|
||||
[source,yml]
|
||||
----
|
||||
spring:
|
||||
cloud:
|
||||
azure:
|
||||
profile:
|
||||
tenant-id: ${AZURE_TENANT_ID}
|
||||
credential:
|
||||
client-id: ${AZURE_CLIENT_ID}
|
||||
client-secret: ${AZURE_CLIENT_SECRET}
|
||||
keyvault:
|
||||
secret:
|
||||
property-source-enabled: true
|
||||
endpoint: ${AZURE_KEYVAULT_ENDPOINT}
|
||||
----
|
||||
|
||||
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 SampleApplication implements CommandLineRunner {
|
||||
|
||||
@Value("${sampleProperty}")
|
||||
private String sampleProperty;
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(SampleApplication.class, args);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void run(String... args) {
|
||||
System.out.println("sampleProperty: " + sampleProperty);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== Multiple Property Source
|
||||
|
||||
===== Property Configuration
|
||||
|
||||
===== Configuration Properties
|
||||
[source,yml]
|
||||
----
|
||||
spring:
|
||||
|
|
@ -91,32 +31,23 @@ spring:
|
|||
azure:
|
||||
keyvault:
|
||||
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-property-souece-1
|
||||
endpoint: ${ENDPOINT_1}
|
||||
- name: key-vault-property-souece-2
|
||||
endpoint: ${ENDPOINT_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]
|
||||
----
|
||||
package com.azure.spring.keyvault.secrets.sample.single.property.source;
|
||||
|
||||
import org.springframework.beans.factory.annotation.Value;
|
||||
import org.springframework.boot.CommandLineRunner;
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
|
||||
@SpringBootApplication
|
||||
public class SampleApplication implements CommandLineRunner {
|
||||
|
||||
|
|
@ -140,39 +71,136 @@ public class SampleApplication implements CommandLineRunner {
|
|||
}
|
||||
----
|
||||
|
||||
=== Advanced Usage
|
||||
==== 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/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:
|
||||
1. Special Characters in Property Name. Key Vault secret name only support characters in `[0-9a-zA-Z-]`. Refs: link:https://docs.microsoft.com/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. **NOTE**: This method can not satisfy requirement like `spring.datasource-url`. When you save `spring-datasource-url` in Key Vault, only `spring.datasource.url` and `spring-datasource-url` is supported to retrieve property value, `spring.datasource-url` is not supported. To handle this case, please refer to the following option: Use property placeholders.
|
||||
- Use property placeholders. For example: setting this property in your application.properties: `property.with.special.character_=${propertyWithoutSpecialCharacter}`. The application will get `propertyWithoutSpecialCharacter` key name and assign its value to `property.with.special.character_`.
|
||||
|
||||
===== Use `-` Instead of `.` in Secret Name
|
||||
2. Case Sensitive. By default, the secret names are case-insensitive. To enable case-sensitive mode, just set the following property: `spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive=true`.
|
||||
|
||||
`.` 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.
|
||||
3. Not retrieve all secrets in Key Vault. If you stored 1000 secrets in the Key Vault, and you just want to use 3 of them. You can list the 3 secret names by `spring.cloud.azure.keyvault.secret.property-sources[].secret-keys`.
|
||||
|
||||
NOTE: This method can not satisfy requirement like `spring.datasource-url`. When you save `spring-datasource-url` in Key Vault, only `spring.datasource.url` and `spring-datasource-url` is supported to retrieve property value, `spring.datasource-url` is not supported. To handle this case, please refer to the following section: Use property placeholders.
|
||||
4. Setting refresh interval. By default, the secrets in `KeyVaultPropertySource` will refresh every 30 minutes. You can configure the time by `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval`. For example: `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval=60m` means refresh every 60 minutes. Set to `0` to disable auto-refresh.
|
||||
|
||||
===== Use Property Placeholders
|
||||
5. PropertySource priority. If key exists in multiple PropertySources, which will take effect is decided by the priority.
|
||||
- If there is no `SystemEnvironmentPropertySource` in PropertySource list, then `KeyVaultPropertySource` will take the highest priority.
|
||||
- If there is `SystemEnvironmentPropertySource` in PropertySource list, then `SystemEnvironmentPropertySource` have higher priority than KeyVaultPropertySource. Which means you can use environment variable to override the Key Vault secret value in your application.
|
||||
- If there is multiple KeyVaultPropertySource in PropertySource list, then the definition order is the priority order. Take above sample as example, `key-vault-property-souece-1` has higher priority than `key-vault-property-souece-2`.
|
||||
|
||||
For example: setting this property in your application.properties:
|
||||
[source,properties]
|
||||
6. All configurable properties.
|
||||
|
||||
.Configurable properties of Key Vault Secret PropertySource
|
||||
[cols="<45,<5,<50", options="header"]
|
||||
|===
|
||||
| Property | Default value | Description
|
||||
| *spring.cloud.azure.keyvault.secret*.property-source-enabled | true | Whether to enable the Key Vault property source.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].name | | Name of this property source.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].endpoint | | Azure Key Vault endpoint.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].case-sensitive | false | Whether the secret keys are case-sensitive.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].secret-keys | | The secret keys supported for this property source. All keys be retrieved if this property is not configured.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].refresh-interval| 30m | Time interval to refresh all Key Vault secrets.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].service-version | | Secret service version used when making API requests.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].client | | Client related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].credential | | Credential related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].profile | | Profile related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].proxy | | Proxy related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.property-sources[].retry | | Retry related properties.
|
||||
|===
|
||||
|
||||
- Please refer to link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure AD] to make sure the link:https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals#service-principal-object[security principal] has been granted the sufficient permission to access the Azure Key Vault secrets.
|
||||
- If common properties like `client`, `credential`, `profile`, `proxy`, `retry` are not configured in `spring.cloud.azure.keyvault.secret.property-sources[].xxx`, `spring.cloud.azure.xxx` will be used. Please refer to link:index.html#configuration[Configuration] to get more information about these common properties.
|
||||
- Please refer to link:appendix.html#_configuration_properties[Configuration Properties] to get more information about nested properties.
|
||||
|
||||
==== Samples
|
||||
|
||||
Sample project: link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}/keyvault/spring-cloud-azure-starter-keyvault-secrets/property-source[property-source].
|
||||
|
||||
|
||||
=== Auto Configure beans for Azure Key Vault Secret Clients
|
||||
|
||||
==== Dependency Setup
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
property.with.special.character__=${propertyWithoutSpecialCharacter}
|
||||
<dependency>
|
||||
<groupId>com.azure.spring</groupId>
|
||||
<artifactId>spring-cloud-azure-starter-keyvault-secrets</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
The application will get `propertyWithoutSpecialCharacter` key name and assign its value to `property.with.special.character__`.
|
||||
==== Basic Usage
|
||||
|
||||
==== Case Sensitive
|
||||
|
||||
To enable case-sensitive mode, you can set the following property:
|
||||
|
||||
[source,properties]
|
||||
===== Configuration Properties
|
||||
[source,yml]
|
||||
----
|
||||
spring.cloud.azure.keyvault.secret.property-sources[].case-sensitive=true
|
||||
spring:
|
||||
cloud:
|
||||
azure:
|
||||
keyvault:
|
||||
secret:
|
||||
endpoint: ${AZURE_KEYVAULT_ENDPOINT}
|
||||
----
|
||||
|
||||
===== Java code
|
||||
[source,java]
|
||||
----
|
||||
package com.azure.spring.keyvault.secrets.sample.secret.client;
|
||||
|
||||
=== Samples
|
||||
import com.azure.security.keyvault.secrets.SecretClient;
|
||||
import org.springframework.beans.factory.annotation.Value;
|
||||
import org.springframework.boot.CommandLineRunner;
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
|
||||
@SpringBootApplication
|
||||
public class SampleApplication implements CommandLineRunner {
|
||||
|
||||
Please refer to link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}/keyvault/spring-cloud-azure-starter-keyvault-secrets[spring-cloud-azure-starter-keyvault-secrets samples] for more details.
|
||||
private final SecretClient secretClient;
|
||||
|
||||
public SampleApplication(SecretClient secretClient) {
|
||||
this.secretClient = secretClient;
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(SampleApplication.class, args);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void run(String... args) {
|
||||
System.out.println("sampleProperty: " + secretClient.getSecret("sampleProperty").getValue());
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== Advanced Usage
|
||||
|
||||
1. Provided other client related beans. Here is the list:
|
||||
- SecretClient: Provides synchronous methods to manage secrets in the Azure Key Vault.
|
||||
- SecretAsyncClient: Provides asynchronous methods to manage secrets in the Azure Key Vault.
|
||||
- SecretClientBuilder: Provides a fluent builder API to help aid the configuration and instantiation of the SecretClient and SecretAsyncClient.
|
||||
|
||||
2. All configurable properties.
|
||||
|
||||
.Configurable properties of Key Vault Clients
|
||||
[cols="<45,<5,<50", options="header"]
|
||||
|===
|
||||
| Property | Default value | Description
|
||||
| *spring.cloud.azure.keyvault.secret*.enable | true | Whether enable autoconfigure Key Vault Secret Client related beans.
|
||||
| *spring.cloud.azure.keyvault.secret*.endpoint | | Azure Key Vault endpoint.
|
||||
| *spring.cloud.azure.keyvault.secret*.service-version | | Secret service version used when making API requests.
|
||||
| *spring.cloud.azure.keyvault.secret*.client | | Client related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.credential | | Credential related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.profile | | Profile related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.proxy | | Proxy related properties.
|
||||
| *spring.cloud.azure.keyvault.secret*.retry | | Retry related properties.
|
||||
|===
|
||||
|
||||
- Please refer to link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure AD] to make sure the link:https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals#service-principal-object[security principal] has been granted the sufficient permission to access the Azure Key Vault secrets.
|
||||
- If common properties like `client`, `credential`, `profile`, `proxy`, `retry` are not configured in `spring.cloud.azure.keyvault.secret.xxx`, `spring.cloud.azure.xxx` will be used. Please refer to link:index.html#configuration[Configuration] to get more information about these common properties.
|
||||
- Please refer to link:appendix.html#_configuration_properties[Configuration Properties] to get more information about nested properties.
|
||||
|
||||
===== Samples
|
||||
|
||||
Sample project: link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}/keyvault/spring-cloud-azure-starter-keyvault-secrets/secret-client[secret-client].
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче