Authentication: Client Certificate Usage

• If you have already securely set up a server certificate, you'll need to use client certificates to connect to a RavenDB server.

• You can read about the logic and rationale behind RavenDB's client certificates in The RavenDB Security Authorization Approach to ensure that you configure them appropriately.

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 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.