SSH

Learn how to configure SSH server access through KMS PAM with support for password, key-based, and certificate-based authentication.

KMS PAM supports secure, just-in-time access to SSH servers. This allows your team to access Linux/Unix servers without sharing static credentials, while maintaining a complete audit trail of all sessions.

How It Works

SSH access in KMS PAM uses a Gateway deployed in your network to establish secure connections to your servers. The Gateway acts as a bridge between Hanzo KMS and your private infrastructure.

sequenceDiagram
    participant CLI as KMS CLI
    participant Gateway
    participant Hanzo KMS
    participant SSH as SSH Server

    CLI->>Hanzo KMS: Request session (authenticate)
    Hanzo KMS-->>CLI: Session ID + Gateway connection details
    CLI->>Gateway: Connect via secure tunnel
    Gateway->>Hanzo KMS: Fetch credentials for session
    Hanzo KMS-->>Gateway: Return credentials
    Gateway->>SSH: Connect with credentials
    SSH-->>Gateway: Session established
    Gateway-->>CLI: Proxied SSH session

Authentication Methods

KMS PAM supports three authentication methods for SSH:

Method	Description	Use Case
Password	Traditional username/password authentication	Legacy systems, simple setups
SSH Key	Public key authentication with a private key	Standard secure access
Certificate	SSH certificates signed by a CA	Zero-trust, ephemeral credentials

Certificate-Based Authentication

Certificate-based authentication allows for the use of ephemeral credentials. Hanzo KMS generates short-lived SSH certificates on-demand for each session.

Benefits:

Ephemeral access: Certificates are generated per-session and expire automatically

Centralized trust: Servers trust the Hanzo KMS CA to authorize connections

Simplified management: Hanzo KMS handles the certificate lifecycle for each connection

Audit trail: Each certificate is tied to a specific user and session

sequenceDiagram
    participant CLI as KMS CLI
    participant Gateway
    participant Hanzo KMS
    participant SSH as SSH Server

    CLI->>Hanzo KMS: Request session (authenticate)
    Hanzo KMS-->>CLI: Session ID + Gateway connection details
    CLI->>Gateway: Connect via secure tunnel
    Gateway->>Hanzo KMS: Fetch credentials for session
    Hanzo KMS->>Hanzo KMS: Generate key pair + sign certificate
    Hanzo KMS-->>Gateway: Return private key + certificate
    Gateway->>SSH: Connect with certificate
    SSH->>SSH: Verify certificate against CA
    SSH-->>Gateway: Session established
    Gateway-->>CLI: Proxied SSH session

Prerequisites

Before configuring SSH access in KMS PAM, ensure you have:

An KMS Gateway deployed with network reachability to your SSH servers

Network connectivity from the Gateway to your SSH servers on port 22 (or custom SSH port)

SSH server credentials (password, private key, or CA setup for certificate auth)

Create the PAM Resource

The PAM Resource represents the SSH server you want to protect.

Go to your PAM project and click on the Resources tab.

Click Add Resource and select SSH.

Fill in the connection details:

A friendly name for this resource (e.g., production-server, bastion-host)

Select the Gateway that has network access to this SSH server

The hostname or IP address of the SSH server (e.g., 192.168.1.100 or server.internal.example.com)

The SSH port (default: 22)

Click Create Resource. Hanzo KMS will validate that the Gateway can reach the SSH server.

Create PAM Accounts

A PAM Account represents a specific user account on the SSH server. You can create multiple accounts per resource with different authentication methods.

Password Authentication

Go to the Resources tab in your PAM project and open your SSH resource.

Click Add Account.

A friendly name for this account (e.g., ubuntu-admin, deploy-user)

Select Password

The SSH username on the server

The SSH password for this user

SSH Key Authentication

Click Add Account and select your SSH resource.

A friendly name for this account

Select SSH Key

The SSH username on the server

The private key in OpenSSH format (begins with -----BEGIN OPENSSH PRIVATE KEY-----)

Certificate Authentication

Certificate authentication requires additional setup on your SSH server to trust the Hanzo KMS CA.

Before creating the account, you need to configure your SSH server to trust certificates signed by Hanzo KMS.

Run the following command on your SSH server (requires root/sudo):

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
  "https://app.kms.hanzo.ai/api/v1/pam/resources/ssh/<RESOURCE_ID>/ssh-ca-setup" \
  | sudo bash

This script will:

Download the CA public key for your SSH resource
Save it to /etc/ssh/kms_ca.pub
Add TrustedUserCAKeys /etc/ssh/kms_ca.pub to /etc/ssh/sshd_config
Validate and restart the SSH service

First-time setup: The CA key pair is generated automatically when you first call the setup endpoint. Subsequent calls will return the same CA public key.

Manual setup: If you prefer to configure the server manually, you can download just the CA public key and configure sshd yourself:

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
  "https://app.kms.hanzo.ai/api/v1/pam/resources/ssh/<RESOURCE_ID>/ssh-ca-public-key" \
  | sudo tee /etc/ssh/kms_ca.pub

Then configure sshd:

Add to /etc/ssh/sshd_config:
```
TrustedUserCAKeys /etc/ssh/kms_ca.pub
```
Restart sshd: sudo systemctl restart sshd

A friendly name for this account

Select Certificate

The SSH username that the certificate will be issued for. This user must exist on the SSH server.

Unlike password or key authentication, you don't need to provide any credentials. Hanzo KMS will generate a new key pair and certificate for each session.

Access SSH Servers

Once your resource and accounts are configured, users can access SSH servers through the KMS CLI.

If you haven't already, install the KMS CLI:

# macOS
brew install kms/get-cli/kms

# Linux
curl -1sLf 'https://artifacts-cli.kms.hanzo.ai/setup.deb.sh' | sudo -E bash
sudo apt-get install kms

kms login

Specify the resource name and account name as shown in Hanzo KMS:

kms pam ssh access --resource <resource-name> --account <account-name> --project-id <project-id> --duration <duration>

For example, to access the account ubuntu-admin on the resource production-server:

kms pam ssh access --resource production-server --account ubuntu-admin --project-id 00000000-0000-0000-0000-000000000000 --duration 1h

On this page