This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Secrets management

Securely access secrets from your application

1 - Secrets management overview

Overview of secrets management API building block

Applications usually store sensitive information in secrets by using a dedicated secret store. For example, you authenticate databases, services, and external systems with connection strings, keys, tokens, and other application-level secrets stored in a secret store, such as AWS Secrets Manager, Azure Key Vault, Hashicorp Vault, etc.

To access these secret stores, the application imports the secret store SDK, often requiring a fair amount of unrelated boilerplate code. This poses an even greater challenge in multi-cloud scenarios, where different vendor-specific secret stores may be used.

Secrets management API

Dapr’s dedicated secrets building block API makes it easier for developers to consume application secrets from a secret store. To use Dapr’s secret store building block, you:

  1. Set up a component for a specific secret store solution.
  2. Retrieve secrets using the Dapr secrets API in the application code.
  3. Optionally, reference secrets in Dapr component files.

The following overview video and demo demonstrates how Dapr secrets management works.

Features

The secrets management API building block brings several features to your application.

Configure secrets without changing application code

You can call the secrets API in your application code to retrieve and use secrets from Dapr supported secret stores. Watch this video for an example of how the secrets management API can be used in your application.

For example, the diagram below shows an application requesting the secret called “mysecret” from a secret store called “vault” from a configured cloud secret store.

A service getting a secret from a configured cloud secret store through its Dapr sidecarOn the left, a green hexagon named App. A line with a head at each end joins it to a hexagon carrying the Dapr logo, named Dapr sidecar. A second such line joins the sidecar to a dashed area captioned Cloud secret stores, which holds the marks and names of four stores in two columns: AWS Secrets Manager, Azure Key Vault, Google Key Management and HashiCorp Vault. Below the service and its sidecar is a card holding the exchange between them: GET over the path /v1.0/secrets/vault/mysecret, and under it the value that comes back, mysecret "supersecret".AppDapr sidecarCloud secret storesAWS SecretsManagerAzureKey VaultGoogle KeyManagementHashiCorpVaultGET/v1.0/secrets/vault/mysecret

Applications can also use the secrets API to access secrets from a Kubernetes secret store. By default, Dapr enables a built-in Kubernetes secret store in Kubernetes mode, deployed via:

  • The Helm defaults, or
  • dapr init -k

If you are using another secret store, you can disable (not configure) the Dapr Kubernetes secret store by adding the annotation dapr.io/disable-builtin-k8s-secret-store: "true" to the deployment.yaml file. The default is false.

In the example below, the application retrieves the same secret “mysecret” from a Kubernetes secret store.

A service in a Kubernetes pod getting a secret from the built-in Kubernetes secret storeA dashed region captioned Kubernetes cluster. Inside it on the left, a dashed pod holds a green hexagon named App joined by a line with a head at each end to a hexagon carrying the Dapr logo, named Dapr sidecar. To the right of the pod, still inside the cluster, is the Kubernetes mark named Kubernetes secret store, joined to the sidecar by another line with a head at each end. Below the cluster is a card holding the exchange: GET over the path /v1.0/secrets/kubernetes/mysecret, and under it the value that comes back, mysecret "supersecret".Kubernetes clusterPodAppDapr sidecarKubernetessecret storeGET/v1.0/secrets/kubernetes/mysecret

In Azure, you can configure Dapr to retrieve secrets using managed identities to authenticate with Azure Key Vault. In the example below:

  1. An Azure Kubernetes Service (AKS) cluster is configured to use managed identities.
  2. Dapr uses pod identities to retrieve secrets from Azure Key Vault on behalf of the application.
A service in an AKS pod getting a secret from Azure Key Vault using a pod managed identityA dashed region captioned AKS cluster. Inside it, a dashed pod holds a green hexagon named App joined by a line with a head at each end to a hexagon carrying the Dapr logo, named Dapr sidecar. Under the sidecar, still inside the pod, is a box named Pod managed identity, joined to the sidecar. Outside the cluster on the right is the Azure Key Vault mark, named Azure Key Vault, joined to the sidecar by a line with a head at each end. Below the cluster is a card holding the exchange: GET over the path /v1.0/secrets/vault/mysecret, and under it the value that comes back, mysecret "supersecret".AKS clusterPodAppDapr sidecarPod managed identityAzureKey VaultGET/v1.0/secrets/vault/mysecret

In the examples above, the application code did not have to change to get the same secret. Dapr uses the secret management components via the secrets management building block API.

Try out the secrets API using one of our quickstarts or tutorials.

Reference secret stores in Dapr components

When configuring Dapr components such as state stores, you’re often required to include credentials in components files. Alternatively, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is the preferred approach and recommended best practice, especially in production environments.

When running in Kubernetes and referencing secrets from the built-in Kubernetes secret store, Dapr also automatically reloads components when the referenced secret values change, for example when a credential is rotated, without restarting the application. This is enabled by default using the hot reloading feature.

For more information, read referencing secret stores in components and updating referenced secrets.

Limit access to secrets

To provide more granular control on access to secrets, Dapr provides the ability to define scopes and restricting access permissions. Learn more about using secret scoping

Try out secrets management

Quickstarts and tutorials

Want to put the Dapr secrets management API to the test? Walk through the following quickstart and tutorials to see Dapr secrets in action:

Quickstart/tutorialDescription
Secrets management quickstartRetrieve secrets in the application code from a configured secret store using the secrets management API.
Secret Store tutorialDemonstrates the use of Dapr Secrets API to access secret stores.

Start managing secrets directly in your app

Want to skip the quickstarts? Not a problem. You can try out the secret management building block directly in your application to retrieve and manage secrets. After Dapr is installed, you can begin using the secrets management API starting with the secrets how-to guide.

Next steps

2 - How To: Retrieve a secret

Use the secret store building block to securely retrieve a secret

Now that you’ve learned what the Dapr secrets building block provides, learn how it can work in your service. This guide demonstrates how to call the secrets API and retrieve secrets in your application code from a configured secret store.

A service retrieving a secret through its Dapr sidecar from a local secret storeAlong the top, three shapes in a row: a green hexagon named Order Processor, a hexagon carrying the Dapr logo named Dapr sidecar, and a padlock in a box named Secret store. A line with a head at each end joins each to the next. Under the service and its sidecar is the call it makes: GET over the path /v1.0/secrets/localsecretstore/secret. Along the bottom, under the shape each configures, are three cards. Order Processor service holds SECRET_STORE_NAME set to localsecretstore and SECRET_NAME set to secret. local-secret-store.yaml holds a component named localsecretstore, of type secretstores.local.file, whose metadata sets secretsFile to secrets.json. secrets.json holds the key secret with the value Order Processing pass key.OrderProcessorDapr sidecarSecret store/v1.0/secrets/localsecretstore/secretGETOrder Processor serviceSECRET_STORE_NAME =  "localsecretstore"SECRET_NAME = "secret"local-secret-store.yamlapiVersion: dapr.io/v1alpha1kind: Componentmetadata:  name: localsecretstorespec:  type: secretstores.local.file  version: v1  metadata:  - name: secretsFile    value: secrets.jsonsecrets.json{   "secret": "Order Processing pass key"}

Set up a secret store

Before retrieving secrets in your application’s code, you must configure a secret store component. This example configures a secret store that uses a local JSON file to store secrets.

In your project directory, create a file named secrets.json with the following contents:

{
   "secret": "Order Processing pass key"
}

Create a new directory named components. Navigate into that directory and create a component file named local-secret-store.yaml with the following contents:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: localsecretstore
spec:
  type: secretstores.local.file
  version: v1
  metadata:
  - name: secretsFile
    value: secrets.json  #path to secrets file
  - name: nestedSeparator
    value: ":"

For more information:

Get a secret

Get the secret by calling the Dapr sidecar using the secrets API:

curl http://localhost:3601/v1.0/secrets/localsecretstore/secret

See a full API reference.

Calling the secrets API from your code

Now that you’ve set up the local secret store, call Dapr to get the secrets from your application code. Below are code examples that leverage Dapr SDKs for retrieving a secret.

using System;
using System.Threading.Tasks;
using Dapr.Client;

namespace EventService;

const string SECRET_STORE_NAME = "localsecretstore";

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprClient();
var app = builder.Build();

//Resolve a DaprClient from DI
var daprClient = app.Services.GetRequiredService<DaprClient>();

//Use the Dapr SDK to get a secret
var secret = await daprClient.GetSecretAsync(SECRET_STORE_NAME, "secret");

Console.WriteLine($"Result: {string.Join(", ", secret)}");
//dependencies
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.dapr.client.DaprClient;
import io.dapr.client.DaprClientBuilder;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Map;


//code
@SpringBootApplication
public class OrderProcessingServiceApplication {

    private static final Logger log = LoggerFactory.getLogger(OrderProcessingServiceApplication.class);
    private static final ObjectMapper JSON_SERIALIZER = new ObjectMapper();

    private static final String SECRET_STORE_NAME = "localsecretstore";

    public static void main(String[] args) throws InterruptedException, JsonProcessingException {
        DaprClient client = new DaprClientBuilder().build();
        //Using Dapr SDK to get a secret
        Map<String, String> secret = client.getSecret(SECRET_STORE_NAME, "secret").block();
        log.info("Result: " + JSON_SERIALIZER.writeValueAsString(secret));
    }
}
#dependencies 
import random
from time import sleep    
import requests
import logging
from dapr.clients import DaprClient
from dapr.clients.grpc._state import StateItem
from dapr.clients.grpc._request import TransactionalStateOperation, TransactionOperationType

#code
logging.basicConfig(level = logging.INFO)
DAPR_STORE_NAME = "localsecretstore"
key = 'secret'

with DaprClient() as client:
    #Using Dapr SDK to get a secret
    secret = client.get_secret(store_name=DAPR_STORE_NAME, key=key)
    logging.info('Result: ')
    logging.info(secret.secret)
    #Using Dapr SDK to get bulk secrets
    secret = client.get_bulk_secret(store_name=DAPR_STORE_NAME)
    logging.info('Result for bulk secret: ')
    logging.info(sorted(secret.secrets.items()))
//dependencies 
import (
	"context"
	"log"

	dapr "github.com/dapr/go-sdk/client"
)

//code
func main() {
	client, err := dapr.NewClient()
	SECRET_STORE_NAME := "localsecretstore"
	if err != nil {
		panic(err)
	}
	defer client.Close()
	ctx := context.Background()
     //Using Dapr SDK to get a secret
	secret, err := client.GetSecret(ctx, SECRET_STORE_NAME, "secret", nil)
	if secret != nil {
		log.Println("Result : ")
		log.Println(secret)
	}
    //Using Dapr SDK to get bulk secrets
	secretBulk, err := client.GetBulkSecret(ctx, SECRET_STORE_NAME, nil)

	if secret != nil {
		log.Println("Result for bulk: ")
		log.Println(secretBulk)
	}
}
//dependencies 
import { DaprClient, HttpMethod, CommunicationProtocolEnum } from '@dapr/dapr'; 

//code
const daprHost = "127.0.0.1"; 

async function main() {
    const client = new DaprClient({
        daprHost,
        daprPort: process.env.DAPR_HTTP_PORT,
        communicationProtocol: CommunicationProtocolEnum.HTTP,
    });
    const SECRET_STORE_NAME = "localsecretstore";
    //Using Dapr SDK to get a secret
    var secret = await client.secret.get(SECRET_STORE_NAME, "secret");
    console.log("Result: " + secret);
    //Using Dapr SDK to get bulk secrets
    secret = await client.secret.getBulk(SECRET_STORE_NAME);
    console.log("Result for bulk: " + secret);
}

main();

3 - How To: Use secret scoping

Use scoping to limit the secrets that can be read by your application from secret stores

Once you configure a secret store for your application, any secret defined within that store is accessible by default from the Dapr application.

You can limit the Dapr application’s access to specific secrets by defining secret scopes. Simply add a secret scope policy to the application configuration with restrictive permissions.

The secret scoping policy applies to any secret store, including:

  • A local secret store
  • A Kubernetes secret store
  • A public cloud secret store

For details on how to set up a secret store, read How To: Retrieve a secret.

Watch this video for a demo on how to use secret scoping with your application.

Scenario 1 : Deny access to all secrets for a secret store

In this example, all secret access is denied to an application running on a Kubernetes cluster, which has a configured Kubernetes secret store named mycustomsecretstore. Aside from the user-defined custom store, the example also configures the Kubernetes default store (named kubernetes) to ensure all secrets are denied access. Learn more about the Kubernetes default secret store.

Define the following appconfig.yaml configuration and apply it to the Kubernetes cluster using the command kubectl apply -f appconfig.yaml.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  secrets:
    scopes:
      - storeName: kubernetes
        defaultAccess: deny
      - storeName: mycustomsecreststore
        defaultAccess: deny

For applications that need to be denied access to the Kubernetes secret store, follow these instructions, and add the following annotation to the application pod:

dapr.io/config: appconfig

With this defined, the application no longer has access to any secrets in the Kubernetes secret store.

Scenario 2 : Allow access to only certain secrets in a secret store

This example uses a secret store named vault. This could be a Hashicorp secret store component set on your application. To allow a Dapr application to have access to only secret1 and secret2 in the vault secret store, define the following appconfig.yaml:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  secrets:
    scopes:
      - storeName: vault
        defaultAccess: deny
        allowedSecrets: ["secret1", "secret2"]

The default access to the vault secret store is deny, while some secrets are accessible by the application, based on the allowedSecrets list. Learn how to apply configuration to the sidecar.

Scenario 3: Deny access to certain sensitive secrets in a secret store

Define the following config.yaml:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  secrets:
    scopes:
      - storeName: vault
        defaultAccess: allow # this is the default value, line can be omitted
        deniedSecrets: ["secret1", "secret2"]

This example configuration explicitly denies access to secret1 and secret2 from the secret store named vault while allowing access to all other secrets. Learn how to apply configuration to the sidecar.

Permission priority

The allowedSecrets and deniedSecrets list values take priority over the defaultAccess policy.

ScenariosdefaultAccessallowedSecretsdeniedSecretspermission
1 - Only default accessdeny/allowemptyemptydeny/allow
2 - Default deny with allowed listdeny[“s1”]emptyonly “s1” can be accessed
3 - Default allow with deneied listallowempty[“s1”]only “s1” cannot be accessed
4 - Default allow with allowed listallow[“s1”]emptyonly “s1” can be accessed
5 - Default deny with denied listdenyempty[“s1”]deny
6 - Default deny/allow with both listsdeny/allow[“s1”][“s2”]only “s1” can be accessed