SSL/TLS and Custom CA Certificates

Keeper Commander communicates with Keeper cloud APIs over HTTPS. By default, Commander verifies server certificates using a trusted CA bundle (the bundled certifi store, or the operating system CA store when configured).

If your network performs TLS inspection (SSL interception) with a corporate root CA, Commander may fail with certificate verification errors unless it is configured to trust that CA.

This page describes how to configure SSL/TLS certificate verification for the Commander CLI and Service Mode deployments.

---

When to Use a Custom CA Bundle

Configure a custom CA bundle when Commander reports errors such as:

requests.exceptions.SSLError: HTTPSConnectionPool(host='keepersecurity.com', port=443): Max retries exceeded with url: /api/rest/authentication/get_device_token (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)')))

or:

certificate verify failed: self-signed certificate in certificate chain

Common scenarios:

Scenario	Recommended approach
Corporate TLS inspection (Zscaler, Palo Alto, etc.)	Allowlist Keeper endpoints from inspection, or provide a CA bundle that includes your corporate root CA
Missing or outdated OS CA store	Set KEEPER_SSL_CERT_FILE=system or install OS CA packages
Commander install without system certificates	Set KEEPER_SSL_CERT_FILE to a PEM file path or certifi
Local development with a debugging proxy	Use a PEM file that includes the proxy CA, or none for testing only

If your security policy allows it, work with your IT team to add Keeper endpoints to the TLS inspection allowlist (keepersecurity.com, keepersecurity.eu, keepersecurity.com.au, keepersecurity.ca, keepersecurity.jp, or govcloud.keepersecurity.us as applicable). Allowlisting outbound HTTPS to these hosts may remove the need for a custom CA bundle.

---

Quick Start

Step 1: Obtain the corporate root CA

Request the root CA certificate used for TLS inspection from your IT or security team. It is typically provided as a .pem or .crt file.

Step 2: Create a CA bundle

Create a single PEM file that contains the public root CAs and your corporate root CA, concatenated together.

macOS / Linux example:

cat "$(python3 -m certifi)" /path/to/corporate-root-ca.pem > /etc/ssl/certs/keeper-cacert.pem

On Windows, concatenate the certifi bundle and your corporate CA into one .pem file. Save it to a stable location such as C:\ProgramData\Keeper\keeper-cacert.pem.

Do not edit the bundled cacert.pem inside the Commander install directory. It is overwritten on upgrade. Use KEEPER_SSL_CERT_FILE to reference your own bundle.

Step 3: Set the environment variable

Windows (persistent):

setx KEEPER_SSL_CERT_FILE "C:\ProgramData\Keeper\keeper-cacert.pem"

Open a new Command Prompt or PowerShell window after running setx.

macOS / Linux (add to ~/.zshrc, ~/.bashrc, or your service unit file):

export KEEPER_SSL_CERT_FILE="/etc/ssl/certs/keeper-cacert.pem"

Step 4: Verify the configuration

Open a new terminal and confirm the variable is set:

echo $KEEPER_SSL_CERT_FILE        # macOS / Linux
echo %KEEPER_SSL_CERT_FILE%       # Windows CMD

Run Commander and log in:

keeper shell
login [e-mail]

Login should complete without CERTIFICATE_VERIFY_FAILED errors. To enable detailed logging, use keeper shell --debug.

---

Configuration Reference

Resolution order

Commander resolves SSL verification settings in the following order. The first matching rule applies.

Order	Setting	Effect
1	VERIFY_SSL=FALSE environment variable	Disables SSL verification for settings that honor this variable, including PAM tunnel WebSocket connections
2	"certificate_check": false in config.json	Disables HTTP certificate verification for REST/API calls using that config file
3	KEEPER_SSL_CERT_FILE environment variable	Sets the CA bundle used for HTTP traffic
4	Default	Uses the certifi bundled store, or the OS CA bundle when KEEPER_SSL_CERT_FILE=system

KEEPER_SSL_CERT_FILE values

Value	Behavior
(not set)	Use the certifi bundled CA store (default)
Absolute path to a .pem file	Use the specified PEM file. If the file does not exist, Commander prints a warning and falls back to certifi
certifi	Use the bundled certifi CA store
system	Use the operating system CA bundle (macOS and Linux). On Windows, falls back to certifi
none or false	Disable HTTP certificate verification. Not recommended for production environments

KEEPER_SSL_CERT_FILE is read once per process. Restart Commander after changing this variable.

config.json option

When using a configuration file (--config or --config-file), the certificate_check property controls HTTP SSL verification:

{
    "user": "[e-mail]",
    "server": "keepersecurity.com",
    "certificate_check": true
}

Value	Effect
true	HTTP SSL verification is enabled (default). Commander uses KEEPER_SSL_CERT_FILE or the default CA store
false	HTTP SSL verification is disabled for that configuration file

See Configuration File for additional configuration options.

VERIFY_SSL environment variable

VERIFY_SSL=FALSE is a legacy setting retained for compatibility. It disables SSL verification for components that check this variable, including PAM tunnel WebSocket connections.

For HTTP traffic, use KEEPER_SSL_CERT_FILE with a proper CA bundle instead of disabling verification.

---

Traffic Covered by These Settings

HTTP/HTTPS traffic

The following Commander operations use KEEPER_SSL_CERT_FILE, certificate_check, and the resolution order described above:

• Login and authentication
• Vault sync and REST API calls
• Record attachments
• Enterprise and compliance reports
• KeeperPAM cloud API operations (Discovery, GraphSync, rotation, PAM SaaS plugin downloads, router HTTP calls)
• Third-party imports that use Commander HTTP (for example, LastPass import)
• Service Mode REST API outbound calls to Keeper cloud APIs

PAM tunnel WebSocket connections

PAM tunnel WebSocket connections (SSH/RDP tunnel signaling) use the VERIFY_SSL environment variable. They do not use KEEPER_SSL_CERT_FILE.

Symptom	Likely cause
Login and vault sync succeed; pam tunnel fails with SSL errors	Configure VERIFY_SSL for WebSocket traffic, or consult with your IT team regarding tunnel endpoint access
Login fails with certificate errors	Configure KEEPER_SSL_CERT_FILE for HTTP traffic

HTTP steps during tunnel setup (for example, bind URL requests) use HTTP SSL settings and honor KEEPER_SSL_CERT_FILE.

---

HTTP Proxy and TLS Inspection

HTTP proxy configuration and TLS inspection are separate settings.

Concern	Configuration
HTTP proxy routing	proxy command, "proxy" in config.json, or --proxy flag
TLS inspection trust	KEEPER_SSL_CERT_FILE

Restricted networks may require both settings. See Logging in with a Proxy.

---

Platform Notes

Windows

• Use setx for persistent environment variables. Scheduled tasks and Windows services do not inherit variables set in an interactive shell.
• For Windows Task Scheduler, set KEEPER_SSL_CERT_FILE in the task environment or as a system environment variable.
• Store the PEM file in a location readable by the account that runs Commander.

macOS

• When using KEEPER_SSL_CERT_FILE=system, Commander checks common Homebrew and system CA paths.
• Open a new terminal after updating your shell profile.

Linux

• Install the ca-certificates package when using KEEPER_SSL_CERT_FILE=system.
• Common system bundle paths include /etc/ssl/certs/ca-certificates.crt and /etc/pki/tls/certs/ca-bundle.crt.

---

Batch and Scheduled Execution

When running Commander in batch mode or from a scheduled task, set KEEPER_SSL_CERT_FILE in the environment before launching Commander. Scheduled tasks and Windows services do not inherit variables from an interactive shell session.

Example:

keeper --config=my_config.json --batch-mode commands.cmd

Ensure KEEPER_SSL_CERT_FILE is set in the same environment that runs this command. See Automating with Windows Task for task scheduler setup.

---

Service Mode

Commander Service Mode runs the Commander REST API as a service. Outbound calls to Keeper cloud APIs use the same HTTP SSL settings as the CLI, including KEEPER_SSL_CERT_FILE.

If the host or VPC egress passes through TLS inspection, configure the CA bundle in the Service Mode runtime environment before the container or instance starts.

Docker

Mount your CA bundle into the container and set KEEPER_SSL_CERT_FILE in the environment section of docker-compose.yml:

services:
  commander:
    container_name: keeper-service
    image: keeper/commander:latest
    environment:
      KSM_CONFIG: <base64-encoded-ksm-config>
      COMMANDER_RECORD: <config-record-uid>
      KEEPER_SSL_CERT_FILE: /certs/keeper-cacert.pem
    volumes:
      - /host/path/keeper-cacert.pem:/certs/keeper-cacert.pem:ro
    ports:
      - "8900:8900"
    command: service-create -p 8900 -c 'tree,ls' -f json -q y -ur $COMMANDER_RECORD \
      --ksm-config $KSM_CONFIG --record $COMMANDER_RECORD
    restart: unless-stopped

Replace /host/path/keeper-cacert.pem with the path to your CA bundle on the Docker host.

If you use service-docker-setup to generate docker-compose.yml, add the KEEPER_SSL_CERT_FILE entry and volume mount to the generated file before running docker compose up.

See Docker Deployment for Service Mode setup.

AWS Marketplace

When deploying Commander Service Mode from the AWS Marketplace AMI, set KEEPER_SSL_CERT_FILE in the environment for the account or service that runs Commander on the instance. Copy the CA bundle PEM file to the instance (for example, under /etc/ssl/certs/) and point the variable at that path.

If outbound traffic from the instance passes through TLS inspection, the variable must be set in the same environment as the running Commander service, not only in an interactive SSH session.

Restart the Commander service after changing KEEPER_SSL_CERT_FILE.

---

Related Topics

The following settings address different SSL/TLS concerns and are not interchangeable with KEEPER_SSL_CERT_FILE:

Topic	Documentation
HTTP proxy for Commander	Logging in with a Proxy
RDP target certificate validation	PAM tunnel record settings (ignore server certificate)
Keeper Gateway outbound proxy	Gateway Proxy Configuration
Keeper Connection Manager server certificate	Keeper Connection Manager documentation

---

Troubleshooting

Problem	Action
CERTIFICATE_VERIFY_FAILED after setting the environment variable	Open a new terminal. Confirm the variable is set. Verify the PEM file includes both public roots and the corporate root CA
Warning that the PEM path does not exist	Use an absolute path and verify file permissions
Login works; PAM Discovery fails with SSL errors	Review PAM tunnel WebSocket connections
Scheduled task fails; interactive shell works	Set KEEPER_SSL_CERT_FILE in the task or system environment
Service Mode health check passes; Keeper API calls fail	Set KEEPER_SSL_CERT_FILE in the container or instance environment, not only in an SSH session

For additional assistance, see Troubleshooting or contact [e-mail].

---