Secret store component specs

• 1: AlibabaCloud OOS Parameter Store
• 2: AWS Secrets Manager
• 3: AWS SSM Parameter Store
• 4: Azure Key Vault secret store
• 5: GCP Secret Manager
• 6: HashiCorp Vault
• 7: HuaweiCloud Cloud Secret Management Service (CSMS)
• 8: Kubernetes secrets
• 9: Local environment variables (for Development)
• 10: Local file (for Development)

The following table lists secret stores supported by the Dapr secrets building block. Learn how to set up different secret stores for Dapr secrets management.

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
HashiCorp Vault	✅	Stable	v1	1.10
Kubernetes secrets	✅	Stable	v1	1.0
Local environment variables		Stable	v1	1.9
Local file	✅	Stable	v1	1.9

Alibaba Cloud

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
AlibabaCloud OOS Parameter Store		Alpha	v1	1.6

Amazon Web Services (AWS)

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
AWS Secrets Manager		Beta	v1	1.15
AWS SSM Parameter Store		Alpha	v1	1.1

Google Cloud Platform (GCP)

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
GCP Secret Manager		Alpha	v1	1.0

Microsoft Azure

Component	Multiple Key-Values Per Secret	Status	Component version	Since runtime version
Azure Key Vault		Stable	v1	1.0

1 - AlibabaCloud OOS Parameter Store

Component format

To setup AlibabaCloud OOS Parameter Store secret store create a component of type secretstores.alicloud.parameterstore. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: alibabacloudparameterstore
spec:
  type: secretstores.alicloud.parameterstore
  version: v1
  metadata:
  - name: regionId
    value: "[alicloud_region_id]"
  - name: accessKeyId 
    value: "[alicloud_access_key_id]"
  - name: accessKeySecret
    value: "[alicloud_access_key_secret]"
  - name: securityToken
    value: "[alicloud_security_token]"

Spec metadata fields

Optional per-request metadata properties

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

Create an AlibabaCloud OOS Parameter Store instance

Setup AlibabaCloud OOS Parameter Store using the AlibabaCloud documentation: https://www.alibabacloud.com/help/en/doc-detail/186828.html.

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference

2 - AWS Secrets Manager

Component format

To setup AWS Secrets Manager secret store create a component of type secretstores.aws.secretmanager. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

See Authenticating to AWS for information about authentication-related attributes.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: awssecretmanager
spec:
  type: secretstores.aws.secretmanager
  version: v1
  metadata:
  - name: region
    value: "[aws_region]"
  - name: accessKey
    value: "[aws_access_key]"
  - name: secretKey
    value: "[aws_secret_key]"
  - name: sessionToken
    value: "[aws_session_token]"

Spec metadata fields

Optional per-request metadata properties

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

Create an AWS Secrets Manager instance

Setup AWS Secrets Manager using the AWS documentation: https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html.

Related links

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

3 - AWS SSM Parameter Store

Component format

To setup AWS SSM Parameter Store secret store create a component of type secretstores.aws.parameterstore. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

See Authenticating to AWS for information about authentication-related attributes.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: awsparameterstore
spec:
  type: secretstores.aws.parameterstore
  version: v1
  metadata:
  - name: region
    value: "[aws_region]"
  - name: accessKey
    value: "[aws_access_key]"
  - name: secretKey
    value: "[aws_secret_key]"
  - name: sessionToken
    value: "[aws_session_token]"
  - name: prefix
    value: "[secret_name]"

Spec metadata fields

Create an AWS SSM Parameter Store instance

Setup AWS SSM Parameter Store using the AWS documentation: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html.

Related links

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

4 - Azure Key Vault secret store

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

Prerequisites

• 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

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]"

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]"

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

5 - GCP Secret Manager

Component format

To setup GCP Secret Manager secret store create a component of type secretstores.gcp.secretmanager. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: gcpsecretmanager
spec:
  type: secretstores.gcp.secretmanager
  version: v1
  metadata:
  - name: type
    value: <replace-with-account-type>
  - name: project_id
    value: <replace-with-project-id>
  - name: private_key_id
    value: <replace-with-private-key-id>
  - name: client_email
    value: <replace-with-email>
  - name: client_id
    value: <replace-with-client-id>
  - name: auth_uri
    value: <replace-with-auth-uri>
  - name: token_uri
    value: <replace-with-token-uri>
  - name: auth_provider_x509_cert_url
    value: <replace-with-auth-provider-cert-url>
  - name: client_x509_cert_url
    value: <replace-with-client-cert-url>
  - name: private_key
    value: <replace-with-private-key>

Spec metadata fields

GCP Credentials

Since the GCP Secret Manager component uses the GCP Go Client Libraries, by default it authenticates using Application Default Credentials. This is explained further in the Authenticate to GCP Cloud services using client libraries guide. Also, see how to Set up Application Default Credentials.

Optional per-request metadata properties

The following optional query parameters can be provided to the GCP Secret Manager component:

Setup GCP Secret Manager instance

Setup GCP Secret Manager using the GCP documentation: https://cloud.google.com/secret-manager/docs/quickstart.

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference

6 - HashiCorp Vault

Create the Vault component

To setup HashiCorp Vault secret store create a component of type secretstores.hashicorp.vault. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: vault
spec:
  type: secretstores.hashicorp.vault
  version: v1
  metadata:
  - name: vaultAddr
    value: [vault_address] # Optional. Default: "https://127.0.0.1:8200"
  - name: caCert # Optional. This or caPath or caPem
    value: "[ca_cert]"
  - name: caPath # Optional. This or CaCert or caPem
    value: "[path_to_ca_cert_file]"
  - name: caPem # Optional. This or CaCert or CaPath
    value : "[encoded_ca_cert_pem]"
  - name: skipVerify # Optional. Default: false
    value : "[skip_tls_verification]"
  - name: tlsServerName # Optional.
    value : "[tls_config_server_name]"
  - name: vaultTokenMountPath # Required if vaultToken not provided. Path to token file.
    value : "[path_to_file_containing_token]"
  - name: vaultToken # Required if vaultTokenMountPath not provided. Token value.
    value : "[path_to_file_containing_token]"
  - name: vaultKVPrefix # Optional. Default: "dapr"
    value : "[vault_prefix]"
  - name: vaultKVUsePrefix # Optional. default: "true"
    value: "[true/false]"
  - name: enginePath # Optional. default: "secret"
    value: "secret"
  - name: vaultValueType # Optional. default: "map"
    value: "map"

Spec metadata fields

Optional per-request metadata properties

The following optional query parameters can be provided to Hashicorp Vault secret store component:

Setup Hashicorp Vault instance

• Self-Hosted
• Kubernetes

Multiple key-values per secret

HashiCorp Vault supports multiple key-values in a secret. While this behavior is ultimately dependent on the underlying secret engine configured by enginePath, it may change the way you store and retrieve keys from Vault. For instance, multiple key-values in a secret is the behavior exposed in the secret engine, the default engine configured by the enginePath field.

When retrieving secrets, a JSON payload is returned with the key names as fields and their respective values.

Suppose you add a secret to your Vault setup as follows:

vault kv put secret/dapr/mysecret firstKey=aValue secondKey=anotherValue thirdKey=yetAnotherDistinctValue

In the example above, the secret is named mysecret and it has 3 key-values under it. Observe that the secret is created under a dapr prefix, as this is the default value for the vaultKVPrefix flag. Retrieving it from Dapr would result in the following output:

$ curl http://localhost:3501/v1.0/secrets/my-hashicorp-vault/mysecret

{
  "firstKey": "aValue",
  "secondKey": "anotherValue",
  "thirdKey": "yetAnotherDistinctValue"
}

Notice that the name of the secret (mysecret) is not repeated in the result.

TLS Server verification

The fields skipVerify, tlsServerName, caCert, caPath, and caPem control if and how Dapr verifies the vault server’s certificate while connecting using TLS/HTTPS.

Inline CA PEM caPem

The caPem field value should be the contents of the PEM CA certificate you want to use. Given PEM certificates are made of multiple lines, defining that value might seem challenging at first. YAML allows for a few ways of defining a multiline values.

Below is one way to define a caPem field.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: vault
spec:
  type: secretstores.hashicorp.vault
  version: v1
  metadata:
  - name: vaultAddr
    value: https://127.0.0.1:8200
  - name: caPem
    value: |-
          -----BEGIN CERTIFICATE-----
          << the rest of your PEM file content's here, indented appropriately. >>
          -----END CERTIFICATE-----

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference

7 - HuaweiCloud Cloud Secret Management Service (CSMS)

Component format

To setup HuaweiCloud Cloud Secret Management Service (CSMS) secret store create a component of type secretstores.huaweicloud.csms. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: huaweicloudcsms
spec:
  type: secretstores.huaweicloud.csms
  version: v1
  metadata:
  - name: region
    value: "[huaweicloud_region]"
  - name: accessKey 
    value: "[huaweicloud_access_key]"
  - name: secretAccessKey
    value: "[huaweicloud_secret_access_key]"

Spec metadata fields

Optional per-request metadata properties

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

Setup HuaweiCloud Cloud Secret Management Service (CSMS) instance

Setup HuaweiCloud Cloud Secret Management Service (CSMS) using the HuaweiCloud documentation: https://support.huaweicloud.com/intl/en-us/usermanual-dew/dew_01_9993.html.

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference

8 - Kubernetes secrets

Default Kubernetes secret store component

When Dapr is deployed to a Kubernetes cluster, a secret store with the name kubernetes is automatically provisioned. This pre-provisioned secret store allows you to use the native Kubernetes secret store with no need to author, deploy or maintain a component configuration file for the secret store and is useful for developers looking to simply access secrets stored natively in a Kubernetes cluster.

A custom component definition file for a Kubernetes secret store can still be configured (See below for details). Using a custom definition decouples referencing the secret store in your code from the hosting platform as the store name is not fixed and can be customized, keeping your code more generic and portable. Additionally, by explicitly defining a Kubernetes secret store component you can connect to a Kubernetes secret store from a local Dapr self-hosted installation. This requires a valid kubeconfig file.

Create a custom Kubernetes secret store component

To setup a Kubernetes secret store create a component of type secretstores.kubernetes. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mycustomsecretstore
spec:
  type: secretstores.kubernetes
  version: v1
  metadata:[]

Spec metadata fields

Optional per-request metadata properties

The following optional query parameters can be provided to Kubernetes secret store component:

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference
• How To: Use secret scoping

9 - Local environment variables (for Development)

This Dapr secret store component uses locally defined environment variable and does not use authentication.

Component format

To setup local environment variables secret store create a component of type secretstores.local.env. Create a file with the following content in your ./components directory:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: envvar-secret-store
spec:
  type: secretstores.local.env
  version: v1
  metadata:
    # - name: prefix
    #   value: "MYAPP_"

Spec metadata fields

Notes

For security reasons, this component cannot be used to access these environment variables:

• APP_API_TOKEN
• Any variable whose name begins with the DAPR_ prefix

Related Links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference

10 - Local file (for Development)

This Dapr secret store component reads plain text JSON from a given file and does not use authentication.

Component format

To setup local file based secret store create a component of type secretstores.local.file. Create a file with the following content in your ./components directory:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: local-secret-store
spec:
  type: secretstores.local.file
  version: v1
  metadata:
  - name: secretsFile
    value: [path to the JSON file]
  - name: nestedSeparator
    value: ":"
  - name: multiValued
    value: "false"

Spec metadata fields

Setup JSON file to hold the secrets

Given the following JSON loaded from secretsFile:

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "sql": "your sql connection string",
        "mysql": "your mysql connection string"
    }
}

The flag multiValued determines whether the secret store presents a name/value behavior or a multiple key-value per secret behavior.

Name/Value semantics

If multiValued is false, the store loads the JSON file and create a map with the following key-value pairs:

If the multiValued setting set to true, invoking a GET request on the key connectionStrings results in a 500 HTTP response and an error message. For example:

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "errorCode": "ERR_SECRET_GET",
  "message": "failed getting secret with key connectionStrings from secret store local-secret-store: secret connectionStrings not found"
}

This error is expected, since the connectionStrings key is not present, per the table above.

However, requesting for flattened key connectionStrings:sql would result in a successful response, with the following:

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings:sql

{
  "connectionStrings:sql": "your sql connection string"
}

Multiple key-values behavior

If multiValued is true, the secret store enables multiple key-value per secret behavior:

• Nested structures after the top level will be flattened.
• It parses the same JSON file into this table:

Notice that in the above table:

• connectionStrings is now a JSON object with two keys: mysql and sql.
• The connectionStrings:sql and connectionStrings:mysql flattened keys from the table mapped for name/value semantics are missing.

Invoking a GET request on the key connectionStrings now results in a successful HTTP response similar to the following:

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "sql": "your sql connection string",
  "mysql": "your mysql connection string"
}

Meanwhile, requesting for the flattened key connectionStrings:sql would now return a 500 HTTP error response with the following:

{
  "errorCode": "ERR_SECRET_GET",
  "message": "failed getting secret with key connectionStrings:sql from secret store local-secret-store: secret connectionStrings:sql not found"
}

Handling deeper nesting levels

Notice that, as stated in the spec metadata fields table, multiValued only handles a single nesting level.

Let’s say you have a local file secret store with multiValued enabled, pointing to a secretsFile with the following JSON content:

{
    "redisPassword": "your redis password",
    "connectionStrings": {
        "mysql": {
          "username": "your mysql username",
          "password": "your mysql password"
        }
    }
}

The contents of key mysql under connectionStrings has a nesting level greater than 1 and would be flattened.

Here is how it would look in memory:

Once again, requesting for key connectionStrings results in a successful HTTP response but its contents, as shown in the table above, would be flattened:

$ curl http://localhost:3501/v1.0/secrets/local-secret-store/connectionStrings

{
  "mysql:username": "your mysql username",
  "mysql:password": "your mysql password"
}

This is useful in order to mimic secret stores like Vault or Kubernetes that return multiple key/value pairs per secret key.

Related links

• Secrets building block
• How-To: Retrieve a secret
• How-To: Reference secrets in Dapr components
• Secrets API reference