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.

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

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.

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.