To enable authentication, either Security.Certificate.Path or 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.
Setting up Client Certificates
When the server is manually set up with a server 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.
Find detailed instructions of the process below.
You can set up various client certificates with different security clearance levels and database permissions.
See Certificate Management for more about permissions.
Standard Manual Setup With Certificate Stored Locally
RavenDB will accept .pfx server certificates that contain the private key, are not expired,
and include a basic (Key Usage) field and an enhanced (Enhanced Key Usage) field.
Permissions granted by this field: Digital Signature, Key Encipherment
Enhanced Key Usage
Permissions granted by this field: Server Authentication, Client Authentication
An Enhanced Key Usage field must include these two OIDs: 220.127.116.11.18.104.22.168.1 - Server Authentication 22.214.171.124.126.96.36.199.2 - Client Authentication
Enhanced Key Usage
Certificates created during setup using Let's Encrypt
are already provided with the above fields and OIDs.
User-created certificates must be provided with these properties for RavenDB to accept and be able to use them.
A settings.json file must reside in each node's Server folder
and define the server and certificate settings. The server will retrieve this file and use its settings on startup.
Read more about RavenDB configuration options here.
When setting up securely, you must also set the ServerUrl configuration option to an HTTPS address.
In manual setup, we recommend configuring a permanent port instead of a random one. In the example below, the port is set to 8080.
For a list of IPs and ports already in use on your machine, run netstat -a in the command line.
Set to "None" if you want a manual setup. If you want to use the Setup Wizard, set to "Initial"
or simply run the run.ps1 file in your server package via PowerShell.
Configure the directory on each machine where the databases will be located.
Path to Certificate
The standard way to enable authentication is to set Security.Certificate.Path in the settings.json file with the path to your .pfx server certificate.
You may also supply a certificate password using Security.Certificate.Password, but this is optional.
With Logic Foreign to RavenDB or External Certificate Storage
The second way to enable authentication is to set Security.Certificate.Load.Exec.
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 the logic that you need.
This 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 -
To use Security.Certificate.Load.Exec with a PowerShell script, the settings.json
must be stored in each node's Server folder and will look something like this:
Make sure that the certificate .path or .load script lead to the correct certificate location. .Path should look something like this: "Security.Certificate.Path": "C:/Windows/MyDomainName/A/Server/ravendb.domain.com.pfx"
See .json example for a .Path situation above.
Right-click and run the run.ps1 (or run.sh in Linux) in the extracted server package. In Windows, it runs in PowerShell as a default.
If you don't yet have a client certificate installed, it will start up and launch a browser window that should give an error message about a missing client certificate.
Setting up the client certificate is the next two steps.
If there is a previously existing client certificate on the machine, the browser will ask which certificate to use.
Until you set up the correct client certificate for this server (in the next two steps), it probably won't work and will give an error message.
This is because your browser will likely save your choice in the cache if you aren't in 'incognito' mode.
It's best to first do the next two steps before selecting a client certificate in your browser.
The PowerShell CLI window will be running the server terminal. The last line should read ravendb>.
In the CLI, run the generateClientCert command to generate a client certificate.
The following is a generic RavenDB CLI command.
ravendb> generateClientCert <your-client-certificate-name> <path-to-output-folder> <number of months> [optional password]
In the following example the certificate will be named RavenDBClient, will be stored at C:\Users\administrator\Documents, will be valid for 60 months, and will have no password.
If a password is required add it to the end of the command.
A few seconds after running this command, a .zip file will download into the output folder that you defined.
Extract the contents of the .zip file generated into the folders where your nodes live.
Install the client certificate into the OS by double-clicking the admin.client.certificate...pfx file and complete the OS Certificate Import Wizard.
To install the client certificate without a password, you can use the default settings by pressing Next all the way through.
In most cases, this is sufficient.
To set a password on the client certificate, do so in the Import Wizard. You'll need to use that password every time you work with the certificate.
Set client certificate password
Quit and restart the server with the run.ps1 script. Select the certificate in the popup and click "OK".
The RavenDB Studio should now open.
In the PowerShell window type quit to close down the server for the next important step of setting it up as an OS service.
To set up as an OS service, run PowerShell as an administrator and navigate to the root Server folder where the settings.json is located.
Copy and paste the following command .\rvn.exe windows-service register --service-name RavenDB.
It will set up the cluster as an OS service, which will launch the server automatically every time the machine starts,
but will fail to start if the Local Service account doesn't have access to all the required resources.
Open the "Services" manager for Windows. Make sure that the "RavenDB" service is there and that the Startup Type is "Automatic".
Now the service should run whenever the machine starts and the Studio should be accessible by the user with the client certificate.
See Certificate Management for an easy way to generate various client certificates with customizable permissions.