Authentication: Client Certificate Usage

In previous sections we described how to obtain a server certificate and how to configure RavenDB to use it. In this section we will cover how to use client certificates to connect to a RavenDB server.

Obtaining Your First Admin Client Certificate

When RavenDB is running 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 an admin client certificate.

Note

This operation is only required when doing a manual secured setup. If you are using the automated Setup Wizard, an admin client certificate will be generated for you as part of the wizard.

Example I - Using the RavenDB CLI

If you have access to the server, the simplest way is to use the RavenDB CLI:

ravendb> generateClientCert <name> <path-to-output-folder> [password]

This will generate a new certificate, with a Cluster Admin Security Clearance.

If you wish to use your own client certificate you can have RavenDB trust it:

ravendb> trustClientCert <name> <path-to-pfx> [password]

The certificate will be registered as a trusted certificate with a Cluster Admin Security Clearance.

Example II - Using Powershell and Wget in Windows

You can use a client to make an HTTP request to the server. At this point you only have a server certificate and you will use it (acting as the client certificate).

Assume we started the server with the following settings.json:

{
    "ServerUrl": "https://rvn-srv-1:8080",
    "Setup.Mode": "None",
    "DataDir": "c:/RavenData",
    "Security.Certificate.Path": "c:/secrets/server.pfx",
    "Security.Certificate.Password": "s3cr7t p@$$w0rd"
}

We can use wget to request a Cluster Admin certificate. This will be the payload of the POST request:

{
    "Name": "cluster.admin.client.certificate",
    "SecurityClearance": "ClusterAdmin",
    "Password": "p@$$w0rd"
}

First, load the server certificate:

$cert = Get-PfxCertificate -FilePath c:/secrets/server.pfx

Then make the request:

wget -UseBasicParsing -Method POST -Certificate $cert -OutFile "cluster.admin.cert.zip" -Body '{"Name": "cluster.admin.client.certificate","SecurityClearance": "ClusterAdmin","Password": "p@$$w0rd"}' -ContentType application/json "https://rvn-srv-1:8080/admin/certificates"

Example III : Using cURL in Linux

At this point you only have a server certificate and you will use it (acting as the client certificate).
First, we will convert the .pfx certificate to .pem:

openssl pkcs12 -in cluster.server.certificate.example.pfx -out server.pem -clcerts

Note

You must provide a password when creating the .pem file, cURL will only accept a password protected certificate.

Then make the request:

curl -X POST -H "Content-Type: application/json" -d '{"Name": "cluster.admin.client.certificate","SecurityClearance": "ClusterAdmin","Password": "p@$$w0rd"}' -o cluster.admin.cert.zip https://rvn-srv-1:8080/admin/certificates --cert /home/secrets/server.pem:pem_password

Using Client Certificates

Once you have the admin client certificate you can access the server/cluster by using the Studio, the Client API or any other client.

Read Here about gaining management access to RavenDB after setup.

It is recommended to generate additional certificates with reduced access rights for applications and users.
Wiring a certificate in the RavenDB Client is described in the setting up authentication and authorization section of the Client API.