mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-17 11:18:16 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
276 lines
8.8 KiB
Plaintext
276 lines
8.8 KiB
Plaintext
---
|
|
title: "SSH"
|
|
sidebarTitle: "SSH"
|
|
description: "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 KMS and your private infrastructure.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant CLI as KMS CLI
|
|
participant Gateway
|
|
participant KMS
|
|
participant SSH as SSH Server
|
|
|
|
CLI->>KMS: Request session (authenticate)
|
|
KMS-->>CLI: Session ID + Gateway connection details
|
|
CLI->>Gateway: Connect via secure tunnel
|
|
Gateway->>KMS: Fetch credentials for session
|
|
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. 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 KMS CA to authorize connections
|
|
- **Simplified management**: KMS handles the certificate lifecycle for each connection
|
|
- **Audit trail**: Each certificate is tied to a specific user and session
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant CLI as KMS CLI
|
|
participant Gateway
|
|
participant KMS
|
|
participant SSH as SSH Server
|
|
|
|
CLI->>KMS: Request session (authenticate)
|
|
KMS-->>CLI: Session ID + Gateway connection details
|
|
CLI->>Gateway: Connect via secure tunnel
|
|
Gateway->>KMS: Fetch credentials for session
|
|
KMS->>KMS: Generate key pair + sign certificate
|
|
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:
|
|
|
|
1. **An KMS Gateway** deployed with network reachability to your SSH servers
|
|
2. **Network connectivity** from the Gateway to your SSH servers on port 22 (or custom SSH port)
|
|
3. **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.
|
|
|
|
<Steps>
|
|
<Step title="Navigate to Resources">
|
|
Go to your PAM project and click on the **Resources** tab.
|
|
</Step>
|
|
|
|
<Step title="Add SSH Resource">
|
|
Click **Add Resource** and select **SSH**.
|
|
</Step>
|
|
|
|
<Step title="Configure Connection Details">
|
|
Fill in the connection details:
|
|
|
|
<ParamField path="Name" type="string" required>
|
|
A friendly name for this resource (e.g., `production-server`, `bastion-host`)
|
|
</ParamField>
|
|
|
|
<ParamField path="Gateway" type="string" required>
|
|
Select the Gateway that has network access to this SSH server
|
|
</ParamField>
|
|
|
|
<ParamField path="Host" type="string" required>
|
|
The hostname or IP address of the SSH server (e.g., `192.168.1.100` or `server.internal.example.com`)
|
|
</ParamField>
|
|
|
|
<ParamField path="Port" type="number" required>
|
|
The SSH port (default: `22`)
|
|
</ParamField>
|
|
</Step>
|
|
|
|
<Step title="Create the Resource">
|
|
Click **Create Resource**. KMS will validate that the Gateway can reach the SSH server.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## 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
|
|
|
|
<Steps>
|
|
<Step title="Navigate to Resource">
|
|
Go to the **Resources** tab in your PAM project and open your SSH resource.
|
|
</Step>
|
|
|
|
<Step title="Add Account">
|
|
Click **Add Account**.
|
|
</Step>
|
|
|
|
<Step title="Configure Password Auth">
|
|
<ParamField path="Name" type="string" required>
|
|
A friendly name for this account (e.g., `ubuntu-admin`, `deploy-user`)
|
|
</ParamField>
|
|
|
|
<ParamField path="Authentication Method" type="string" required>
|
|
Select **Password**
|
|
</ParamField>
|
|
|
|
<ParamField path="Username" type="string" required>
|
|
The SSH username on the server
|
|
</ParamField>
|
|
|
|
<ParamField path="Password" type="string" required>
|
|
The SSH password for this user
|
|
</ParamField>
|
|
</Step>
|
|
</Steps>
|
|
|
|
### SSH Key Authentication
|
|
|
|
<Steps>
|
|
<Step title="Add Account">
|
|
Click **Add Account** and select your SSH resource.
|
|
</Step>
|
|
|
|
<Step title="Configure Key Auth">
|
|
<ParamField path="Name" type="string" required>
|
|
A friendly name for this account
|
|
</ParamField>
|
|
|
|
<ParamField path="Authentication Method" type="string" required>
|
|
Select **SSH Key**
|
|
</ParamField>
|
|
|
|
<ParamField path="Username" type="string" required>
|
|
The SSH username on the server
|
|
</ParamField>
|
|
|
|
<ParamField path="Private Key" type="string" required>
|
|
The private key in OpenSSH format (begins with `-----BEGIN OPENSSH PRIVATE KEY-----`)
|
|
</ParamField>
|
|
</Step>
|
|
</Steps>
|
|
|
|
### Certificate Authentication
|
|
|
|
Certificate authentication requires additional setup on your SSH server to trust the KMS CA.
|
|
|
|
<Steps>
|
|
<Step title="Configure the SSH Server">
|
|
Before creating the account, you need to configure your SSH server to trust certificates signed by KMS.
|
|
|
|
Run the following command on your SSH server (requires root/sudo):
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer <YOUR_TOKEN>" \
|
|
"https://kms.hanzo.ai/api/v1/pam/resources/ssh/<RESOURCE_ID>/ssh-ca-setup" \
|
|
| sudo bash
|
|
```
|
|
|
|
This script will:
|
|
1. Download the CA public key for your SSH resource
|
|
2. Save it to `/etc/ssh/kms_ca.pub`
|
|
3. Add `TrustedUserCAKeys /etc/ssh/kms_ca.pub` to `/etc/ssh/sshd_config`
|
|
4. Validate and restart the SSH service
|
|
|
|
<Info>
|
|
**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.
|
|
</Info>
|
|
|
|
<Warning>
|
|
**Manual setup**: If you prefer to configure the server manually, you can download just the CA public key and configure sshd yourself:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer <YOUR_TOKEN>" \
|
|
"https://kms.hanzo.ai/api/v1/pam/resources/ssh/<RESOURCE_ID>/ssh-ca-public-key" \
|
|
| sudo tee /etc/ssh/kms_ca.pub
|
|
```
|
|
|
|
Then configure sshd:
|
|
1. Add to `/etc/ssh/sshd_config`:
|
|
```
|
|
TrustedUserCAKeys /etc/ssh/kms_ca.pub
|
|
```
|
|
2. Restart sshd: `sudo systemctl restart sshd`
|
|
</Warning>
|
|
</Step>
|
|
|
|
<Step title="Add Account in KMS">
|
|
<ParamField path="Name" type="string" required>
|
|
A friendly name for this account
|
|
</ParamField>
|
|
|
|
<ParamField path="Authentication Method" type="string" required>
|
|
Select **Certificate**
|
|
</ParamField>
|
|
|
|
<ParamField path="Username" type="string" required>
|
|
The SSH username that the certificate will be issued for. This user must exist on the SSH server.
|
|
</ParamField>
|
|
|
|
<Note>
|
|
Unlike password or key authentication, you don't need to provide any credentials. KMS will generate a new key pair and certificate for each session.
|
|
</Note>
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Access SSH Servers
|
|
|
|
Once your resource and accounts are configured, users can access SSH servers through the KMS CLI.
|
|
|
|
<Steps>
|
|
<Step title="Install the CLI">
|
|
If you haven't already, install the KMS CLI:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Login to KMS">
|
|
```bash
|
|
hanzo-kms login
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Connect to SSH Server">
|
|
Specify the **resource name** and **account name** as shown in KMS:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
kms pam ssh access --resource production-server --account ubuntu-admin --project-id 00000000-0000-0000-0000-000000000000 --duration 1h
|
|
```
|
|
</Step>
|
|
</Steps>
|