Client Certificate Configuration

Optional NGINX Client Certificate configuration for advanced protection

Client Certificate Overview

To implement device-based access security with Keeper Connection Manager, this can be accomplished using NGINX client certificates. A client certificate is installed into the web browser of your user's approved devices, and the server will only accept communication from a device with the client certificate installed.

The steps to activate this advanced level of protection is described in the steps below.

(1) Create a Certificate Authority (CA) Key

Generate a CA Key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

openssl genrsa -des3 -out ca.key 4096

(2) Create a CA Certificate

A certificate is created with the CA Key. When answering the questions, you can leave the Common Name and Email empty. Save the information that you entered for Country, State, Locality, and Organization, because you may need these later when renewing the certificate.

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

Side Note: to analyze the certificate parameters, you can run the below command.

openssl x509 -in ca.crt -noout -text

(3) Create a Client Key

For the end-user devices, a client key must be generated. You can decide if you would like to generate one key for all devices, or each user can generate their own key and request a certificate. The process is up to you. Generate a client key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

openssl genrsa -des3 -out client.key 4096

(4) Create a CSR

For each Client Key, generate a CSR to create a signed certificate.

openssl req -new -key client.key -out client.csr

(5) Sign the CSR with the CA Key

openssl x509 -req -days 365 -in client.csr \
 -CA ca.crt -CAkey ca.key \
 -set_serial 01 -out client.crt

You'll need to enter the CA passphrase from Step 1 to sign the request.

At this point, you now have a signed Client Certificate (client.crt).

(6) Convert the Client Certificate to PKCS#12

To import the certificate into a web browser, a pfx file in PKCS#12 is typically required. Generate the client.pfx file using the command below. A passphrase will be required. This passphrase will be provided to each of the users who need to install the certificate, so it should be used specifically for this purpose.

openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.pfx

(7) Add to NGINX Config

Add the below line to your Keeper Connection Manager NGINX configuration file to block access without a certificate. Make sure to upload the CA certificate to the folder path designated.

ssl_client_certificate /etc/nginx/client_certs/ca.crt;
ssl_verify_client optional;

In the Location block, add this section to send the user a 403 error if the client cert is not installed:

        if ($ssl_client_verify != SUCCESS) {
                return 403;
        }

Make sure that the ca.crt file is located in a folder that NGINX can access.

After updating the configuration, restart NGINX.

sudo systemctl restart nginx

(8) Test the configuration

Before installing the client certificate on the user's machine, load up the Keeper Connection Manager login screen to ensure that a 403 error is sent:

403 Error without Client Certificate

(9) Install the Client Certificate

For each end-user client device that will need access to Keeper Connection Manager, you will need to install the client certificate into the user's browser or machine. The installation of client certificates varies by platform.

On Windows

Double-click or right-click the client certificate (client.pfx) from Step 6 and enter the client certificate passphrase.

Install Windows Client Certificate

Restart the browser.

The next time Keeper Connection Manager is loaded, you can approve the certificate.

Select Client Certificate

On Mac OS - Chrome

Import the client.pfx file by double-clicking or loading into the Keychain login Certificates section. In the "Trust" section of the certificate, mark as Always Trust.

Import Certificate

Mark as Trusted

Restart the browser and load the Keeper Connection Manager login screen to select the certificate.

Select Client Certificate

On Mac OS - Firefox

Open Firefox > Preferences > search for Certificates and select Your Certificates tab. Click "Import" and select the client.pfx certificate file. Complete the import.

Import Certificate on Firefox

After successful import, the Keeper Connection Manager login screen will load.

Troubleshooting

After setting up the client certificate configuration, the following errors are common.

If NGINX fails to start, journalctl -xe might show something like "Permission denied:fopen('/path/to/ca.crt','r'). This might occur if the folder permissions and file permissions are not set properly.

If the folder and file permissions are set properly and you're still receiving this error, the restorecon command will repair the SELinux security context for the file:

restorecon ca.crt