Overview

The Keeper Gateway is a service that is installed on any Docker, Linux or Windows machine in order to execute rotation, discovery, connection and tunneling. A single Gateway can be used to communicate with any target infrastructure, both on-prem and cloud. Typically, customers deploy a Keeper Gateway in each environment that is being managed.

Platforms Supported

• Docker

• Windows

• Linux

Platform Specific Capabilities

The Keeper Gateway offers different feature capabilities based on the underlying operating system and hardware. We recommend using Docker on a Linux or Windows host with x86 CPUs for full feature support and ease of management.

Note: EL9 which includes Rocky Linux 9 and RHEL 9 support is coming soon.

System Requirements

System requirements vary based on the number of simultaneous user sessions and the types of connections being established. As the volume of simultaneous connections grows, scaling CPU and memory resources becomes essential. In particular, remote browser isolation (RBI) launches a headless Chromium instance for each session. If you anticipate a high number of RBI sessions, ensure the system is scaled to meet these demands.

For a testing or sandbox a minimum of 2 CPUs with 8GB of memory and 10GB of storage is required. In a production environment, increase to at least 4 CPUs with 16GB of memory. Scale the number of CPUs and memory as the number of simultaneous sessions increases.

Installation Steps

The Keeper Gateway generates encryption keys and a local Secrets Manager configuration that is used to authenticate with the Keeper cloud. The location depends on the context in which the Gateway is being run. It can be installed to the local user or installed as a service.

• Login to the Keeper Web Vault or Desktop App (version 17.1 or newer required)

• Click on Secrets Manager on the left side

• Create a new Secrets Manager Application or select existing application

• Click on the "Gateways" tab and click "Provision Gateway"

• Select Docker, Linux or Windows install method

• Install the Keeper Gateway using the provided method

During the creating of a Keeper Gateway using a one-time token method for Linux and Windows, you have the choice to select "Lock external WAN IP Address of device for initial request". This will additionally IP lock the Gateway in addition to the authentication and encryption built into the service.

Based on your Operating System, refer to the corresponding guide on installing the Keeper Gateway:

• Docker

• Linux

• Windows

Additional Installation Configurations

If you are installing on an EC2 instance in AWS, the Keeper Gateway can be configured to use the instance role for pulling its configuration from AWS Secrets Manager. Detailed instructions on this setup can be found here.

Overview

In order to install and setup a Keeper Gateway device, you need to have a few resources set up:

• Shared Folders to hold the PAM Resources (Machines, Databases, Users, etc)

• Keeper Secrets Manager application

• PAM Configuration

To simplify the process, we have a new Gateway wizard which creates all of the necessary components. Or, you can run each step individually.

Using the Gateway Wizard

The fastest way to create a Gateway and associated resources is using the Gateway Wizard. From the Web Vault or Desktop App, click on Create New > Gateway.

The below link describes how to create a sandbox environment in just a few steps:

• Quick Start: Sandbox

Using Keeper Secrets Manager

To set up a Keeper Gateway manually using the Keeper Secrets Manager application resources, follow these steps.

1

Create a Secrets Manager Application

• In the Keeper Web Vault or Desktop App user interface, create a Shared Folder. This Shared Folder will contain the PAM resource records.

• Navigate to the "Secret Managers" tab on the left and click on "Create Application" to create a KSM application

• In the prompted window:

  • Enter the name of your KSM application

  • Choose the Shared Folder

  • Set the Record Permissions for Application to "Can Edit"

  • Click on "Generate Access Token" and then click on "OK"

  • You can safely ignore the first One-Time Access Token generated for the newly created KSM application. When creating a Keeper Gateway device, a different One-Time Access Token will be created.

2

Generate the Gateway Token

• From the Application screen, open the Gateways tab

• Click on Provision Gateway

• Select a name for the Gateway and the operating system

• Follow the on-screen instructions based on the type of install

Using Commander CLI

You can also create a Gateway and configuration file from the Commander CLI. The below CLI commands will create a Secrets Manager application, shared folders and other resources before creating a Gateway instance.

Create an Application

secrets-manager app create "My Infrastructure"

Create Folders

mkdir -uf "My Infrastructure"
mkdir -sf -a "My Infrastructure/Resources"
mkdir -sf -a "My Infrastructure/Users"

Share the KSM app to the Shared Folders

secrets-manager share add --app "My Infrastructure" --secret <Resources folder UID>
secrets-manager share add --app "My Infrastructure" --secret <Users folder UID>

Create a Gateway

To initialize a Gateway for Linux or Windows native install methods, the one-time token method is used:

pam gateway new -n "My Demo Gateway" -a "My Infrastructure"

To initialize a Gateway using Docker, the base64 configuration is provided as GATEWAY_CONFIG environment variable as described in the Docker Installation instructions.

pam gateway new -n "My Demo Gateway" -a "My Infrastructure" -c b64

Overview

This document contains information on how to install, configure, and update your Keeper Gateway on Docker. The Docker container is built upon the base image of Rocky Linux 8 and it is hosted in DockerHub.

Prerequisites

• A Linux host with a x86 AMD processor

• docker and docker-compose installed (see Docker Install for help)

Note: The syntax is docker-compose for servers, but on a local Docker Desktop it might be docker compose (with no space).

Create a Gateway

A new Gateway deployment can be created by clicking on Create New > Gateway from the Web Vault or Desktop App (version 17.1 or newer required).

You can also create a Gateway and configuration file from the Commander CLI:

pam gateway new -n "<Gateway Name>" -a <Application Name or UID> -c b64

The Application names and UIDs can be found with secrets-manager app list

Installation

services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 2g
        security_opt:
          - seccomp:./docker-seccomp.json
          - apparmor=unconfined
        environment:
          ACCEPT_EULA: Y
          GATEWAY_CONFIG: XXXXXXXXXXXXXXXXX

curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/docker-seccomp.json

docker compose up -d

Logging

When running the latest version of the Keeper Gateway, you'll see the output in the logs like below:

docker compose logs keeper-gateway

On the Vault UI in the Secrets Manager > Applications > Gateways screen, the Gateway will show Online.

Gateway Service Management

Starting the service

docker compose up -d

Stopping the service

docker compose stop

Restarting the service

docker compose restart

Connecting to the Gateway container

docker compose exec keeper-gateway bash

Enable Debugging

If you need to enable verbose debug logs on the Gateway, enable debug logging by adding the below environment section variables to your Docker Compose file:

services:
      keeper-gateway:
        .....
        environment:
          KEEPER_GATEWAY_LOG_LEVEL: "debug" # logs for gateway
          LOG_LEVEL: "debug" # logs for guacd

After debug is enabled, restart the service with docker compose restart

Tailing the logs:

docker compose logs -f keeper-gateway

Updating

Executing the following command will update the Keeper Gateway container to the latest version and restart the service:

docker compose pull
docker compose down
docker compose up -d

Start up automatically

Adding the "restart" parameter in the docker-compose.yml file will assign a restart policy to the environment:

restart: always

Starting Gateway on Reboot

If you would like to force the host operating system to automatically start the Keeper Gateway on a Docker installation, follow these steps (Linux host).

First, create a .service file in /etc/systemd/system/keeper-gateway.service

[Unit]
Description=Keeper Gateway Docker Compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/ec2-user
ExecStart=/usr/local/bin/docker-compose up -d
ExecStop=/usr/local/bin/docker-compose down
User=ec2-user
Group=docker

[Install]
WantedBy=multi-user.target

NOTE:

• Replace /home/ec2-user with the path to your docker-compose.yml

• Replace ec2-user user with your user running Docker

• Replace docker group with your defined group

Then enable the service:

sudo systemctl daemon-reload
sudo systemctl enable keeper-gateway.service
sudo systemctl start keeper-gateway.service

Health Checks

To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the Health Check section for full setup details and examples.

Connecting to the Host Instance

A very useful capability of the Keeper Gateway is being able to open connections and tunnels to the host machine. By adding the extra_hosts section to your docker compose file with a value of host.docker.internal:host-gateway, you can open sessions directly to the host.

Example docker compose with the Gateway container:

services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 2g
        restart: always
        extra_hosts:
          - "host.docker.internal:host-gateway"
        security_opt:
          - seccomp:./docker-seccomp.json
          - apparmor=unconfined
        environment:
          ACCEPT_EULA: Y
          GATEWAY_CONFIG: xxxxxxxx

Enabling this option allows you to establish a Connection to the host. For example, to open an SSH connection:

• Create a PAM User record with the SSH private key

• Create a PAM Machine record with the hostname to host.docker.internal and port 22

• Activate the SSH connection in PAM settings referencing the PAM User

Upgrading the Keeper Gateway service through the host

If you use KeeperPAM to SSH over to the host service, you can upgrade the container by running the container update of the gateway in the background:

docker-compose pull
nohup docker-compose up -d keeper-gateway &

Network Configuration

The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:

The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.

References:

• DockerHub listing: https://hub.docker.com/r/keeper/gateway

• Quick reference for Installing Docker and Docker Compose on Linux

Overview

This document contains information on how to install, configure, and update your Keeper Gateway on Linux.

Prerequisites

• Prior to proceeding with this document, make sure you created a Gateway device.

• For full capabilities, use Rocky Linux 8, RHEL 8 or Alma Linux 8.

• If you cannot use one of these Linux flavors, please install using the Docker method

Installation

Install Command

Executing the following command will install the Keeper Gateway, and run it as a service:

curl -fsSL https://keepersecurity.com/pam/install | \
  sudo bash -s -- --token XXXXXX

• Replace XXXXX with the One-Time Access Token provided from creating the Keeper Gateway

Installation Location

The gateway will be installed in the following location:

/usr/local/bin/keeper-gateway

An alias gateway is also created in the same directory

gateway -> /usr/local/bin/keeper-gateway

Gateway Service Management

For managing the Keeper Gateway as a service, the following are created during the Gateway installation:

• A keeper-gateway folder

• A keeper-gw user

keeper-gateway folder

The keeper-gateway folder contains the gateway configuration file and is created in the following location:

/etc/keeper-gateway

keeper-gw user

During the gateway installation, a new user, keeper-gw, is created and added to the sudoers list in /etc/sudoers.d/.

The keeper-gw user is the owner of the keeper-gateway folder and runs the gateway service. This is required when performing rotations on the gateway service and performing post-execution scripts.

Managing the Gateway Service

The following commands can be executed to start, restart, or stop the Keeper Gateway as a service:

sudo systemctl start keeper-gateway
sudo systemctl restart keeper-gateway
sudo systemctl stop keeper-gateway

Keeper Gateway Configuration File

The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and tenant server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the One-Time Access Token generated when you created the Gateway.

If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:

/etc/keeper-gateway/gateway-config.json

If the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:

<User>/.keeper/gateway-config.json

Keeper Gateway Log files

Logs that contain helpful debugging information are automatically created and stored on the local machine.

If the Gateway is running as a service, the log files are stored in the following location:

/var/log/keeper-gateway/

If the Gateway is not running as a service, the log files are stored in the following location:

<User>/.keeper/logs/

Verbose Logging

To add verbose debug logging, modify this file:

/etc/systemd/system/keeper-gateway.service

and add the -d flag to the "gateway start" command, e.g:

ExecStart=/bin/bash -c "/usr/local/bin/gateway start --service -d --config-file /etc/keeper-gateway/gateway-config.json"

Apply changes to the service:

sudo systemctl daemon-reload
sudo systemctl restart keeper-gateway

Tailing the Logs

sudo journalctl -u keeper-gateway.service -f

Upgrading

Executing the following command will upgrade the Keeper Gateway to the latest version:

curl -fsSL https://keepersecurity.com/pam/install | sudo bash -s --

Auto Update

Configure your Keeper Gateway installation to automatically check for updates, ensuring it stays up-to-date with the latest version.

• Activate the Auto Updater

Uninstalling

Executing the following command will uninstall the Keeper Gateway:

curl -fsSL https://keepersecurity.com/pam/uninstall | sudo bash -s --

Health Checks

To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the Health Check section for full setup details and examples.

Network Configuration

The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:

The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.

Checksum Verification

Keeper Gateway SHA256 hashes for the latest version are published at the below location:

https://keepersecurity.com/pam/latest.txt

Calculating and verifying the checksum:

Linux

sha256sum keeper-gateway_linux_x86_64
cat keeper-gateway_X.X.X_SHA256SUMS | grep keeper-gateway_linux_x86_64

PowerShell

Get-FileHash -Algorithm SHA256 keeper-gateway_windows_x86_64.exe | Format-List
Get-Content keeper-gateway_X.X.X_SHA256SUMS | Select-String keeper-gateway_windows_x86_64.exe

Overview

This document contains information on how to install, configure, and update the Keeper Gateway on Windows.

Prerequisite

Prior to proceeding with this document, make sure you created a Gateway device.

Installation

The latest Keeper Gateway for Windows is downloaded from here:

• Download the Keeper Gateway for Windows

You can run the service under system privilege or use a service account.

New Installs

Upon installation of the service, select "Enter a Keeper One-Time Access Token" and supply the token provided by when you created a Gateway on the Vault. After installation, the service will automatically start up and register with the Keeper cloud.

Upgrading

If you are upgrading an existing Gateway, un-check the "Enter a Keeper One-Time Access Token" so that the existing configuration is maintained.

Installation Location

The default installation location is the following:

C:\ProgramFiles (x86)\Keeper Gateway\<version>

Setup Options

• Install Windows service - Installs the gateway as a Windows service.

  • Use service account - Use the specified service account, otherwise the account installing the gateway will be used.

  • Start Windows service - Start the Keeper Gateway service immediately after installation

  • Enable automatic updates

• Turn on debug logging - Enable verbose logging on the gateway log files. NOT recommended for production environments. Only use this when debugging with Keeper support.

• Remove Keeper Gateway configuration and logs from previous installations

Specifying the Keeper Gateway Service Account

If "Use service account" is specified you will be prompted to enter the valid credentials of the desired service account:

One-Time Access Token

The final step prior to successfully installing the Keeper Gateway as service is to enter the One-Time Access Token provided from the Keeper Vault.

After clicking "Next", click "Install" in the next screen to install the Keeper Gateway.

Gateway Service Management

After installing and running the Keeper Gateway as a service, this service can be accessed and easily managed within the Windows Services Manager as "Keeper Gateway Service".

Configuration File

The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and tenant server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the One-Time Access Token generated when you created the Gateway.

If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:

C:\ProgramData\KeeperGateway\config\gateway-config.json

If the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:

C:\Users\<User>\.keeper\gateway-config.json

Log files

Logs that contain helpful debugging information are automatically created and stored on the local machine.

If the gateway is running as a service, the gateway log files are stored in the following location:

C:\ProgramData\KeeperGateway\logs\

If the gateway is not running as a service, the gateway log files are stored in the following location:

C:\Users\<User>\.keeper\logs\

Verbose Logging

To activate verbose logging:

• Go to Windows Services > Keeper Gateway > Properties

• Stop the service

• Set the "Start parameters" to: --debug or -d

• Start the service by clicking on "Start" Do not click "OK" without first starting the service as it will not persist the Parameter setting

Upgrading

To upgrade, stop the service, install the latest version and then start the service.

• Back up your gateway-config.json configuration file

• Run the latest Keeper Gateway installer

• During installation DO NOT select "Enter a Keeper One-Time Access Token".

Auto Updates

Select "Enable automatic updates" during the installer process to ensure that your Keeper Gateway is automatically updated when there are new versions available.

Health Checks

To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the Health Check section for full setup details and examples.

Silent Install

This section provides instructions for performing a silent installation of the Keeper Gateway on Windows systems. Silent installation allows the setup process to run in the background without displaying any user interface or messages.

To install the Keeper Gateway silently, use the following command in your command prompt or script:

keeper-gateway_windows_x86_64.exe /verysilent /suppressmsgboxes /norestart /token=<TOKEN>

Replace <TOKEN> with the token provided in the Keeper Vault when creating the Keeper Gateway.

Configuration Options

If you have previously installed Keeper Gateway and wish to use the existing configuration, you can bypass the token entry by using:

/existingconfig=1

To generate a log file during the installation process, use the following option and specify the desired log file path:

/log=<Optional log file>

Windows Service Account

If you prefer to run the Keeper Gateway under a specific Windows service account, use the following options to specify the account details:

/mergetasks="service/account" /serviceuser=<ACCOUNT USERNAME> /servicepass=<ACCOUNT PASSWORD>

Replace <ACCOUNT USERNAME> and <ACCOUNT PASSWORD> with the credentials of the service account you intend to use.

Auto Updater

To enable the Auto Updater feature, allowing Keeper Gateway to automatically check for and apply updates, use the following option:

/autoupdate=1

Uninstalling

To uninstall the service:

• Uninstall Keeper Gateway from "Add and remove programs"

• If desired, delete the private configuration .json file

Network Configuration

The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:

The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.

Checksum Verification

Keeper Gateway SHA256 hashes for the latest version are published at the below location:

https://keepersecurity.com/pam/latest.txt

Calculating and verifying the checksum:

Linux

sha256sum keeper-gateway_linux_x86_64
cat keeper-gateway_X.X.X_SHA256SUMS | grep keeper-gateway_linux_x86_64

PowerShell

Get-FileHash -Algorithm SHA256 keeper-gateway_windows_x86_64.exe | Format-List
Get-Content keeper-gateway_X.X.X_SHA256SUMS | Select-String keeper-gateway_windows_x86_64.exe

Overview

Automatic updates of the Keeper Gateway can be enabled on Linux and Windows installations through Keeper's Auto Updater feature. The Auto Updater makes periodic checks to update your Keeper Gateway to the latest version.

We recommend enabling the Auto Updater to ensure you receive the most recent security and functionality enhancements. The Auto Updater verifies all Keeper Gateway downloads by checking the GPG signature of hash value, which are then utilized to checksum each file.

Auto Updater Installation

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Docker

On Docker based installations, the best way to update the container is running the below commands from a cron job or your CI/CD tools.

As an example, create a file called update_gateway.sh that contains:

#!/bin/bash
set -e  # Exit immediately if a command fails

# Navigate to the directory containing your docker-compose.yml file
cd /path/to/your/docker-compose-directory

# Pull the latest image and update the Gateway container
docker compose pull
docker compose up -d keeper-gateway

Make the script executable:

chmod +x update_gateway.sh

Edit the crontab:

crontab -e

Add a line to schedule the script. For example, to run it every day at 3 AM:

0 3 * * * /path/to/update_gateway.sh >> /var/log/update_gateway.log 2>&1

Linux

New Gateway

Execute the following command to download and run the KeeperPAM installer with auto update enabled.

The --autoupdate parameter activates the auto updater in addition to the Keeper Gateway.

curl -fsSL https://keepersecurity.com/pam/install | \
  sudo bash -s -- --autoupdate

Existing Keeper Gateway

Activate the Auto Updater on an existing installation by executing the following Keeper Gateway command:

sudo keeper-gateway autoupdate enable

Verify Installation (Optional)

Verify that the Auto Updater has been installed successfully by executing the following Keeper Gateway command:

sudo keeper-gateway autoupdate status

Windows

New Gateway

• Download and run the latest version of the Gateway installer.

• During installation, check the box "Enable automatic updates".

• This setup option will create a new Task Scheduler task for updating the Gateway.

Existing Gateway

• Open a command prompt as Administrator.

• Install Auto Updater with the following Keeper Gateway command:

keeper-gateway autoupdate enable

Verify Installation (Optional)

• Open a command prompt as Administrator.

• Verify that Auto Updater has been installed successfully by executing the following Keeper Gateway command:

keeper-gateway autoupdate status

Auto Updater Status

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Status on Linux

Check the Auto Updater status by executing the following Keeper Gateway command:

sudo keeper-gateway autoupdate status

Status on Windows

• Open a command prompt as Administrator

• Check the Auto Updater status by executing the following Keeper Gateway command:

keeper-gateway autoupdate status

Auto Updater Configuration

Configuration on Linux

Edit the crontab that runs Auto Updater.

sudo crontab -e

Here is an example of the default crontab entry that checks for updates every hour:

0 * * * * /usr/local/bin/keeper-gateway-update --trust

• The first part 0 * * * * is the crontab expression which will cause execution to occur every hour at 0 minutes.

• The second part is the update command keeper-gateway-update

• The option --trust causes explicit trust of the Keeper Gateway GPG public key for verification of downloaded install files.

Configuration on Windows

Configure the update frequency and other settings with the following steps:

• Run taskschd.msc to open Windows Task Scheduler.

• In the left pane double-click on Task Scheduler Library -> Keeper -> Gateway -> AutoUpdate to show the Auto Updater Task.

• In the upper middle pane double-click on the AutoUpdate Task with the name of the current version and click on the Triggers menu tab.

• Click Edit... to change when the Auto Updater checks for a new update to install. The default is to "Repeat task every 1 hour indefinitely" as shown below.

Auto Updater Removal

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Removal on Linux

Remove Auto Updater by executing the following Keeper Gateway command:

sudo keeper-gateway autoupdate disable

Removal on Windows

Remove Auto Updater with the following steps:

• Open a command prompt as Administrator.

• Remove Auto Updater with the following Keeper Gateway command:

keeper-gateway autoupdate disable

Troubleshooting

Check the status of the Auto Update

keeper-gateway autoupdate status

Logging in the Gateway Auto Updater

To assist with diagnosing issues or monitoring the status of updates, the Gateway Auto Updater generates two types of logs. These logs are subject to rotation policies to avoid overuse of disk space.

Linux

Log Location

All log files for Linux are located in /var/log/keeper-gateway

Log Files

• Update Logs: Any logs generated during an update will be timestamped and stored as update_YYYY-MM-DD_HH-MM-SS.log.

• Last Update Check: The file last-update-check.log contains information regarding the most recent check for updates.

Windows

Log Location

The log files for the Gateway Auto Updater are located in \ProgramData\KeeperGateway\install

Log Files

• Update Logs: Any logs generated during an update will be timestamped and stored as YYYY-MM-DD_HH-MM-SS.log

• Last Update Check: The file last-update-check.log contains information regarding the most recent check for updates.

Overview

Keeper Gateways are essential when configuring PAM features such as rotation and connections on PAM resources. Keeper provides KSM Application Sharing from the vault UI and Keeper Commander CLI.

Why is Gateway Sharing Needed?

Gateways are tied to Keeper Secrets Manager (KSM) applications. Only users who have access to a KSM application can view and select its associated Gateway when configuring PAM Record Types. Without sharing, only the owner of the KSM application can use the Gateway for PAM configuration.

Sharing the KSM application (and thus the Gateway) allows other administrators or team members to independently configure and manage PAM resources. This is critical when multiple users in your organization are responsible for managing privileged access.

Note: Gateways are automatically shared when the associated KSM application is shared.

Sharing KSM applications

When you share the KSM application, you also share access to the associated Gateway.

To share the KSM application:

1. From the vault, open the KSM Application you want to share

2. Edit the Application

3. Navigate to the "Users" tab

4. In the search bar, enter the user’s email address

5. Add the user to the application.

For more information, visit this page.

User Permissions

When sharing a KSM application with other users, the following permissions can be assigned:

Sharing Implications

Shared Folders

Shared folders assigned to a KSM application are accessible by the devices and gateways associated with the application. When sharing a KSM application with another user, if the user does not already have access to the shared folders associated with the application, those folders will be automatically shared with the user.

The level of access the user receives to these shared folders depends on their assigned role in the application:

• If the user is added as a "Member":

  • The user receives the "No User Permissions" shared folder permissions

If the user already had access to any of the shared folders before being added to the KSM application, their existing folder permissions remain unchanged and are not overwritten.

Records

Records can be directly assigned to a KSM application via Keeper Commander secrets-manager app share command.

When sharing a KSM application with another user, if the user does not already have access to the records associated with the application, those records will be automatically shared with the user. The level of access the user receives to these records is "View Only".

Note: Adding individual records to a KSM application requires using Keeper Commander.

Removing a user from the KSM application

Removing a user from the KSM application does not revoke their permissions from the shared folders. Folder access must be manually removed if desired.

Outcomes

Once the gateway is shared through the KSM application, users who now have access can configure PAM resources using that gateway.

Overview

KeeperPAM supports integration with your SIEM provider to provide real-time event logging and monitoring of all privileged access management activity. In the Keeper Admin Console, alerts can also be configured based on any event.

For more information on activating SIEM integration from the Keeper Enterprise guide:

• See Reporting, Alerts & SIEM integration

Features

• Push over 200 different event types to any connected SIEM provider

• Send alerts to email, SMS, Webhook, Slack or Microsoft Teams on any event trigger

• Run custom reports from the Keeper Admin Console or Keeper Commander CLI

KeeperPAM Events

Events related to KeeperPAM include:

• Starting and stopping sessions, tunnels, remote browser isolation

• Gateway lifecycle (online, offline, added/removed)

• Connection lifecycle (creation, editing and deleting PAM resources)

Recommended Alerts

As a KeeperPAM administrator, it is useful to receive alerts related to Gateway actions, such as when a Gateway goes offline (in case of server outage or system restart).

From the Admin Console, go to Reporting & Alerts > Alerts > select Event Types and set the recipient information.

Event alert details will include the name and UID of the affected Keeper gateway.

Email alerts contain event information

Overview

This document describes the health check functionality implemented for the KeeperPAM Gateway. Health checks provide essential monitoring capabilities that solve several common operational challenges. Health checks require the Keeper Gateway 1.5.5 or newer.

Docker Container Lifecycle Management

Problem: When a gateway goes offline or loses connection, Docker containers continue running and report as "healthy" even though the gateway inside is not functioning properly. This creates misleading container status and prevents proper automated recovery.

Solution: With health checks enabled, Docker can properly monitor the gateway's actual operational status and automatically restart or terminate containers when the gateway is unhealthy.

Load Balancer Integration

Problem: Load balancers need to know which gateway instances are actively handling connections to route traffic appropriately.

Solution: Health check endpoints allow load balancers to automatically remove unhealthy instances from rotation and add them back when they recover.

Monitoring and Alerting

Problem: Operations teams need real-time visibility into gateway status across multiple deployments and environments.

Solution: Health checks integrate with monitoring systems (Prometheus, Nagios, Datadog, etc.) to provide automated alerting and dashboards showing gateway health across your infrastructure.

Service Orchestration

Problem: In Kubernetes or other orchestration platforms, services need to know when gateways are ready to accept connections and when they should be restarted.

Solution: Health checks provide the necessary endpoints for readiness probes, liveness probes, and automated restart policies.

Automated Recovery

Problem: Manual intervention is required to detect and restart failed gateway instances.

Solution: Health checks enable automated monitoring scripts and orchestration tools to detect failures and trigger recovery procedures without human intervention.

Quick Start / Common Issues

Step 1: Start the gateway with health check enabled:

gateway start --health-check

Step 2: Only after the gateway is running with health check enabled, you can check its health:

gateway health-check

If you get an error like "Could not connect to health check server", it means you haven't completed Step 1.

If you see "Exception No such command 'keeper-gateway.exe'", you're using the wrong command syntax. Always use gateway as the command name.

Complete Configuration Examples

Here are comprehensive examples showing how to start the gateway and check its health in different configurations:

Output Format Examples

Troubleshooting Commands

Error Messages and Troubleshooting

The CLI health check provides detailed error messages to help diagnose issues:

Authentication Errors (HTTP 401)

CRITICAL: Authentication failed when connecting to https://127.0.0.1:8099/health
ERROR: Invalid or missing authentication token.

Possible fixes:
1. Check if auth token is required:
   curl -k https://127.0.0.1:8099/health
2. Provide the correct auth token:
   gateway health-check --ssl --token YOUR_TOKEN
3. Check gateway startup logs for the configured token

Connection Errors

CRITICAL: Could not connect to health check server at http://127.0.0.1:8099/health
ERROR: Connection failed.

Possible causes:
1. Health check server is not running
2. Wrong host/port combination
3. Network connectivity issues
4. SSL/non-SSL mismatch

Troubleshooting steps:
1. Verify gateway is running with health check enabled:
   gateway start --health-check
2. Check if server is using SSL:
   gateway health-check --ssl
3. Verify host and port:
   Current: 127.0.0.1:8099
4. Test with curl:
   curl http://127.0.0.1:8099/health

SSL Certificate Errors

CRITICAL: SSL error connecting to health check server at https://127.0.0.1:8099/health
ERROR: SSL certificate validation failed.

Possible causes:
- Self-signed certificate (try curl with -k flag)
- Invalid certificate path
- Certificate expired

Implementation

The Gateway health check is implemented using Bottle, a lightweight WSGI micro web-framework for Python. Bottle was chosen for the following advantages:

• Minimal dependency (single file, ~60KB in size)

• Enhanced security over the built-in Python HTTP server

• Proper request routing and handling

• Better error management

• Thread safety

• Production-ready with minimal overhead

CLI Health Check

You can check the gateway's health from the command line:

gateway health-check

This command returns:

• Exit code 0 if the gateway is healthy

• Exit code 1 if the gateway is not running or not healthy

• Text output indicating the status (OK/CRITICAL/WARNING)

For detailed output in a machine-parsable format (one key=value pair per line):

gateway health-check -i

For JSON format output (matching the HTTP endpoint format):

gateway health-check -j

If your health check server is using SSL:

gateway health-check --ssl

If your health check server requires authentication:

gateway health-check --ssl --token your_auth_token

If your health check server is running on a non-default port:

gateway health-check --port 8123

If your health check server is running on a different host:

gateway health-check --host 10.0.0.5

The detailed output includes:

• Gateway version

• Connection status

• WebSocket metrics (when available)

• Process information (in background mode)

This makes it suitable for monitoring scripts and cron jobs.

Note: The CLI health check command requires the HTTP health check server to be running. If the health check server is not running, the command will return an error message suggesting to enable the health check server.

HTTP Health Check

The gateway includes a secure HTTP health check endpoint that can be enabled with environment variables or command line arguments.

Configuration

The health check server can be configured using environment variables or command line arguments:

Environment Variables

Command Line Arguments

When starting the gateway, you can also use these command line arguments:

--health-check               Enable the health check server
--health-check-port INT      Port for the health check server (default: 8099)
--health-check-host STRING   Host address to bind to (default: 127.0.0.1)
--health-check-auth-token    Auth token for the health check server
--health-check-ssl           Enable SSL for the health check server
--health-check-ssl-cert      Path to SSL certificate
--health-check-ssl-key       Path to SSL private key

Command line arguments take precedence over environment variables when both are specified.

Example Commands

Basic health check with default settings:

gateway start --health-check

Custom port and authentication token:

gateway start --health-check --health-check-port 9000 --health-check-auth-token mysecrettoken

Bind to all interfaces (only in secure environments):

gateway start --health-check --health-check-host 0.0.0.0

Enable SSL with certificate and key:

gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pem

Complete example with all options:

gateway start --health-check --health-check-port 8443 --health-check-host 10.0.0.5 --health-check-auth-token mysecrettoken --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pem

Usage

When enabled, the HTTP health check endpoint will be available at:

http://localhost:8099/health

Or with SSL:

https://localhost:8099/health

Response Format

The endpoint returns:

• HTTP 200 if the gateway is healthy

• HTTP 503 if the gateway is not healthy

• JSON response with details:

{
  "status": "healthy",
  "message": "Gateway is running and connected",
  "details": {
    "timestamp": 1742849941,
    "version": 1,
    "connection_status": "connected",
    "websocket": {
      "uptime_seconds": 85,
      "uptime_human": "1m 25s",
      "last_ping_received_seconds_ago": 10,
      "latency_ms": 75,
      "last_ping_sent_timestamp": 1742850455,
      "last_pong_received_timestamp": 1742850455
    }
  }
}

The response includes:

• status: Overall health status ("healthy" or "unhealthy")

• message: Human-readable description of the status

• details: Detailed information about the gateway

  • timestamp: Current server timestamp

  • version: API version

  • connection_status: Current connection status ("connected", "disconnected", etc.)

  • websocket: WebSocket connection metrics

    • uptime_seconds: WebSocket connection uptime in seconds

    • uptime_human: Human-readable uptime (e.g., "1m 25s")

    • last_ping_received_seconds_ago: Seconds since the last ping was received

    • latency_ms: Round-trip latency of the last ping-pong in milliseconds

    • last_ping_sent_timestamp: Unix timestamp when the last ping was sent

    • last_pong_received_timestamp: Unix timestamp when the last pong was received

Example Responses

Healthy Gateway:

{
  "status": "healthy",
  "message": "Gateway is running and connected",
  "details": {
    "timestamp": 1742849941,
    "version": 1,
    "connection_status": "connected",
    "websocket": {
      "uptime_seconds": 85,
      "uptime_human": "1m 25s",
      "last_ping_received_seconds_ago": 10,
      "latency_ms": 75,
      "last_ping_sent_timestamp": 1742850455,
      "last_pong_received_timestamp": 1742850455
    }
  }
}

Unhealthy Gateway:

{
  "status": "unhealthy",
  "message": "Gateway is not properly connected (status: reconnecting)",
  "details": {
    "timestamp": 1742850874,
    "version": 1,
    "connection_status": "reconnecting",
    "websocket": {
      "uptime_seconds": 1018,
      "uptime_human": "16m 58s",
      "last_ping_received_seconds_ago": 324,
      "latency_ms": 77
    }
  }
}

Note that some metrics like latency_ms, last_ping_sent_timestamp, and last_pong_received_timestamp may not always be present in the response. The availability of these metrics depends on the current state of the WebSocket connection and the timing of ping/pong messages.

Status Update Delays

The health check reflects the current state of the WebSocket connection, but there may be a delay in status updates.

Delayed Status Updates

When connectivity is lost, it may take up to 2 minutes for the health check to report an "unhealthy" status, as the gateway attempts to reconnect. Similarly, when connectivity is restored, it may take up to 2 minutes for the health check to reflect a "healthy" status.

This latency is intentional and allows the gateway to attempt reconnection without immediately reporting failures for transient connectivity issues.

Security

The HTTP health check includes the following security features:

1. Authentication: When KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN is set, requests must include the token in the Authorization header:

   Copy

   Authorization: Bearer <token>

2. SSL/TLS: When SSL is enabled, all communication is encrypted. You must provide a valid certificate and private key.

3. Localhost binding: The server binds to localhost only by default, not exposing the endpoint over the network.

4. Security Headers: The health check server adds the following security headers to responses:

   • X-Content-Type-Options: nosniff

   • X-Frame-Options: DENY

   • Content-Security-Policy: default-src 'none'

5. Rate Limiting: Automatic rate limiting is applied to non-localhost connections (60 requests per minute per IP).

6. Information Protection: When the server is bound to a non-localhost address, sensitive information is automatically redacted from the response.

7. Forced SSL: SSL is automatically enforced when binding to non-localhost interfaces.

TLS Compatibility

The health check server is configured to support a wide range of clients by:

• Using secure TLS defaults (TLS 1.2+ minimum) for maximum security

• Supporting modern cipher suites for strong encryption

• Automatically handling protocol negotiation for HTTP and HTTPS

For clients that support modern TLS versions, use standard curl commands:

curl -k -H "Authorization: Bearer your_token" https://localhost:8099/health

Docker-Specific Configuration Requirements

When running Keeper Gateway inside Docker, special configuration is required to expose the health check to the host or external systems:

Binding to 0.0.0.0

• The health check server must bind to 0.0.0.0 to be reachable outside the container.

• 127.0.0.1 restricts access to within the container only.

SSL Enforcement

• When using 0.0.0.0, Keeper Gateway forces SSL to protect health check data.

• You must provide a valid certificate and key or the server will not start.

Authentication Requirement

• If binding to 0.0.0.0, you must also specify an AUTH_TOKEN to secure the endpoint.

Docker Compose Example

services:
  keeper-gateway:
    image: keeper/gateway:latest
    ports:
      - "8099:8099"
    volumes:
      - ./certs:/certs:ro
    environment:
      KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true
      KEEPER_GATEWAY_HEALTH_CHECK_HOST: "0.0.0.0"
      KEEPER_GATEWAY_HEALTH_CHECK_PORT: 8099
      KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true
      KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /certs/healthcheck.crt
      KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY: /certs/healthcheck.key
      KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: mysecrettoken

Generate a Self-Signed Certificate

mkdir -p certs
openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout certs/healthcheck.key \
  -out certs/healthcheck.crt \
  -subj "/CN=localhost"

Test the Endpoint from the Host

curl -k -H "Authorization: Bearer mysecrettoken" https://localhost:8099/health

Example Linux Configuration

# Enable HTTP health check
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8099
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken

# Start the gateway
gateway start

Or using command line arguments:

gateway start --health-check --health-check-port 8099 --health-check-auth-token mysecrettoken

Self-Signed SSL Certificates

For testing or internal use, you can generate self-signed certificates to enable SSL/TLS encryption:

# Generate a private key
openssl genrsa -out healthcheck.key 2048

# Generate a certificate signing request (CSR)
openssl req -new -key healthcheck.key -out healthcheck.csr -subj "/CN=localhost"

# Generate a self-signed certificate (valid for 365 days)
openssl x509 -req -days 365 -in healthcheck.csr -signkey healthcheck.key -out healthcheck.crt

# Set the environment variables
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL=true
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT=/path/to/healthcheck.crt
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY=/path/to/healthcheck.key
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8443  # Typical HTTPS port
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken

# Start the gateway
gateway start

Or using command line arguments:

gateway --health-check --health-check-port 8443 --health-check-ssl --health-check-ssl-cert /path/to/healthcheck.crt --health-check-ssl-key /path/to/healthcheck.key --health-check-auth-token mysecrettoken start

When using self-signed certificates, your HTTP client will need to be configured to trust the certificate or ignore SSL verification (not recommended for production).

Monitoring Integration

This endpoint can be used with monitoring systems like:

• Prometheus with blackbox exporter

• Nagios/Icinga

• Zabbix

• Datadog

• AWS CloudWatch

• Any monitoring system that can perform HTTP checks

Overview

This section will cover additional configurations to modify the Keeper Gateway's default behavior.

Support Configurations

The following are supported configurations for the Keeper Gateway:

• Storing Gateway Configuration in AWS KMS

• Gateway Configuration with Custom Fields

Overview

If the Keeper Gateway is installed on an AWS EC2 Instance, the corresponding Gateway configuration file can be protected and stored in AWS Secrets Manager. This method eliminates the need for storing a configuration file on the instance, and instead stores the configuration file with AWS KMS protection.

AWS Key Management Service (KMS) Key

AWS KMS is a fully managed service that makes it easy for you to create and control the cryptographic keys used to encrypt and decrypt your data. The service is integrated with other AWS services, making it easier to encrypt data and manage keys. You will need a AWS KMS key as part of this process, and it is recommended that you follow the principle of least privilege when assigning permissions to this key.

Prerequisites

In order to use AWS KMS to protect the Gateway configuration secrets, you need to install the Keeper Gateway on an EC2 instance which assumes an IAM Role. This works on either Docker or Linux install methods.

• Docker Installation

• Linux Installation

Generate a Configuration

From the Keeper Vault, go to Secrets Manager > Applications and select the application configured with your Gateway. Then select the Gateways tab and select "Provision Gateway".

Select the Gateway initialization method of "Configuration" and click Next.

Alternatively, you can generate a One-Time Access Token and then use the Keeper Gateway's "gateway ott-init" command:

gateway ott-init [ONE-TIME-TOKEN]

In either case, you'll be provided with a base64 encoded configuration. Save this for the next step.

Create Secret in AWS Secrets Manager

From the AWS Console, go to the Secrets Manager and create a new secret.

• Select "Other type of secret"

• Select Plaintext and paste the entire base64 value there.

• Click Next.

Enter a Secret Name and a description then click Next, Next and Store.

Assign Policy to Instance Role

The EC2 instance role needs to be assigned a policy which provides read access to the specific AWS Secrets Manager key. As an example:

{
    "Sid": "SecretsManagerPermissions",
    "Effect": "Allow",
    "Action": [
        "secretsmanager:GetSecretValue"
     ],
     "Resource": "arn:aws:secretsmanager:us-west-1:XXX:secret:XXX"
}

Confirming Access

From the EC2 instance, the below command will confirm the policy has been applied:

aws secretsmanager get-secret-value --secret-id YourSecretName --query SecretString --output text

Configuration of the Keeper Gateway

Docker Install Method

For Docker installations, remove the GATEWAY_CONFIG entry and add AWS_KMS_SECRET_NAME with the value containing the name of the secret from the AWS secrets manager.

services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 2g
        security_opt:
          - "seccomp:docker-seccomp.json"
        environment:
          ACCEPT_EULA: Y
          AWS_KMS_SECRET_NAME: "YourSecretName"

Then update the service with the new environment:

docker compose pull
docker compose down
docker compose up -d

Linux Install Method

Open the Keeper Gateway service unit file:

/etc/systemd/system/keeper-gateway.service

Modify the "ExecStart" line as seen below, replacing YourSecretName with your assigned name.

ExecStart=/bin/bash -c "/usr/local/bin/gateway start --service --aws-kms-secret-name="YourSecretName" --log-to-stdout"

Apply changes to the service:

sudo systemctl daemon-reload
sudo systemctl restart keeper-gateway

If there are any errors starting up, they can be seen through this command:

systemctl status keeper-gateway.service

Advanced Gateway Configuration with Custom Fields

When setting up Rotation in your Keeper Vault, you store the credentials of your assets involved in rotation on their corresponding PAM Record Types. On these record types, you are able to create custom fields.

The additional gateway configurations will be defined with these custom fields on the PAM Record Types. The Keeper Gateway will then adjust its behavior based on the defined configurations.

The following tables lists all the possible configurations with custom fields:

Note:

• The custom fields values are not case-sensitive.