> For the complete documentation index, see [llms.txt](https://newdocs.keeper.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://newdocs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup/configuration/ssl-tls-and-custom-ca-certificates.md). # 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: {% code overflow="wrap" %} ``` 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)'))) ``` {% endcode %} 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: ```bash 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`. {% hint style="info" %} 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. {% endhint %} #### 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): ```bash 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: ```bash echo $KEEPER_SSL_CERT_FILE # macOS / Linux echo %KEEPER_SSL_CERT_FILE% # Windows CMD ``` Run Commander and log in: ```bash keeper shell login user@company.com ``` 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.
OrderSettingEffect
1VERIFY_SSL=FALSE environment variableDisables SSL verification for settings that honor this variable, including PAM tunnel WebSocket connections
2"certificate_check": false in config.jsonDisables HTTP certificate verification for REST/API calls using that config file
3KEEPER_SSL_CERT_FILE environment variableSets the CA bundle used for HTTP traffic
4DefaultUses the certifi bundled store, or the OS CA bundle when KEEPER_SSL_CERT_FILE=system
#### `KEEPER_SSL_CERT_FILE` values
ValueBehavior
(not set)Use the certifi bundled CA store (default)
Absolute path to a .pem fileUse the specified PEM file. If the file does not exist, Commander prints a warning and falls back to certifi
certifiUse the bundled certifi CA store
systemUse the operating system CA bundle (macOS and Linux). On Windows, falls back to certifi
none or falseDisable 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: ```json { "user": "services@company.com", "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](/en/keeperpam/commander-cli/commander-installation-setup/configuration/configuration.md) 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: ```bash 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`: ```yaml services: commander: container_name: keeper-service image: keeper/commander:latest environment: KSM_CONFIG: COMMANDER_RECORD: 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](/en/keeperpam/commander-cli/service-mode-rest-api/docker-deployment.md) for Service Mode setup. #### AWS Marketplace When deploying Commander Service Mode from the [AWS Marketplace AMI](https://docs.keeper.io/keeperpam/commander-cli/service-mode-rest-api/aws-marketplace.md), 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 . *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://newdocs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup/configuration/ssl-tls-and-custom-ca-certificates.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.