Azure Key Vault secret store

Detailed information on the Azure Key Vault secret store component

Component format

To setup Azure Key Vault secret store, create a component of type secretstores.azure.keyvault.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: azurekeyvault
  5. spec:
  6.   type: secretstores.azure.keyvault
  7.   version: v1
  8.   metadata:
  9.   - name: vaultName # Required
  10.     value: [your_keyvault_name]
  11.   - name: azureEnvironment # Optional, defaults to AZUREPUBLICCLOUD
  12.     value: "AZUREPUBLICCLOUD"
  13.   # See authentication section below for all options
  14.   - name: azureTenantId
  15.     value: "[your_service_principal_tenant_id]"
  16.   - name: azureClientId
  17.     value: "[your_service_principal_app_id]"
  18.   - name: azureCertificateFile
  19.     value : "[pfx_certificate_file_fully_qualified_local_path]"

Authenticating with Microsoft Entra ID

The Azure Key Vault secret store component supports authentication with Microsoft Entra ID only. Before you enable this component:

  1. Read the Authenticating to Azure document.
  2. Create an Microsoft Entra ID application (also called Service Principal).
  3. Alternatively, create a managed identity for your application platform.

Spec metadata fields

FieldRequiredDetailsExample
vaultNameYThe name of the Azure Key Vault“mykeyvault”
azureEnvironmentNOptional name for the Azure environment if using a different Azure cloud“AZUREPUBLICCLOUD” (default value), “AZURECHINACLOUD”, “AZUREUSGOVERNMENTCLOUD”, “AZUREGERMANCLOUD”
Auth metadataSee Authenticating to Azure for more information

Additionally, you must provide the authentication fields as explained in the Authenticating to Azure document.

Optional per-request metadata properties

The following optional query parameters can be provided when retrieving secrets from this secret store:

Query ParameterDescription
metadata.version_idVersion for the given secret key.
metadata.maxresults(For bulk requests only) Number of secrets to return, after which the request will be truncated.

Example

前期准备

  • Azure Subscription
  • Azure CLI
  • jq
  • You are using bash or zsh shell

  • You’ve created an Microsoft Entra ID application (Service Principal) per the instructions in Authenticating to Azure. You will need the following values:

    ValueDescription
    SERVICE_PRINCIPAL_IDThe ID of the Service Principal that you created for a given application

Create an Azure Key Vault and authorize a Service Principal

  1. Set a variable with the Service Principal that you created:
  1. SERVICE_PRINCIPAL_ID="[your_service_principal_object_id]"
  1. Set a variable with the location in which to create all resources:
  1. LOCATION="[your_location]"

(You can get the full list of options with: az account list-locations --output tsv)

  1. Create a Resource Group, giving it any name you’d like:
  1. RG_NAME="[resource_group_name]"
  2. RG_ID=$(az group create \
  3.   --name "${RG_NAME}" \
  4.   --location "${LOCATION}" \
  5.   | jq -r .id)
  1. Create an Azure Key Vault that uses Azure RBAC for authorization:
  1. KEYVAULT_NAME="[key_vault_name]"
  2. az keyvault create \
  3.   --name "${KEYVAULT_NAME}" \
  4.   --enable-rbac-authorization true \
  5.   --resource-group "${RG_NAME}" \
  6.   --location "${LOCATION}"
  1. Using RBAC, assign a role to the Microsoft Entra ID application so it can access the Key Vault.
    In this case, assign the “Key Vault Secrets User” role, which has the “Get secrets” permission over Azure Key Vault.
  1. az role assignment create \
  2.   --assignee "${SERVICE_PRINCIPAL_ID}" \
  3.   --role "Key Vault Secrets User" \
  4.   --scope "${RG_ID}/providers/Microsoft.KeyVault/vaults/${KEYVAULT_NAME}"

Other less restrictive roles, like “Key Vault Secrets Officer” and “Key Vault Administrator”, can be used, depending on your application. See Microsoft Docs for more information about Azure built-in roles for Key Vault.

Configure the component

Using a client secret

To use a client secret, create a file called azurekeyvault.yaml in the components directory. Use the following template, filling in the Microsoft Entra ID application you created:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: azurekeyvault
  5. spec:
  6.   type: secretstores.azure.keyvault
  7.   version: v1
  8.   metadata:
  9.   - name: vaultName
  10.     value: "[your_keyvault_name]"
  11.   - name: azureTenantId
  12.     value: "[your_tenant_id]"
  13.   - name: azureClientId
  14.     value: "[your_client_id]"
  15.   - name: azureClientSecret
  16.     value : "[your_client_secret]"

Using a certificate

If you want to use a certificate saved on the local disk instead, use the following template. Fill in the details of the Microsoft Entra ID application you created:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: azurekeyvault
  5. spec:
  6.   type: secretstores.azure.keyvault
  7.   version: v1
  8.   metadata:
  9.   - name: vaultName
  10.     value: "[your_keyvault_name]"
  11.   - name: azureTenantId
  12.     value: "[your_tenant_id]"
  13.   - name: azureClientId
  14.     value: "[your_client_id]"
  15.   - name: azureCertificateFile
  16.     value : "[pfx_certificate_file_fully_qualified_local_path]"

In Kubernetes, you store the client secret or the certificate into the Kubernetes Secret Store and then refer to those in the YAML file. Before you start, you need the details of the Microsoft Entra ID application you created.

Using a client secret

  1. Create a Kubernetes secret using the following command:

    1. kubectl create secret generic [your_k8s_secret_name] --from-literal=[your_k8s_secret_key]=[your_client_secret]
    • [your_client_secret] is the application’s client secret as generated above
    • [your_k8s_secret_name] is secret name in the Kubernetes secret store
    • [your_k8s_secret_key] is secret key in the Kubernetes secret store

  2. Create an azurekeyvault.yaml component file.

    The component yaml refers to the Kubernetes secretstore using auth property and secretKeyRef refers to the client secret stored in the Kubernetes secret store.

    1. apiVersion: dapr.io/v1alpha1
    2. kind: Component
    3. metadata:
    4.   name: azurekeyvault
    5. spec:
    6.   type: secretstores.azure.keyvault
    7.   version: v1
    8.   metadata:
    9.   - name: vaultName
    10.     value: "[your_keyvault_name]"
    11.   - name: azureTenantId
    12.     value: "[your_tenant_id]"
    13.   - name: azureClientId
    14.     value: "[your_client_id]"
    15.   - name: azureClientSecret
    16.     secretKeyRef:
    17.       name: "[your_k8s_secret_name]"
    18.       key: "[your_k8s_secret_key]"
    19. auth:
    20.   secretStore: kubernetes

  3. Apply the azurekeyvault.yaml component:

    1. kubectl apply -f azurekeyvault.yaml

Using a certificate

  1. Create a Kubernetes secret using the following command:

    1. kubectl create secret generic [your_k8s_secret_name] --from-file=[your_k8s_secret_key]=[pfx_certificate_file_fully_qualified_local_path]
    • [pfx_certificate_file_fully_qualified_local_path] is the path of PFX file you obtained earlier
    • [your_k8s_secret_name] is secret name in the Kubernetes secret store
    • [your_k8s_secret_key] is secret key in the Kubernetes secret store

  2. Create an azurekeyvault.yaml component file.

    The component yaml refers to the Kubernetes secretstore using auth property and secretKeyRef refers to the certificate stored in the Kubernetes secret store.

    1. apiVersion: dapr.io/v1alpha1
    2. kind: Component
    3. metadata:
    4.   name: azurekeyvault
    5. spec:
    6.   type: secretstores.azure.keyvault
    7.   version: v1
    8.   metadata:
    9.   - name: vaultName
    10.     value: "[your_keyvault_name]"
    11.   - name: azureTenantId
    12.     value: "[your_tenant_id]"
    13.   - name: azureClientId
    14.     value: "[your_client_id]"
    15.   - name: azureCertificate
    16.     secretKeyRef:
    17.       name: "[your_k8s_secret_name]"
    18.       key: "[your_k8s_secret_key]"
    19. auth:
    20.   secretStore: kubernetes

  3. Apply the azurekeyvault.yaml component:

    1. kubectl apply -f azurekeyvault.yaml

Using Azure managed identity

  1. Ensure your AKS cluster has managed identity enabled and follow the guide for using managed identities.

  2. Create an azurekeyvault.yaml component file.

    The component yaml refers to a particular KeyVault name. The managed identity you will use in a later step must be given read access to this particular KeyVault instance.

    1. apiVersion: dapr.io/v1alpha1
    2. kind: Component
    3. metadata:
    4.   name: azurekeyvault
    5. spec:
    6.   type: secretstores.azure.keyvault
    7.   version: v1
    8.   metadata:
    9.   - name: vaultName
    10.     value: "[your_keyvault_name]"

  3. Apply the azurekeyvault.yaml component:

    1. kubectl apply -f azurekeyvault.yaml

  4. Create and assign a managed identity at the pod-level via either:

    Important: While both Microsoft Entra ID pod identity and workload identity are in preview, currently Microsoft Entra ID Workload Identity is planned for general availability (stable state).

  5. After creating a workload identity, give it read permissions:

    • On your desired KeyVault instance
    • In your application deployment. Inject the pod identity both:
      • Via a label annotation
      • By specifying the Kubernetes service account associated with the desired workload identity
    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: mydaprdemoapp
    5.   labels:
    6.     aadpodidbinding: $POD_IDENTITY_NAME

Using Azure managed identity directly vs. via Microsoft Entra ID workload identity

When using managed identity directly, you can have multiple identities associated with an app, requiring azureClientId to specify which identity should be used.

However, when using managed identity via Microsoft Entra ID workload identity, azureClientId is not necessary and has no effect. The Azure identity to be used is inferred from the service account tied to an Azure identity via the Azure federated identity.

References