From f3e3b9c9c39986f59619b5083e8ccce4a0be5892 Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Tue, 11 Feb 2020 09:45:14 -0800 Subject: [PATCH] Add mTLS How To (#345) * Add mTLS How To * yaml format * Update README.md * go to * Update README.md * Update README.md Co-authored-by: Mark Fussell --- howto/README.md | 4 + howto/configure-mtls/README.md | 199 +++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 howto/configure-mtls/README.md diff --git a/howto/README.md b/howto/README.md index f30d6f79f..2f2014e95 100644 --- a/howto/README.md +++ b/howto/README.md @@ -30,6 +30,10 @@ Here you'll find a list of How To guides that walk you through accomplishing spe * [Diagnose your services with distributed tracing](./diagnose-with-tracing) +## Mutual Transport Layer Security (TLS) + +* [Setup and configure mutual TLS between Dapr instances](./configure-mtls) + ## Secrets * [Configure secrets using Dapr secret stores](./setup-secret-store) diff --git a/howto/configure-mtls/README.md b/howto/configure-mtls/README.md new file mode 100644 index 000000000..fc195c7dd --- /dev/null +++ b/howto/configure-mtls/README.md @@ -0,0 +1,199 @@ +# Setup and Configure Mututal TLS + +Dapr supports in-transit encryption of communication between Dapr instances using Sentry, a central Certificate Authority. + +Dapr allows operators and developers to bring in their own certificates, or let Dapr automatically create and persist self signed root and issuer certificates. + +For detailed information on mTLS, go to the concepts section [here](../../concepts/security/security.md). + +If custom certificates have not been provided, Dapr will automaically create and persist self signed certs valid for one year. +In Kubernetes, the certs are persisted to a secret that resides in the namespace of the Dapr system pods, accessible only to them. +In Self Hosted mode, the certs are persisted to disk. More information on that is shown below. + +## Sentry Configuration + +mTLS settings reside in a Dapr configuration file. +The following file shows all the available settings for mTLS in a configuration resource: + +``` +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: default +spec: + mtls: + enabled: true + workloadCertTTL: "24h" + allowedClockSkew: "15m" +``` + +The file here shows the default configuration settings. The examples below show you how to change and apply this configuration to Sentry in Kubernetes and Self hosted modes. + + +## Kubernetes + +### Setting up mTLS with the configuration resource + +In Kubernetes, Dapr creates a default configuration resource with mTLS enabled. +Sentry, the certificate authority system pod, is installed both with Helm and with the Dapr CLI using `dapr init --kubernetes`. + +Depending on how you install Dapr, this resource may reside in the `default` namespace if you installed Dapr using the Dapr CLI, or the `dapr-system` namespace if deployed using Helm. + +You can view the configuration resource with the following command: + +`kubectl get configurations/default --namespace -o yaml`. + +To make changes to the configuration resource, you can run the following command to edit it: + +``` +kubectl edit configurations/default --namespace +``` + +Once the changes are saved, you need to restart the Sentry pod in order for the changes to take effect. +You can restart Sentry using the following command: + +``` +kubectl delete pod --selector=app=dapr-sentry --namespace +``` + +### Viewing logs + +In order to view Sentry logs, run the following command: + +``` +kubectl logs --selector=app=dapr-sentry --namespace +``` + +### Bringing your own certificates + +Using Helm, you can provide the PEM encoded root cert, issuer cert and private key that will be populated into the Kubernetes secret. + +*Note: This example uses the step tool to create the certificates. You can install step [here](https://smallstep.com/docs/getting-started/). Windows binaries available [here](https://github.com/smallstep/cli/releases)* + +Create the root certificate: + +``` +step certificate create cluster.local ca.crt ca.key --profile root-ca --no-password --insecure +``` + +Create the issuer certificate: + +``` +step certificate create cluster.local issuer.crt issuer.key --ca ca.crt --ca-key ca.key --profile intermediate-ca --not-after 8760h --no-password --insecure +``` + +This creates the root and issuer certs and keys. + +Install Helm and pass the root cert, issuer cert and issuer key to Sentry via configuration: + +``` +kubectl create ns dapr-system + +helm install \ + --set-file dapr_sentry.tls.issuer.certPEM=issuer.crt \ + --set-file dapr_sentry.tls.issuer.keyPEM=issuer.key \ + --set-file dapr_sentry.tls.root.certPEM=ca.crt \ + --namespace dapr-system \ + dapr \ + dapr/dapr +``` + +## Self-hosted + +### Running Sentry System Service + +In order to run Sentry, you can either build from source, or download a release binary from [here](https://github.com/dapr/dapr/releases). + +When building from source, please refer to [this](https://github.com/dapr/dapr/blob/master/docs/development/developing-dapr.md#build-the-dapr-binaries) guide on how to build Dapr. + +Second, create a directory for Sentry to create the self signed root certs: + +``` +mkdir -p $HOME/.dapr/certs +``` + +Run Sentry locally with the following command: + +``` +./sentry --issuer-credentials $HOME/.dapr/certs --trust-domain cluster.local +``` + +If successful, sentry will run and create the root certs in the given directory. +This command uses default configuration values as no custom config file was given. See below on how to start Sentry with a custom configuration. + +### Setting up mTLS with the configuration resource + +#### Dapr instance configuration + +When running Dapr in self hosted mode, mTLS is disabled by default. you can enable it by creating the following configuration file: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: default +spec: + mtls: + enabled: true +``` + +If using the Dapr CLI, point Dapr to the config file above to run the Dapr instance with mTLS enabled: + +``` +dapr run --app-id myapp --config ./config.yaml node myapp.js +``` + +If using `daprd` directly, use the following flags to enable mTLS: + +``` +daprd --app-id myapp --enable-mtls --sentry-address localhost:50001 --config=./config.yaml +``` + +#### Sentry configuration + +Here's an example of a configuration for Sentry that changes the workload cert TTL to 25 seconds: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: default +spec: + mtls: + enabled: true + workloadCertTTL: "25s" +``` + +In order to start Sentry with a custom config, use the following flag: + +``` +./sentry --issuer-credentials $HOME/.dapr/certs --trust-domain cluster.local --config=./config.yaml +``` + +### Bringing your own certificates + +In order to provide your own credentials, create ECDSA PEM encoded root and issuer certificates and place them on the file system. +Tell Sentry where to load the certificates from using the `--issuer-credentials` flag. + +The next examples creates root and issuer certs and loads them with Sentry. + +*Note: This example uses the step tool to create the certificates. You can install step [here](https://smallstep.com/docs/getting-started/). Windows binaries available [here](https://github.com/smallstep/cli/releases)* + +Create the root certificate: + +``` +step certificate create cluster.local ca.crt ca.key --profile root-ca --no-password --insecure +``` + +Create the issuer certificate: + +``` +step certificate create cluster.local issuer.crt issuer.key --ca ca.crt --ca-key ca.key --profile intermediate-ca --not-after 8760h --no-password --insecure +``` + +This creates the root and issuer certs and keys. +Place `ca.crt`, `issuer.crt` and `issuer.key` in a desired path (`$HOME/.dapr/certs` in the example below), and launch Sentry: + +``` +./sentry --issuer-credentials $HOME/.dapr/certs --trust-domain cluster.local +```