The documentation you are viewing is for Dapr v1.13 which is an older version of Dapr. For up-to-date documentation, see the latest version.

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.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName # Required
    value: [your_keyvault_name]
  - name: azureEnvironment # Optional, defaults to AZUREPUBLICCLOUD
    value: "AZUREPUBLICCLOUD"
  # See authentication section below for all options
  - name: azureTenantId
    value: "[your_service_principal_tenant_id]"
  - name: azureClientId
    value: "[your_service_principal_app_id]"
  - name: azureCertificateFile
    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

Field Required Details Example
vaultName Y The name of the Azure Key Vault "mykeyvault"
azureEnvironment N Optional name for the Azure environment if using a different Azure cloud "AZUREPUBLICCLOUD" (default value), "AZURECHINACLOUD", "AZUREUSGOVERNMENTCLOUD", "AZUREGERMANCLOUD"
Auth metadata See 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 Parameter Description
metadata.version_id Version 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:
    Value Description
    SERVICE_PRINCIPAL_ID The 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:
SERVICE_PRINCIPAL_ID="[your_service_principal_object_id]"
  1. Set a variable with the location in which to create all resources:
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:
RG_NAME="[resource_group_name]"
RG_ID=$(az group create \
  --name "${RG_NAME}" \
  --location "${LOCATION}" \
  | jq -r .id)
  1. Create an Azure Key Vault that uses Azure RBAC for authorization:
KEYVAULT_NAME="[key_vault_name]"
az keyvault create \
  --name "${KEYVAULT_NAME}" \
  --enable-rbac-authorization true \
  --resource-group "${RG_NAME}" \
  --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.
az role assignment create \
  --assignee "${SERVICE_PRINCIPAL_ID}" \
  --role "Key Vault Secrets User" \
  --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:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    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:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureCertificateFile
    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:

    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.

    apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    secretKeyRef:
      name: "[your_k8s_secret_name]"
      key: "[your_k8s_secret_key]"
auth:
  secretStore: kubernetes

  3. Apply the azurekeyvault.yaml component:

    kubectl apply -f azurekeyvault.yaml

Using a certificate

  1. Create a Kubernetes secret using the following command:

    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.

    apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureCertificate
    secretKeyRef:
      name: "[your_k8s_secret_name]"
      key: "[your_k8s_secret_key]"
auth:
  secretStore: kubernetes

  3. Apply the azurekeyvault.yaml component:

    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.

    apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: azurekeyvault
spec:
  type: secretstores.azure.keyvault
  version: v1
  metadata:
  - name: vaultName
    value: "[your_keyvault_name]"

  3. Apply the azurekeyvault.yaml component:

    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
    apiVersion: v1
kind: Pod
metadata:
  name: mydaprdemoapp
  labels:
    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