SSL/TLS Client Authentication

Requiring SSL/TLS Client Authentication with KCM

Keeper Connection Manager can be configured to require SSL/TLS client authentication.

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

The keeper/guacamole-ssl-nginx image can be configured to require SSL/TLS client authentication by specifying the CLIENT_CERTIFICATE_FILE environment variable. A user will only be able to connect to the KCM instance of NGINX using their browser if their browser has access to a private key that is signed by this certificate.

This variable is similar to the CERTIFICATE_FILE environment variable in that it points to a file within the container, but in this case it controls the certificate used to authenticate the client’s private key.

Example:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CLIENT_CERTIFICATE_FILE: "/path/in/container/ca.crt"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

After updating the configuration, restart the containers.

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

Optional Parameters

Additional environment variables are also available to modify SSL/TLS auth behavior further:

Variable	Description	Default
ADDITIONAL_PROXY_CONFIG	Arbitrary, additional NGINX configuration statements that should be included within the location block that configures NGINX to proxy Guacamole.
SSL_VERIFY_CLIENT	Controls how and whether NGINX requires and verifies the certificate presented by the client (browser), as provided by the NGINX ssl_verify_client directive.	on
SSL_VERIFY_DEPTH	Controls how deep NGINX will follow through the client’s certificate chain when attempting to validate their certificate, as provided by the NGINX ssl_verify_depth directive.	1