# SSH Connections

## 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.

<figure><img src="/files/Kpao838xIHcaicPAPSnG" alt=""><figcaption></figcaption></figure>

## Prerequisites

Prior to following this guide, familiarize yourself with the prerequisites on the Connection's [Getting Started page](/keeperpam/privileged-access-manager/connections/getting-started.md).

The following PAM records are needed in order to successfully setup this protocol:

<table><thead><tr><th width="211">PAM Record</th><th>Definition</th></tr></thead><tbody><tr><td><a href="/pages/r3KpQ6RkUwiqQMMpRR7r">PAM Configuration</a></td><td>The PAM Configuration contains information of your target infrastructure.</td></tr><tr><td><a href="/pages/XTyf98IFn0oRnCoEILhY">PAM Machine</a> Record</td><td>The PAM Machine record stores the endpoint details needed to establish an SSH connection.</td></tr><tr><td><a href="/pages/T4j5fXFV7knAjQZ8QKj1">PAM User</a> Record</td><td>The PAM User record stores the credentials used to connect to the endpoint or generate ephemeral credentials.</td></tr></tbody></table>

{% hint style="info" %}
This guide will use a Linux server to represent a PAM Machine record.
{% endhint %}

## 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:

1. Editing the PAM Record
2. Clicking on "Set Up" in the PAM Settings section
3. Navigate to the "Connection" section in the prompted window

<figure><img src="/files/mMT87VpnphY6HRMslFht" alt=""><figcaption><p>PAM Settings on a PAM Machine Record</p></figcaption></figure>

### 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:

<table><thead><tr><th width="293">Field</th><th>Description</th></tr></thead><tbody><tr><td>PAM Configuration</td><td>This is the PAM Configuration that contains the details of your target infrastructure and provides access to the target configured on the PAM Record.</td></tr><tr><td>Administrative Credential Record</td><td>This is the linked <a href="/pages/T4j5fXFV7knAjQZ8QKj1">PAM User</a> that will be used to authenticate to the target and perform administrative operations such as rotation or account creation</td></tr></tbody></table>

The following table lists all the configurable connection settings for the SSH protocol on the PAM Settings:

### Connection Parameters

<figure><img src="/files/Q2ClQBrF5aPQ2n0CnFuW" alt=""><figcaption><p>Connection Parameters</p></figcaption></figure>

<table><thead><tr><th width="295">Field</th><th>Definition</th></tr></thead><tbody><tr><td>Protocol</td><td><p><strong>Required</strong></p><p>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</p></td></tr><tr><td>Enable Connection</td><td><p><strong>Required</strong></p><p>To enable connection for this record, this toggle needs to be enabled</p></td></tr><tr><td>Graphical Session Recording</td><td>When enabled, graphical session recordings will be enabled for this record</td></tr><tr><td>Text Session Recording (Typescript)</td><td>When enabled, text session recordings (typescript) will be enabled for this record</td></tr><tr><td>Key Events</td><td>When enabled, the individual keystroke data will be included in the session playback. Note: This will include any secrets potentially typed by the user.</td></tr><tr><td>Connection Port</td><td>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.<br><br>For SSH, the default port is 22</td></tr><tr><td>Launch Credentials</td><td>When configured, these credentials will be used to authenticate the connection. More details <a href="#connection-authentication-methods">here</a></td></tr><tr><td>Allow users to select credentials from their vault</td><td>When enabled, allow users to use their own personal/private credentials to authenticate the connection. More details <a href="#connection-authentication-methods">here</a></td></tr><tr><td>Rotate launch credentials upon session termination</td><td>When enabled, the configured launch credentials will be automatically rotated when the session is closed</td></tr><tr><td>Public Host Key (Base64)</td><td>The known hosts entry for the SSH server, in the same format as would be specified within an OpenSSH <code>known_hosts</code> file. If not provided, no verification of host identity will be performed.</td></tr><tr><td>Color Scheme</td><td><p>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:</p><ul><li>"black on white" - Black text over a white background</li><li>"gray on black" - Gray text over a black background (the default)</li><li>"green on black" - Green text over a black background</li><li>"white on black" - White text over a black background</li><li>"Custom" - custom color scheme</li></ul><p>Default value is "white-black"</p></td></tr><tr><td>Font Size</td><td>Font size displayed for the terminal session</td></tr><tr><td>Font Name</td><td>The name of the font to use. If not specified, the default of "monospace" will be used instead. <strong>This must be the name of a font installed on the server running guacd, and should be a monospaced font.</strong> If a non-monospaced font is used, individual glyphs may render incorrectly.</td></tr><tr><td>Maximum scrollback size</td><td>The maximum number of rows to allow within the terminal <code>scrollback</code> buffer. By default, the <code>scrollback</code> buffer will be limited to a maximum of 1000 rows.</td></tr><tr><td>SFTP</td><td>If enabled, the user can drag and drop files into the terminal session to transfer one or more files.</td></tr><tr><td>File Browser Root Directory</td><td>If SFTP is enabled, file transfers will be saved to the specified folder path.</td></tr><tr><td>Can copy to clipboard</td><td>If enabled, text copied within the connected protocol session will be accessible by the user.</td></tr><tr><td>Can paste from clipboard</td><td>If enabled, user can paste text from clipboard within the connected protocol session.</td></tr><tr><td>Read-only</td><td>Whether this connection should be <code>read-only</code>. 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.</td></tr></tbody></table>

### Session / Environment Parameters <a href="#id-.sshv2.x-session-environmentparameters" id="id-.sshv2.x-session-environmentparameters"></a>

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.

<figure><img src="/files/VEB2Xv3ASpa0xUlvPM1B" alt=""><figcaption><p>Environment Parameters</p></figcaption></figure>

| Field                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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)   | <p>The specific locale to request for the SSH session. This may be any value accepted by the <code>LANG</code> environment variable of the SSH server. If not specified, the SSH server's default locale will be used.</p><p><strong>As this parameter is sent to the SSH server using the <code>LANG</code> environment variable, the parameter will only have an effect if the SSH server allows the <code>LANG</code> environment variable to be set by SSH clients.</strong></p>                                                             |
| Time zone ($TZ)           | <p>The time zone to request for the SSH session. This may be any value accepted by the <code>TZ</code> 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.</p><p><strong>As this parameter is sent to the SSH server using the <code>TZ</code> environment variable, the parameter will only have an effect if the SSH server allows the <code>TZ</code> environment variable to be set by SSH clients.</strong></p> |
| 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 <a href="#id-.sshv2.x-terminalbehaviorparameters" id="id-.sshv2.x-terminalbehaviorparameters"></a>

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.

| Field               | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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**](/keeperpam/privileged-access-manager/connections/authentication-methods.md#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**](/keeperpam/privileged-access-manager/connections/authentication-methods.md#personal-private-credentials)\
  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**](/keeperpam/privileged-access-manager/connections/authentication-methods.md#ephemeral-account)\
  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](/keeperpam/privileged-access-manager/just-in-time-access-jit.md) 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:

<figure><img src="/files/JJSGPwIMir5ZGGIXbvqB" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="/files/lwn4F5fSSM785u1nwRzs" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/pHSC1VRKDFjbpYkhBPRc" alt=""><figcaption></figcaption></figure>

## 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.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FGUHA9hRGHzUZ07N2oMSA%2FScreenshot%202025-02-09%20at%208.15.45%E2%80%AFPM.png?alt=media&#x26;token=55f1b1fa-2a39-430e-b991-cceda12355ad" alt=""><figcaption><p>SFTP File Transfer Options</p></figcaption></figure>

Keeper supports one or more files transferred simultaneously through drag-and-drop.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F53Sn5P6KscJtt7usRQWh%2Fdrag-and-drop.png?alt=media&#x26;token=e07ef4fa-c6ad-49e0-acb4-64e0a042dd36" alt=""><figcaption></figcaption></figure>

While the files are being uploaded to the target machine, a file transfer status is displayed in the dock area of the Keeper Vault:

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FPAOewYiPjJuOgJsngzSX%2Fupload-progress.png?alt=media&#x26;token=50307229-bdbe-4704-bd53-f8485bda7681" alt=""><figcaption><p>File Upload Status</p></figcaption></figure>

#### 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:

```
wget https://raw.githubusercontent.com/apache/guacamole-server/master/bin/guacctl
chmod +x guacctl
```

Initiate the file download using this syntax:

```
./guacctl -d <filename>
```

## 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](/keeperpam/privileged-access-manager/references/setting-up-ssh.md#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.

```bash
ssh-keygen -t rsa -b 4096 -f /home/linuxuser/.ssh/id_rsa_passphrase -C "my-passphrase"
```

> **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.

```bash
cat /home/linuxuser/.ssh/id_rsa_passphrase.pub >> /home/linuxuser/.ssh/authorized_keys
```

#### 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.

```bash
chmod 600 /home/linuxuser/.ssh/authorized_keys
chmod 700 /home/linuxuser/.ssh
chown -R linuxuser:linuxuser /home/linuxuser/.ssh
```

#### 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.

```bash
cat /home/linuxuser/.ssh/id_rsa_passphrase
```

> ⚠️ 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:

| Field                  | Value                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.

<figure><img src="/files/XajykisUVZufiWiLGHYN" alt=""><figcaption><p>PAM User with SSH Key and Optional Passphrase</p></figcaption></figure>

### 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:

1. Clicking the **gear icon** on the PAM Machine record
2. Navigating to the **Connection** tab in the prompted window

#### Step 7 — Configure Connection Settings

Configure the following fields in the Connection tab:

| Field              | Description                                                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| 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:

<table><thead><tr><th width="78.73046875">#</th><th>Check</th><th>Resolution</th></tr></thead><tbody><tr><td>1</td><td>The private key stored in the Keeper record matches the key generated on the server</td><td>Re-run <code>cat /home/linuxuser/.ssh/id_rsa_passphrase</code> on the server and paste the fresh output into the Private PEM Key field</td></tr><tr><td>2</td><td>The passphrase stored in the Keeper record is correct — no leading or trailing spaces</td><td>Edit the PAM User record and retype the passphrase carefully</td></tr><tr><td>3</td><td>The public key is present in <code>authorized_keys</code> on the server</td><td>Run <code>cat /home/linuxuser/.ssh/authorized_keys</code> and confirm the key ending in <code>linuxuser-passphrase</code> is present</td></tr><tr><td>4</td><td>File permissions on the <code>.ssh</code> directory and <code>authorized_keys</code> are correct</td><td>Re-run the <code>chmod</code> and <code>chown</code> commands from Step 3, then retry the connection</td></tr></tbody></table>

Check the Gatewayy logs to troubleshoot any connection issues.

```bash
docker compose logs -f keeper-gateway
```

***

## 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_keys` needed

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-keygen` available 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.).

```bash
ssh-keygen -t ed25519 -f keeper_ca -C "KeeperPAM CA"
```

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.

```bash
# Copy CA public key to the server
sudo cp keeper_ca.pub /etc/ssh/keeper_ca.pub

# Add to sshd config (Rocky Linux / RHEL / Ubuntu path)
echo "TrustedUserCAKeys /etc/ssh/keeper_ca.pub" | sudo tee -a /etc/ssh/sshd_config

# Verify the line was added
grep TrustedUserCAKeys /etc/ssh/sshd_config
```

Reload the SSH daemon to apply the change:

```bash
# systemd-based systems (most Linux distros)
sudo systemctl reload sshd

# Docker containers or systems without systemd
sudo kill -HUP $(sudo cat /var/run/sshd.pid)
# or
sudo pkill sshd && sudo /usr/sbin/sshd
```

***

### Step 3 — Generate a User Key Pair

Generate a dedicated key pair for the user account that will be used for PAM connections.

```bash
ssh-keygen -t ed25519 -f linuxuser_cert_key -N "" -C "linuxuser cert key"
```

This produces:

* `linuxuser_cert_key` — user private key
* `linuxuser_cert_key.pub` — user public key (to be signed by the CA)

***

### Step 4 — Sign the User Public Key with the CA

```bash
ssh-keygen -s keeper_ca \
  -I "linuxuser-keeper" \
  -n linuxuser \
  -V +52w \
  linuxuser_cert_key.pub
```

**Parameter reference:**

| Parameter               | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `-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:

```bash
ssh-keygen -L -f linuxuser_cert_key-cert.pub
```

Confirm the output shows:

* **Type:** `ssh-ed25519-cert-v01@openssh.com user certificate`
* **Principals:** 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.

<figure><img src="/files/4Gv61pxPKf1aVuYetYHT" alt=""><figcaption></figcaption></figure>

#### 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.

| Field               | Value                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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 `ssh-ed25519-cert-v01@openssh.com` |

***

### Step 6 — Link the Credential Record to the PAM Machine

On the PAM Machine record:

1. Open the record in Keeper Vault
2. Under **Launch Credentials**, set the linked credential to the record created in Step 5
3. Confirm the gateway shows **Online** in PAM Settings

<figure><img src="/files/uBjP1F0tMEQjSYQtKAQ9" alt=""><figcaption></figcaption></figure>

***

### 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

{% hint style="danger" %}
Important: If using certificate-based authentication, you need to prevent KeeperPAM from rotating the private keys.
{% endhint %}

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:

```bash
docker logs <gateway_container_name> --tail 100 2>&1 | grep -iE "guacd|auth|cert|error"
```

**Common causes:**

| Log message                                                                | Cause                                     | Fix                                                                       |
| -------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
| `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:

```bash
sudo sshd -T | grep trustedusercakeys
```

Expected output (example):

```
trustedusercakeys /etc/ssh/keeper_ca.pub
```

#### Verify the certificate is valid and not expired

```bash
ssh-keygen -L -f linuxuser_cert_key-cert.pub
```

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:

```bash
ssh -i linuxuser_cert_key \
    -o CertificateFile=linuxuser_cert_key-cert.pub \
    -p 2222 linuxuser@<server-address>
```

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:

1. Re-sign the user public key with the CA (Step 4) using a new validity window
2. Update the **Public Key** custom field in the Keeper credential record with the new certificate
3. 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 record `Public Key` field.
* Certificates can be revoked before expiry using an `RevokedKeys` file on the server if needed.
* Use short validity periods (e.g., 24h or 7d) in high-security environments and automate certificate issuance.
* The `-n` principal 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.

<figure><img src="/files/HoMJZgcl0vADeW4OZ02B" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/PMY5DqP9CtbtXZeNF0do" alt=""><figcaption></figcaption></figure>

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](/keeperpam/privileged-access-manager/session-recording-and-playback.md).

* Learn more about [Session Recording and Playback](/keeperpam/privileged-access-manager/session-recording-and-playback.md)

## 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.

<figure><img src="/files/5wIPFFqlfjFGGmtBkvmT" alt=""><figcaption></figcaption></figure>

* [Learn more about KeeperAI](/keeperpam/privileged-access-manager/keeperai.md)

## 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".

<figure><img src="/files/nHAqi9hlmnptPvV5IS92" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="/files/sTuXKegovHXBpr9BUE9x" alt=""><figcaption><p>SSH Connection Template</p></figcaption></figure>

* Learn more about [Connection Templates](/keeperpam/privileged-access-manager/connections/connection-templates.md).

***

## 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.

<figure><img src="/files/to8KBEnbdeUyeiuD5b3G" alt=""><figcaption></figcaption></figure>

SSH sessions can be configured for time-limited access, access approvals, single-user mode (check-in/check-out) and MFA.

* Learn more about [Workflow](/keeperpam/privileged-access-manager/just-in-time-access-jit/workflow.md).

***

## 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:

```
My Vault> pam launch <UID>

Launching connection to SSH to Linux Gateway Host (i-028348b3257e8c550)...
⠧ [ Establishing secure session… ]

   ,     #_
   ~\_  ####_        Amazon Linux 2023
  ~~  \_#####\
  ~~     \###|
  ~~       \#/ ___   https://aws.amazon.com/linux/amazon-linux-2023
   ~~       V~' '->
    ~~~         /
      ~~._.   _/
         _/ _/
       _/m/'
Last login: Wed May  6 02:10:58 2026 from 192.168.1.11
[ec2-user@ip-10-0-0-137 ~]$ 
```

From the terminal, sessions can be launched outside of the Commander CLI:

```
$ keeper pam launch <UID>
```

* [Learn more](/keeperpam/commander-cli/overview.md) about the Commander CLI


---

# Agent Instructions: 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:

```
GET https://docs.keeper.io/keeperpam/privileged-access-manager/connections/session-protocols/ssh-connections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.
