SSH Connections
Keeper Connections - SSH Protocol
Overview
KeeperPAM provides zero-trust privileged session management for target infrastructure over the SSH protocol. This guide explains how to configure SSH connections with PAM Machine records within the Keeper Vault. Secure SSH sessions are initiated from the Vault, proxied through the Keeper Gateway, and established directly with target systems. Keeper supports multiple SSH authentication methods, including password, SSH key, SSH key with passphrase and SSH certificate-based authentication.
Prerequisites
Prior to following this guide, familiarize yourself with the prerequisites on the Connection's Getting Started page.
The following PAM records are needed in order to successfully setup this protocol:
The PAM Configuration contains information of your target infrastructure.
PAM Machine Record
The PAM Machine record stores the endpoint details needed to establish an SSH connection.
PAM User Record
The PAM User record stores the credentials used to connect to the endpoint or generate ephemeral credentials.
This guide will use a Linux server to represent a PAM Machine record.
PAM Settings - Configuring SSH Protocol
Accessing Connection Settings
After creating a PAM Record Type (PAM Machine, PAM Database, or PAM Directory) with your target endpoint, navigate to the Connection Section on the PAM Settings screen by:
Editing the PAM Record
Clicking on "Set Up" in the PAM Settings section
Navigate to the "Connection" section in the prompted window
Configuring Connection Settings
Prior to configuring the SSH protocol settings on the PAM Settings screen, the following fields are all required and need to be configured:
PAM Configuration
This is the PAM Configuration that contains the details of your target infrastructure and provides access to the target configured on the PAM Record.
Administrative Credential Record
This is the linked PAM User that will be used to authenticate to the target and perform administrative operations such as rotation or account creation
The following table lists all the configurable connection settings for the SSH protocol on the PAM Settings:
Connection Parameters
Protocol
Required
The protocol to be configured on the record. The protocol settings will be populated based on the selected protocol. In this guide, the SSH protocol should be selected
Enable Connection
Required
To enable connection for this record, this toggle needs to be enabled
Graphical Session Recording
When enabled, graphical session recordings will be enabled for this record
Text Session Recording (Typescript)
When enabled, text session recordings (typescript) will be enabled for this record
Key Events
When enabled, the individual keystroke data will be included in the session playback. Note: This will include any secrets potentially typed by the user.
Connection Port
The port used to establish the selected protocol connection. By Default, this will be the port value defined on the PAM Machine record. The port specified here will override the default port. For SSH, the default port is 22
Launch Credentials
When configured, these credentials will be used to authenticate the connection. More details here
Allow users to select credentials from their vault
When enabled, allow users to use their own personal/private credentials to authenticate the connection. More details here
Rotate launch credentials upon session termination
When enabled, the configured launch credentials will be automatically rotated when the session is closed
Public Host Key (Base64)
The known hosts entry for the SSH server, in the same format as would be specified within an OpenSSH known_hosts file. If not provided, no verification of host identity will be performed.
Color Scheme
The color scheme to use for the terminal emulator used by SSH connections. Each color scheme dictates the default foreground and background color for the terminal. Programs which specify colors when printing text will override these defaults. Legal values are:
"black on white" - Black text over a white background
"gray on black" - Gray text over a black background (the default)
"green on black" - Green text over a black background
"white on black" - White text over a black background
"Custom" - custom color scheme
Default value is "white-black"
Font Size
Font size displayed for the terminal session
Font Name
The name of the font to use. If not specified, the default of "monospace" will be used instead. This must be the name of a font installed on the server running guacd, and should be a monospaced font. If a non-monospaced font is used, individual glyphs may render incorrectly.
Maximum scrollback size
The maximum number of rows to allow within the terminal scrollback buffer. By default, the scrollback buffer will be limited to a maximum of 1000 rows.
SFTP
If enabled, the user can drag and drop files into the terminal session to transfer one or more files.
File Browser Root Directory
If SFTP is enabled, file transfers will be saved to the specified folder path.
Can copy to clipboard
If enabled, text copied within the connected protocol session will be accessible by the user.
Can paste from clipboard
If enabled, user can paste text from clipboard within the connected protocol session.
Read-only
Whether this connection should be read-only. If set to "true", no input will be accepted on the connection at all. Users will be able to see the terminal (or the application running within the terminal) but will be unable to interact.
Session / Environment Parameters
By default, SSH sessions will start an interactive shell. The shell which will be used is determined by the SSH server, normally by reading the user's default shell previously set with chsh or within /etc/passwd. If you wish to override this and instead run a specific command, you can do so by specifying that command in the configuration of the SSH connection.
Execute command
The command to execute over the SSH session, if any. If not specified, the SSH session will use the user's default shell.
Language/Locale ($LANG)
The specific locale to request for the SSH session. This may be any value accepted by the LANG environment variable of the SSH server. If not specified, the SSH server's default locale will be used.
As this parameter is sent to the SSH server using the LANG environment variable, the parameter will only have an effect if the SSH server allows the LANG environment variable to be set by SSH clients.
Time zone ($TZ)
The time zone to request for the SSH session. This may be any value accepted by the TZ environment variable of the SSH server, typically the standard names defined by the IANA time zone database. If not specified, the SSH server's default time zone will be used.
As this parameter is sent to the SSH server using the TZ environment variable, the parameter will only have an effect if the SSH server allows the TZ environment variable to be set by SSH clients.
Server keepalive interval
The interval in seconds between which keepalive packets should be sent to the SSH server, where "0" indicates that no keepalive packets should be sent at all (the default behavior). The minimum legal value is "2".
Terminal Behavior Parameters
In most cases, the default behavior of the Keeper Connection Manager terminal emulator works without modification. However, when connecting to certain systems (particularly operating systems other than Linux), the terminal behavior may need to be tweaked to allow it to operate properly. Keeper's SSH support provides parameters for controlling the control code sent for backspace, as well as the terminal type claimed via the TERM environment variable.
Backspace key sends
The integer value of the terminal control code that should be sent when backspace is pressed. Under most circumstances this should not need to be adjusted; however, if, when pressing the backspace key, you see control characters (often either ^? or ^H) instead of seeing the text erased, you may need to adjust this parameter. By default, the control code 127 (Delete) is sent.
Terminal type
The terminal type string that should be passed to the SSH server. This value will typically be exposed within the SSH session as the TERM environment variable and will affect the control characters sent by applications. By default, the terminal type string "linux" is used.
Connection Authentication Methods
SSH Connections can be authenticated using one of the following methods:
Launch Credential The session to the target is authenticated using the "Launch Credentials" configured directly on the PAM Machine, PAM Database, or PAM Directory record types. The user does not need access to the credentials in order to launch the connection.
Personal/Private Credential When "Allow users to select credentials from the vault" is enabled, users can choose to authenticate the session to the target using a personal/private credential stored securely in their own Keeper Vault.
Just-In-Time Ephemeral Accounts When the ephemeral account feature is enabled on the PAM Machine or PAM database resources, a system-generated, time-limited privileged account is created specifically for the session. This account is deleted automatically after the session ends, eliminating standing privilege. This method is used for Just-In-Time access with no persistent account on the target system.
Starting a Connection
Once you have configured the SSH Protocol connection on your PAM Machine Record, your record will contain the following connection banner with the "Launch" Button:
Clicking Launch starts an SSH connection between Keeper Gateway and the target machine. The session is streamed into Keeper Vault, providing a fully interactive, passwordless SSH experience.
File Transfer
Transfer In
If the SFTP file transfer feature is enabled, the user can drag and drop files into the terminal session to transfer the files to the machine.
Keeper supports one or more files transferred simultaneously through drag-and-drop.
While the files are being uploaded to the target machine, a file transfer status is displayed in the dock area of the Keeper Vault:
Transfer Out
Files can be transferred from the target machine through Keeper Gateway and delivered to Vault with a native download prompt. To transfer files out, enable SFTP in the record’s Connection Settings before starting the session.
To transfer files from the SSH remote connection to the local filesystem, you can download a tool called guacctl into the remote system and use it for performing outbound transfers.
Download guacctl and set as executable:
Initiate the file download using this syntax:
SSH to Windows Servers
The SSH protocol can be used to access Windows servers for execution of PowerShell commands or other administrative actions.
Learn more on how to activate SSH on Windows
SSH Connection with Private Key
This section explains how to configure SSH authentication using a private key, optionally protected by a passphrase. The private key and passphrase are stored securely in a PAM User record and used automatically at session launch — the user does not need access to the credentials in order to connect.
The session is established from the Keeper Vault, through the Keeper Gateway, and directly to the target machine. The gateway decrypts the private key using the stored passphrase and authenticates on behalf of the user.
Configuring the Linux Server
Open a session to the target server using an existing SSH credential. In this example, we are using an RSA key pair but Keeper also supports ed25519, ECDSA and any key type supported by libssh2. Run the following commands in the terminal in order.
Step 1 — Generate a key pair with optional passphrase
Run the command similar to the example below to generate a key pair. The use of a private key passphrase is optional. If a passphrase is specified, it will be included in the PAM User record along with private key.
Note: If a passphrase is specified, avoid using special shell characters
Step 2 — Authorize the public key
Append the new public key to the authorized_keys file. This tells the SSH server to accept connections authenticated with the corresponding private key.
Step 3 — Set correct file permissions
SSH will silently reject a key if the file or directory permissions are too permissive. Run all three commands.
Step 4 — Copy the private key
Print the private key and copy the complete output to your clipboard. This includes the header line through to the footer line. This content will be pasted into the Keeper Vault record.
⚠️ Copy the entire output including
-----BEGIN OPENSSH PRIVATE KEY-----and-----END OPENSSH PRIVATE KEY-----. A missing header or footer line will result in Permission Denied / Aborted when launching the session.
Creating the PAM User Record
In Keeper Vault, create a new PAM User record to store the private key and optional passphrase. The gateway will retrieve these automatically at session launch.
Step 5 — Create the PAM User record
Navigate to the appropriate folder in the Vault. Click + Create New and select PAM User as the record type. Fill in the following fields:
Record Type
PAM User
Title
A descriptive name, e.g. ssh passphrase user authentication
Login
The SSH username on the target server (e.g. linuxuser)
Private PEM Key
Paste the full output of cat id_rsa_passphrase from Step 4. The field must include both the BEGIN and END header lines exactly as printed.
Private Key Passphrase
The passphrase entered in Step 1
⚠️ A missing header or footer line on the Private PEM Key field, or an incorrect passphrase, will result in Permission Denied / Aborted. See logs. when attempting to launch the session.
Click Save to store the record.
Configuring the PAM Machine Connection
Step 6 — Access Connection Settings
Open the PAM Machine record for your target server. Navigate to the Connection section on the PAM Settings screen by:
Clicking the gear icon on the PAM Machine record
Navigating to the Connection tab in the prompted window
Step 7 — Configure Connection Settings
Configure the following fields in the Connection tab:
Protocol
Required — select SSH from the protocol dropdown
Enable Connection
Required — toggle must be enabled to allow sessions on this record
Session Recording
Graphical Session Recording, Key Events, and Text Session Recording (Typescript) can be enabled or disabled based on your requirements
Connection Port
The port used to establish the SSH connection (default: 22; adjust as needed)
Launch Credentials
Select the PAM User record created above. The gateway will use these credentials to authenticate the session automatically.
Click Update to save the connection settings.
Starting a Connection
Once the Connection settings have been configured, the PAM Machine record will display the SSH protocol banner with a Launch button. Clicking Launch opens the session through the Keeper Gateway. The gateway retrieves the private key and passphrase from the PAM User record and authenticates to the server automatically — the user never sees or handles the credentials directly.
The session header confirms the authentication method as Key-based authentication only.
Troubleshooting
If the connection fails with "Permission Denied / Aborted. See logs." work through the following checklist in order:
1
The private key stored in the Keeper record matches the key generated on the server
Re-run cat /home/linuxuser/.ssh/id_rsa_passphrase on the server and paste the fresh output into the Private PEM Key field
2
The passphrase stored in the Keeper record is correct — no leading or trailing spaces
Edit the PAM User record and retype the passphrase carefully
3
The public key is present in authorized_keys on the server
Run cat /home/linuxuser/.ssh/authorized_keys and confirm the key ending in linuxuser-passphrase is present
4
File permissions on the .ssh directory and authorized_keys are correct
Re-run the chmod and chown commands from Step 3, then retry the connection
Check the Gatewayy logs to troubleshoot any connection issues.
SSH Certificate-Based Authentication
Overview
SSH certificate authentication allows organizations to use a single Certificate Authority (CA) to authorize users across thousands of servers — without distributing individual public keys to each machine. Instead:
The CA's public key is deployed once to every target server
Each user receives a signed certificate from the CA
When connecting, the user presents their private key + signed certificate
The server validates the certificate against the trusted CA — no per-user
authorized_keysneeded
This section covers how to set up a CA, sign a user certificate, and configure a KeeperPAM connection record to use certificate-based authentication.
Prerequisites
A KeeperPAM gateway deployed and online
A PAM Machine record in Keeper Vault pointing to the target SSH server
SSH access to the target machine to perform initial server-side configuration
ssh-keygenavailable on your local machine or the gateway host
Step 1 — Create a Certificate Authority (CA) Key Pair
Generate a CA key pair. This can be done on any trusted machine (your workstation, a bastion host, etc.).
This produces:
keeper_ca— the CA private key (keep this secure; never share it)keeper_ca.pub— the CA public key (this gets deployed to servers)
Note: Use a passphrase to protect the CA private key in production environments.
Step 2 — Configure the Target Server to Trust the CA
Copy keeper_ca.pub to the target SSH server and add the TrustedUserCAKeys directive to the SSH daemon configuration.
Reload the SSH daemon to apply the change:
Step 3 — Generate a User Key Pair
Generate a dedicated key pair for the user account that will be used for PAM connections.
This produces:
linuxuser_cert_key— user private keylinuxuser_cert_key.pub— user public key (to be signed by the CA)
Step 4 — Sign the User Public Key with the CA
Parameter reference:
-s keeper_ca
CA private key used for signing
-I "linuxuser-keeper"
Certificate identity (label, visible in logs)
-n linuxuser
Principal — must match the SSH login username on the target server
-V +52w
Validity period (52 weeks from now; adjust as needed)
This produces: linuxuser_cert_key-cert.pub
Verify the certificate:
Confirm the output shows:
Type:
[email protected] user certificatePrincipals: the target login username (e.g.,
linuxuser)Valid: date range that covers the current date
Step 5 — Create or Update the Keeper Credential Record
In Keeper Vault, the credential record used for the SSH connection must include both the user's private key and the signed certificate.
Record Type
Use a PAM User record type. Both fields required for certificate authentication are native to the PAM User record — no custom fields needed.
Login
SSH username on the target server (e.g., linuxuser)
Private PEM Key
Contents of linuxuser_cert_key — the private key block from -----BEGIN OPENSSH PRIVATE KEY----- to -----END OPENSSH PRIVATE KEY-----
Public Key
Contents of linuxuser_cert_key-cert.pub — the signed certificate, not the plain .pub file. This is the single long line starting with [email protected]
Step 6 — Link the Credential Record to the PAM Machine
On the PAM Machine record:
Open the record in Keeper Vault
Under Launch Credentials, set the linked credential to the record created in Step 5
Confirm the gateway shows Online in PAM Settings
Step 7 — Launch the Connection
Click Launch on the PAM Machine record. The gateway will retrieve the private key and SSH certificate from the credential record and present both to the SSH server during authentication.
The server validates the certificate against the trusted CA public key configured in Step 2. No authorized_keys entry is required for the user.
SSH Key Rotation with Certificate-based Auth
Important: If using certificate-based authentication, you need to prevent KeeperPAM from rotating the private keys.
In a custom field of the PAM User record, add a custom field called Private Key Rotate and set the value to FALSE. If set, Keeper will not rotate the private key.
Troubleshooting
"Permission Denied — Aborted. See logs."
Pull gateway logs and check the guacd lines:
Common causes:
Public key authentication failed: Username/PublicKey combination invalid
Server does not recognize the key or cert
Verify TrustedUserCAKeys is in /etc/ssh/sshd_config and sshd reloaded
Auth key successfully imported but connection fails
Cert not being presented
Confirm Public Key custom field exists and has correct content
No Auth public key line at all
Private key field is empty or malformed
Re-paste private key into the Private PEM Key field
Verify sshd is loading the CA config
On the target server:
Expected output (example):
Verify the certificate is valid and not expired
Check the Valid: field — if the current date is outside the range, re-sign the certificate.
Test certificate auth directly (bypassing Keeper)
From a machine that has access to the SSH server:
If this succeeds but the Keeper connection fails, the issue is in the record field mapping, not the server configuration.
Certificate Renewal
Certificates have a finite validity period set with the -V flag during signing. To renew:
Re-sign the user public key with the CA (Step 4) using a new validity window
Update the Public Key custom field in the Keeper credential record with the new certificate
No server-side changes are needed — the CA trust is already configured
Security Notes
The CA private key (
keeper_ca) should be stored securely and in the Keeper vault in a separate record. Only the signed user certificate goes in the PAM User recordPublic Keyfield.Certificates can be revoked before expiry using an
RevokedKeysfile on the server if needed.Use short validity periods (e.g., 24h or 7d) in high-security environments and automate certificate issuance.
The
-nprincipal must exactly match the login username. Mismatches result in authentication failure even with a valid certificate.
Session Recordings - SSH Protocol
To access session recordings, visit Session Activity screen.
For this protocol, both graphical and the full, raw text text content of terminal sessions, including timing information, are recorded. For more information on recordings and how to access these recordings, visit this page.
Learn more about Session Recording and Playback
KeeperAI Session Analysis
KeeperAI is an AI-driven threat detection and response engine built into KeeperPAM, designed to secure privileged access across environments. By analyzing behavior patterns and session activity in real time, it helps identify anomalies and high-risk actions. This is especially valuable for SSH connections, where command-level visibility is critical to preventing misuse.
To enable KeeperAI, visit the PAM Settings screen of the PAM Machine record.
Connection Templates
The PAM record for your target system can also be configured as a connection template. Connection templates are reusable record types that let you launch sessions to target systems without predefining a specific hostname or credential.
To enable a Connection Template for the PAM Machine record, select "Allow shared users to select their own host and credentials".
When using a connection template, the Keeper Gateway must have line of sight access to the designated hostname and port. The user will be prompted for the hostname, port and launch credentials.
Learn more about Connection Templates.
Just-In-Time Workflow
Workflow is a core capability within KeeperPAM that governs how SSH access is requested, approved, and granted. It enables organizations to enforce structured, just-in-time (JIT) access to SSH resources with full oversight and control. By requiring approvals and limiting session duration, Workflow ensures SSH access is both secure and auditable.
To enable Workflow for a PAM Machine, open the PAM Settings and select the Workflow tab.
SSH sessions can be configured for time-limited access, access approvals, single-user mode (check-in/check-out) and MFA.
Learn more about Workflow.
Terminal Connections with Commander CLI
Keeper Commander, the Command-line CLI and SDK provides launch capability into an terminal-based session type, including SSH, telnet, MySQL, PostgreSQL, SQL Server, etc.
To initiate a connection from the Commander CLI:
From the terminal, sessions can be launched outside of the Commander CLI:
Learn more about the Commander CLI
Last updated