Skip to main content

Client certificate usage

Obtaining your first admin client certificate​

When a RavenDB server runs with a server certificate for the first time, no client certificates are registered on the server yet.
The first thing an administrator does is generate or register an admin client certificate.

An admin client certificate is a client certificate that carries Cluster Admin security clearance.
It is separate from the server certificate (which may be a Let's Encrypt certificate); it is the certificate that administrators and applications present to authenticate to the server.

This step is only required for a manual secure setup.
If you use the automated Setup Wizard, an admin client certificate is generated for you as part of the wizard.

Using the RavenDB CLI​

If you have access to the server, the simplest way to generate a client certificate is to use the RavenDB CLI:

ravendb> generateClientCert <name> <path-to-output-folder> <number of months until expiration> [password]

This generates a new certificate with a Cluster Admin security clearance.

To have RavenDB trust a client certificate that you already own, run:

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

The certificate is registered as a trusted certificate with a Cluster Admin security clearance.

Using PowerShell and wget on Windows​

You can use a client to make an HTTP request to the server.
You have not generated a client certificate yet, so this first request is authenticated with the server certificate itself.
RavenDB trusts its own server certificate as a client certificate with Cluster Admin clearance, which authorizes it to create your first client certificate.

Assume the server was started 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"
}

Use wget to request a Cluster Admin certificate.
This is 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"

Using cURL on Linux​

You have not generated a client certificate yet, so this first request is authenticated with the server certificate itself.
RavenDB trusts its own server certificate as a client certificate with Cluster Admin clearance, which authorizes it to create your first client certificate.
First, convert the .pfx certificate to .pem:

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

You must provide a password when creating the .pem file.
cURL only accepts 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 or cluster using 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.

In this article