Authentication

Authenticate Using x.509 Certificates

X.509 certificates are digital certificates that use the X.509 public key infrastructure (PKI) standard to verify the identity of clients and servers. They play a crucial role in establishing a secure connection by providing a way to authenticate identities and establish trust.

Prerequisites

1. EventStoreDB 24.2.0 or later with commercial license.
2. A valid x.509 certificate, which can be created using version 1.3 or higher of our gencert tool.
3. The server must run in secure mode. See Security Options for more information.
4. Enable User Certificates plugin on the server

Generate User Certificates

The following command uses the gencert tool to generate a user certificate for the user admin that will expire in 10 days:

• Linux and macOS
• Windows

./es-gencert-cli create-user -username admin -days 10 -ca-certificate ./es-ca/ca.crt -ca-key ./es-ca/ca.key

.\es-gencert-cli.exe create-user -username admin -days 10 -ca-certificate ./es-ca/ca.crt -ca-key ./es-ca/ca.key

Connect to EventStoreDB using the x.509 certificate

To connect to EventStoreDB using the x.509 certificate, you need to provide the certificate and the private key to the client. If both username/password and certificate authentication data are supplied, the client prioritizes user credentials for authentication. The client will throw an error if the certificate and the key are not both provided.

NOTE

Please note that currently, password-protected private key files are not supported.

The client supports the following parameters:

Parameter	Description
userCertFile	The file containing the X.509 user certificate in PEM format.
userKeyFile	The file containing the user certificate’s matching private key in PEM format.

To authenticate, include these two parameters in your connection string or constructor when initializing the client.

const connectionString = `esdb://admin:changeit@{endpoint}?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}`;
const client = EventStoreDBClient.connectionString(connectionString);

const connectionString = `esdb://admin:changeit@{endpoint}?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}`;
const client = EventStoreDBClient.connectionString(connectionString);

EventStoreDBClientSettings settings = EventStoreDBConnectionString
        .parseOrThrow("esdb://admin:changeit@{endpoint}?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}");
EventStoreDBClient client = EventStoreDBClient.create(settings);

const string userCertFile = "/path/to/user.crt";
const string userKeyFile  = "/path/to/user.key";

var settings = EventStoreClientSettings.Create(
    quot;esdb://localhost:2113/?tls=true&tlsVerifyCert=true&userCertFile={userCertFile}&userKeyFile={userKeyFile}"
);

await using var client = new EventStoreClient(settings);