Secure EventStoreDB with TLS

Overview

The sample shows how to run the .NET client secured by TLS certificates.

Read more in the docs:

It is essential for production use to configure EventStoreDB security features to prevent unauthorised access to your data. EventStoreDB supports gRPC with TLS and SSL.

Each protocol has its security configuration, but you can only use one set of certificates for TLS and HTTPS.

Certificates

The protocol security configuration depends a lot on the deployment topology and platform. We have created an interactive configuration toolopen in new window, which also has instructions on generating and installing the certificates and configure EventStoreDB nodes to use them.

You need to generate CA (certificate authority)

./es-gencert-cli create-ca -out ./es-ca

And certificate for each node in your cluster.

./es-gencert-cli-cli create-node -ca-certificate ./es-ca/ca.crt -ca-key ./es-ca/ca.key -out ./node -ip-addresses 127.0.0.1,172.20.240.1 -dns-names localhost,eventstoredb

The client application should have public CA certificate installed (Note: private keys should not be shared to clients).

While generating the certificate, you need to remember to pass:

  • IP addresses to -ip-addresses: e.g. 127.0.0.1,172.20.240.1 or
  • DNS names to -dns-names: e.g. localhost,eventstoredb that will match the URLs that you will be accessing EventStoreDB nodes.

The Certificate Generation CLIopen in new window is also available as the Docker image. Check the docker-compose.certs.yml

See instruction how to install certificates below.

You can find helpers scripts that are also installing created CA on local machine:

Description

The sample shows how to connect with the client and append new event. You can run it locally or through docker configuration.

Suggested order of reading:

Running Sample

1. Generate self-signed certificates

Use following command to generate and install certificates:

  • Linux/MacOS
    ./create-certs.sh
    
    1
  • Windows
    .\create-certs.ps1
    
    1

Note: to regenerate certificates you need to remove the ./certs folder.

2. Run samples with Docker

The following command will run both server and client with preconfigured TLS connection setup.

docker-compose -f docker-compose.yml -f docker-compose.app.yml up
1

3. Run samples locally (without Docker)

Assuming the certificates were generated and installed.

3.1 Run EventStoreDB

Use the following command to run EventStoreDB

docker-compose up -d
1

3.2 Run client application

Run the application from your favourite IDE or the console:

dotnet run ./secure-with-tls.csproj
1