Authentication: Manual Certificate Configuration
This section explains how to set up authentication manually. Please also take a look at the automated
Setup Wizard which lets you set up authentication in a much easier and faster way.
In RavenDB, configuration values can be set using environment variables, command line arguments or using the settings.json
file. For more details, please read the Configuration Section.
To enable authentication, either
Security.Certificate.Load.Exec must be set in settings.json.
Please note that
Security.Certificate.Load.Exec has replaced the old
Security.Certificate.Exec as of 4.2 - see FAQ.
RavenDB will accept
.pfx server certificates which contain the private key, are not expired and have the following fields:
- KeyUsage: DigitalSignature, KeyEncipherment
- ExtendedKeyUsage: Client Authentication, Server Authentication
The first way to enable authentication is to set
Security.Certificate.Path with the path to your
.pfx server certificate. You may supply the certificate password using
When providing a certificate for authentication, you must also set the
ServerUrl configuration option to an HTTPS address.
For example, this is a typical settings.json:
"Password": "s3cr7t p@$$w0rd"
The second way to enable authentication is to set
This option is useful when you want to protect your certificate (private key) with other solutions such as "Azure Key Vault", "HashiCorp Vault" or even Hardware-Based Protection. RavenDB will invoke a process you specify, so you can write your own scripts / mini programs and apply whatever logic you need. It creates a clean separation between RavenDB and the secret store in use.
RavenDB expects to get the raw binary representation (byte array) of the .pfx certificate through the standard output.
Let's look at an example - a simple powershell script called
$thumbprint = $args
$cert = gci "cert:\CurrentUser\my\$thumbprint"
$exportedCertBinary = $cert.Export("Pfx")
$stdout = [System.Console]::OpenStandardOutput()
$stdout.Write($exportedCertBinary, 0, $exportedCertBinary.Length)
And settings.json will look something like this:
"Security.Certificate.Load.Exec.Arguments": "C:\\secrets\\give_me_cert.ps1 90F4BC16CA5E5CB535A6CD8DD78CBD3E88FC6FEA"
In all secure configurations, the
ServerUrl must contain the same domain name that is used in the certificate (under the CN or ASN properties).
When the server is running with a certificate for the first time, there are no client certificates registered in the server yet. The first action an administrator will do is to generate/register a new client certificate.
You can do this by using the RavenDB CLI (generateClientCert) or by using a client, see the Client Certificate Usage section for a detailed example.