LogoLogo
Keeper Connection Manager
Keeper Connection Manager
  • Overview
  • Security Architecture
  • Installation
    • License Key
    • System Requirements
    • Preparing for Installation
    • Auto Docker Install
      • Service Management
      • Upgrading
      • Adding Packages
    • Docker Compose Install
      • keeper/guacamole
      • keeper/guacd
      • Database images
        • keeper/guacamole-db-mysql
        • keeper/guacamole-db-postgres
      • SSL Termination
        • keeper/guacamole-ssl-nginx
        • Using a Custom SSL Cert
      • Upgrading
    • Backup & Recovery
  • Authentication Options
    • SSO Auth (SAML)
      • Microsoft Azure
      • Okta
      • Google Workspace
      • OneLogin
      • Oracle
      • PingIdentity
    • 2FA with TOTP
    • 2FA with Duo
    • SSL/TLS Client Authentication
    • Multiple Hostnames
    • PIV/CAC/Smart cards
    • Account Approve/Deny Workflow
    • OpenID Connect Auth
    • LDAP Auth
      • Using Multiple LDAP Servers
      • Storing connection data within LDAP
      • Using LDAP with a database
  • Connection Protocols
    • RDP
    • SSH
    • VNC
    • Telnet
    • Remote Browser Isolation
    • Kubernetes
    • MySQL
      • Importing and Exporting
      • Keyboard Shortcuts
    • PostgreSQL
      • Importing and Exporting
      • Keyboard Shortcuts
    • Microsoft SQL Server
      • Importing and Exporting
      • Keyboard Shortcuts
    • Connecting to Host Instance
    • Persistent Reverse SSH Tunnel
      • AutoSSH as a Windows Service
      • Linux - AutoSSH
      • Windows - OpenSSH
  • How to Use KCM
    • Login Screen
    • Home Screen
    • Creating Connections
      • Batch Import and API
    • How to Use KCM
    • File Transfer Config
    • Sharing Connections
    • Session Recording and Playback
    • AWS EC2 Discovery
    • Credential Pass-Through
    • Dynamic Connections
    • Custom Branding
      • Add Your Logo
  • Vault Integration
    • Connecting KCM to your Vault
    • Dynamic Tokens
    • Static Tokens
    • Multiple Vaults Integration
    • EC2 Cloud Connector
    • Advanced
    • KeeperPAM
  • Custom Extensions
  • Guest Mode
  • Advanced Configuration
    • guacamole.properties
      • SAML 2.0 Authentication Configuration Properties
      • Duo Two-Factor Authentication Configuration Properties
      • Encrypted JSON Configuration Properties
      • LDAP Configuration Properties
      • MySQL / MariaDB Configuration Properties
      • PostgreSQL Configuration Properties
      • SQL Server Configuration Properties
      • Login Attempts Properties
  • Troubleshooting
  • Importing Connections
  • Exporting Connections
  • High Availability
  • Pre-Release Testing
  • Changelog
  • Licensing and Open Source
  • Scope of Support
  • Security Advisories
  • Accessibility Conformance
Powered by GitBook

Company

  • Keeper Home
  • About Us
  • Careers
  • Security

Support

  • Help Center
  • Contact Sales
  • System Status
  • Terms of Use

Solutions

  • Enterprise Password Management
  • Business Password Management
  • Privileged Access Management
  • Public Sector

Pricing

  • Business and Enterprise
  • Personal and Family
  • Student
  • Military and Medical

© 2025 Keeper Security, Inc.

On this page
  • Supported Types of SSL certificates
  • Let's Encrypt
  • Existing certificate from an arbitrary CA
  • Self-signed Certificates
  • Environment Variables
  • Content Security Policy (CSP)
  • HTTP Strict Transport Security (HSTS)
  • Docker secrets
  • Advanced Configuration

Was this helpful?

Export as PDF
  1. Installation
  2. Docker Compose Install
  3. SSL Termination

keeper/guacamole-ssl-nginx

Docker deployment of NGINX for SSL termination with Keeper Connection Manager

PreviousSSL TerminationNextUsing a Custom SSL Cert

Last updated 1 year ago

Was this helpful?

Image: keeper/guacamole-ssl-nginx

keeper/guacamole-ssl-nginx is a Dockerized deployment of NGINX, built off which is pre-configured to provide SSL termination for Guacamole. It supports:

  • that you have already obtained from a certificate authority.

This image is produced as part of Keeper Connection Manager and made available under the same . It is normally used to provide SSL termination for a container using the .

Supported Types of SSL certificates

The keeper/guacamole-ssl-nginx supports several mechanisms for generating, retrieving, or using existing SSL certificates. The mechanism used depends on which environment variables are specified when the Docker container is created.

In addition to these mechanism-specific environment variables, there is a set of environment variables that must always be specified:

  • - Whether you accept the Keeper Connection Manager EULA (acceptance of the EULA is required to use the image).

  • - The hostname/address of the Guacamole instance.

  • - The public domain name that will be used to access Guacamole.

Let's Encrypt

Let's Encrypt is used by default if no existing certificate is supplied and generation of a self-signed certificate is not requested. The keeper/guacamole-ssl-nginx image will reach out to the Let's Encrypt service using the "certbot" tool to retrieve an SSL certificate.

Only one environment variable specific to Let's Encrypt is strictly required if using Let's Encrypt certificates:

  • LETSENCRYPT_ACCEPT_TOS - Whether you accept the Let's Encrypt Terms of Service (acceptance of Let's Encrypt's Terms of Service is required to use that service).

In addition to accepting their Terms of Service, beware that Let's Encrypt strongly recommends providing an email address so that you can get important alerts regarding your certificate. You should additionally provide an email address unless you have a reason not to do so:

  • LETSENCRYPT_EMAIL - The email address to submit to Let's Encrypt when requesting the certificate.

  • LETSENCRYPT_STAGING - Set to "Y" to use Let's Encrypt's staging environment instead of production.

The retrieved certificate be automatically renewed by the image when necessary. If retrieval fails, the container will stop, details describing the failure will be logged, and the process will be retried the next time the container starts.

The keeper/guacamole-ssl-nginx image leverages Docker volumes to enable Let's Encrypt certificates and state to persist across container recreation.

For example, below will generate a Let's Encrypt certificate in your docker-compose.yml file:

    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
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: "you@company.com"

Existing certificate from an arbitrary CA

If you already have a certificate that you obtained from a certificate authority, you can use that certificate by pointing to the relevant files with the CERTIFICATE_FILE and PRIVATE_KEY_FILE environment variables. The relevant files will need to be exposed to the image using Docker volume mounts.

  • CERTIFICATE_FILE - The full path to the certificate PEM file.

  • PRIVATE_KEY_FILE - The full path to the private key PEM file.

When your certificate comes up for renewal with your CA, you will need to replace the certificate and private key and reload NGINX. Stop and start the Docker Compose after the certificate has been updated.

For Docker Compose configuration, the example below will load a custom certificate from a shared volume that will hold the keys.

    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
            CERTIFICATE_FILE: "/path/in/container/mycert.pem"
            PRIVATE_KEY_FILE: "/path/in/container/mykey.pem"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

Self-signed Certificates

If deploying for testing, the image can automatically generate and maintain its own self-signed certificate:

  • SELF_SIGNED - Set to "Y" to automatically generate a self-signed certificate for testing.

The keeper/guacamole-ssl-nginx image will regenerate the self-signed certificate on startup. As the certificate expires 30 days after generation, the image will also automatically regenerate the certificate every 21 days to ensure it does not expire.

The certificate expiration date and fingerprints will be logged each time the certificate is regenerated, allowing rudimentary server identity verification.

Environment Variables

ACCEPT_EULA

SSL_HOSTNAME

The public-facing hostname of the server hosting Docker. This environment variable is required and should be the full public domain name that will be used to access Guacamole over the internet, already associated with the IP address that reaches the server running Docker and this image.

GUACAMOLE_HOSTNAME

The internal hostname or IP address of the Guacamole server. This environment variable is required, and should be the hostname/address that NGINX will connect to internally when servicing connections.

Note that the Guacamole service whose hostname/address is provided here should be reachable only on the internal network. Only the SSL terminating service (this image) should be public-facing.

GUACAMOLE_PORT

The TCP port number that the Guacamole server is listening on. This environment variable is optional. If omitted, the typical port 8080 will be used by default.

GUACAMOLE_CONTEXT_PATH

The path that Guacamole is being served beneath. This environment variable is optional. By default, this will be blank, representing that Guacamole is being served from the root path. As with the GUACAMOLE_CONTEXT_PATH environment variable of the keeper/guacamole image, this parameter may not contain slashes.

For example, if Guacamole is running internally at http://some-host/guacamole/, you would set GUACAMOLE_CONTEXT_PATH to guacamole.

SELF_SIGNED

If set to "Y", requests that a self-signed certificate be automatically generated for SSL_HOSTNAME rather than using an existing certificate or retrieving a new certificate from Let's Encrypt.

Self-signed certificates are inherently insecure. This option should be used only for testing.

CERTIFICATE_FILE and PRIVATE_KEY_FILE

The paths of the PEM files for the SSL certificate and associated private key, respectively. These paths are relative to the filesystem of the Docker container. Externally-provided SSL certificate PEM files will need to be exposed within the container using Docker volume mounts.

These environment variables are only required if providing your own certificate. They will be ignored if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_ACCEPT_TOS

This environment variable is only required if using Let's Encrypt. It is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_EMAIL

The email address that should be provided to Let's Encrypt when requesting a certificate. This environment variable is optional and is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

While this environment variable is optional, beware that Let's Encrypt strongly recommends providing an email address when obtaining a certificate using their service. From the help content for the certbot tool:

... This is strongly discouraged, because in the event of key loss or account compromise you will irrevocably lose access to your account. You will also be unable to receive notice about impending expiration or revocation of your certificates. Updates to the Subscriber Agreement will still affect you, and will be effective 14 days after posting an update to the web site.

LETSENCRYPT_STAGING

Content Security Policy (CSP)

Content Security Policy (CSP) is a browser feature that allows web applications like KCM to declare to the browser what types of operations should be allowed in the context of that web application. In particular, CSP allows web applications to request that the browser block attempts to load resources or run scripts that the web application considers unsafe or unexpected. This is done by adding a Content-Security-Policy header to HTTP responses.

A default Content-Security-Policy header with known-good default value is set automatically by the keeper/guacamole-ssl-nginx image unless configured otherwise using the CONTENT_SECURITY_POLICY environment variable.

It is not typically necessary set this environment variable except in cases where custom KCM/Guacamole extensions require a more lenient policy.

Be careful if overriding the default policy is necessary. An overly-strict CSP can easily prevent KCM from performing core required tasks, such as decoding graphical data or making requests to its own REST API.

CONTENT_SECURITY_POLICY

Configures the value of the Content-Security-Policy header that will be sent in responses from Nginx.

If set to "Y", a reasonable default Content-Security-Policy value will be set that's known to work with most KCM installations: script-src 'self' 'unsafe-eval'; default-src 'self' data:; style-src 'self' 'unsafe-inline';. This configuration allows loading of assets from the same domain as KCM, along with allowing eval() for translations, and allowing JavaScript to dynamically load CSS.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

HTTP Strict Transport Security (HSTS)

HTTP Strict Transport Security (HSTS) is a browser feature that allows the owners of a domain to advise browsers that connections should only use HTTPS, and that any HTTP connections should be upgraded to HTTPS before being sent.

As HSTS is not always appropriate for all deployments of KCM, particularly if KCM will share a domain with other web applications that do not all support HTTPS, installations of KCM do not enable HSTS by default.

The STRICT_TRANSPORT_SECURITY environment variable must be set to a value to enable HSTS. A recommended default is available for convenience.

STRICT_TRANSPORT_SECURITY

Configures the value of the Strict-Transport-Security header that will be sent in responses from Nginx.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

Docker secrets

Rather than pass data directly in environment variables, a _FILE suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. As Docker secrets store sensitive data within files beneath /run/secrets/ within the container, this can be used to load sensitive data from Docker secrets.

For example, to load the Let's Encrypt account email from Docker secrets:

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
    -d keeper/guacamole-ssl-nginx

Advanced Configuration

The environment variables in this section are only needed in unusual cases, such as when serving KCM from a non-standard port or when older ciphers or versions of SSL must be enabled. Do not set these variables unless you are certain that doing so is necessary.

SSL_CIPHERS

SSL_PROTOCOLS

SSL_EXTERNAL_PORT

Configures value of the X-Forwarded-Port header that will be sent to the KCM web application in requests from Nginx. This header advises the KCM server know that SSL requests are being received at a non-standard port.

If a non-standard port is used for SSL, this port must additionally be mapped to the standard port, e.g. -p 8443:443. Setting this variable has no impact on the ports used by Nginx internally within the image.

If not specified, KCM will expect that inbound requests are coming from the standard HTTPS port (443).

ADDITIONAL_CONFIG

Arbitrary configuration for the server block that points at the KCM web application in the Nginx configuration files generated by this image.

This variable functions as a catch-all for applying Nginx configuration options that do not have corresponding environment variables in the keeper/guacamole-ssl-nginx image.

Any value provided via the ADDITIONAL_CONFIG environment variable will be included in the main server block pointing at the KCM web application. Only configuration options that Nginx will accept within a server block may be included here.

If you are just testing usage of Let's Encrypt, you should use the instead of the production environment:

In addition to the environment variables documented below, all environment variables supported by are accepted, as the official NGINX image forms the basis of this image.

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the . This Docker image may not be used except under the terms of the EULA.

If intending to use Let's Encrypt, the LETSENCRYPT_ACCEPT_TOS environment variable must be set to "Y" to indicate your acceptance of the . Let's Encrypt cannot be used unless you agree to the relevant Terms of Service.

If set to "Y", requests that be used to retrieve an SSL certificate, rather than the production environment. This option should be used if you are just testing the Let's Encrypt functionality.

If set to "Y", a reasonable default Strict-Transport-Security value will be set: 'max-age=31536000; includeSubDomains; preload;' always, as recommended by .

Configures the allowable SSL ciphers for the Nginx instance. For information on the allowable values for this parameter, see . If not otherwise specified, the value will default to "HIGH:!aNULL:!MD5".

Configures the allowable SSL protocols for the Nginx instance. For information on the allowable values for this parameter, see . If not otherwise specified, TLS 1.2 and 1.3 will be enabled.

Let's Encrypt staging/testing environment
the official Docker Nginx image
Keeper Connection Manager EULA
Let's Encrypt Terms of Service
the Let's Encrypt staging environment
https://https.cio.gov/hsts/
the Nginx documentation
the Nginx documentation
Docker's official Nginx image
EULA
keeper/guacamole image
Automatic retrieval of a certificate from Let's Encrypt.
Automatic generation of a self-signed certificate.
Usage of an existing certificate
ACCEPT_EULA
GUACAMOLE_HOSTNAME
SSL_HOSTNAME