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.

• See the secret store components guide on how to create and apply a secret store configuration.
• See the guide on referencing secrets to retrieve and use the secret with Dapr components.
• See the Configure the component section below.

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

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:

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

• Self-Hosted
• Kubernetes

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:

   • Microsoft Entra ID workload identity (preferred method)
   • Microsoft Entra ID pod identity

   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

• Authenticating to Azure
• Azure CLI: keyvault commands
• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference