Docs/ Replace SSH Keys with Short-Lived Certificates
View as .md

Replace SSH Keys with Short-Lived Certificates

Configure SSH servers to trust Vouch certificates for passwordless authentication

Windows: SSH certificate integration is not available on Windows. See the FAQ for details on Windows platform support.

Vouch replaces static SSH keys with short-lived certificates. Administrators trust a single certificate authority (CA) key, and developers receive SSH certificates that expire after 8 hours. There is no key distribution, no authorized_keys sprawl, and no offboarding checklist.

How it works

  1. During vouch login, the Vouch server signs the developer’s ephemeral public key with an Ed25519 CA key.
  2. The resulting SSH certificate is valid for 8 hours and contains the developer’s email address and username as principals.
  3. When the developer connects to a server, the SSH client presents the certificate.
  4. The server verifies the certificate was signed by the trusted CA and that one of the certificate’s principals matches an allowed user.
  5. The connection is established without any authorized_keys lookup.

Because certificates expire after 8 hours, a compromised certificate is useless the next day. There is nothing to revoke and nothing to rotate.

Step 1 – Set up the CLI (for developers)

After completing the Getting Started guide, enable the SSH agent integration:

vouch setup ssh

This command configures your local SSH client to use the Vouch agent for certificate authentication. It adds the following to your ~/.ssh/config:

Host *
  IdentityAgent ~/.vouch/ssh-agent.sock

After setup, every ssh connection will automatically use your Vouch certificate when available, falling back to regular keys if needed.

Verify the agent is running

vouch status

Look for the SSH agent line in the output. If the agent is not running, vouch login will start it automatically.

Check your certificate

After logging in, inspect the current certificate:

vouch credential ssh

This obtains a certificate from the server and displays the certificate’s principals, validity period, and signing CA.

Step 2 – Configure SSH servers (for administrators)

To accept Vouch certificates, each server must trust the Vouch CA public key. Below are three approaches for deploying this configuration.

You can find the CA public key on the Integrations page of the Vouch dashboard:

Integrations page showing SSH Certificates with CA public key

Fetch the CA public key

You can also retrieve your organization’s CA public key programmatically from the Vouch server:

curl -s https://us.vouch.sh/v1/credentials/ssh/ca | jq -r '.public_key'

Save the output – you will need it for each method below.

CLI (manual)

On each server, add the CA public key and create a drop-in sshd configuration file:

# Write the CA public key
echo "CONTENTS_OF_CA_PUB" | sudo tee /etc/ssh/vouch_ca.pub

# Configure sshd to trust the CA (drop-in config)
# See: https://man.openbsd.org/sshd_config#TrustedUserCAKeys
# See: https://man.openbsd.org/sshd_config#AuthorizedPrincipalsFile
sudo tee /etc/ssh/sshd_config.d/99-vouch.conf <<'SSHD'
TrustedUserCAKeys /etc/ssh/vouch_ca.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
SSHD

# Create a principals file for a specific user
sudo mkdir -p /etc/ssh/auth_principals
echo "alice@example.com" | sudo tee /etc/ssh/auth_principals/alice

# Restart sshd
sudo systemctl restart sshd

Ansible

- name: Configure Vouch SSH CA trust
  hosts: all
  become: true
  vars:
    vouch_ca_pub: "{{ (lookup('url', 'https://us.vouch.sh/v1/credentials/ssh/ca') | from_json).public_key }}"

  tasks:
    - name: Write Vouch CA public key
      copy:
        content: "{{ vouch_ca_pub }}"
        dest: /etc/ssh/vouch_ca.pub
        owner: root
        group: root
        mode: "0644"

    - name: Configure sshd to trust Vouch CA
      copy:
        content: |
          TrustedUserCAKeys /etc/ssh/vouch_ca.pub
          AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
        dest: /etc/ssh/sshd_config.d/99-vouch.conf
        owner: root
        group: root
        mode: "0644"
      notify: restart sshd

    - name: Create auth_principals directory
      file:
        path: /etc/ssh/auth_principals
        state: directory
        owner: root
        group: root
        mode: "0755"

  handlers:
    - name: restart sshd
      service:
        name: sshd
        state: restarted

Terraform (AWS EC2 user data)

resource "aws_instance" "example" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"

  user_data = <<-EOF
    #!/bin/bash
    set -e

    # Fetch and install the Vouch CA public key
    curl -s https://us.vouch.sh/v1/credentials/ssh/ca \
      | jq -r '.public_key' | tee /etc/ssh/vouch_ca.pub

    # Configure sshd to trust the CA (drop-in config)
    cat > /etc/ssh/sshd_config.d/99-vouch.conf <<'SSHD'
    TrustedUserCAKeys /etc/ssh/vouch_ca.pub
    AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
    SSHD

    mkdir -p /etc/ssh/auth_principals

    systemctl restart sshd
  EOF

  tags = {
    Name = "vouch-ssh-example"
  }
}

Tip: understanding principals

Vouch certificates include two principals by default:

PrincipalExampleUse case
Email addressalice@example.comUnique per-user access control
UsernamealiceMatches standard Unix usernames

When configuring AuthorizedPrincipalsFile, you can list either the email or the username (or both) in the principals file for each Unix account.

Example: To allow both alice@example.com and bob@example.com to SSH as the deploy user:

sudo mkdir -p /etc/ssh/auth_principals
printf "alice@example.com\nbob@example.com\n" | sudo tee /etc/ssh/auth_principals/deploy

If you do not configure AuthorizedPrincipalsFile, OpenSSH will accept any certificate signed by the trusted CA. This is convenient for testing but is not recommended for production.

Step 3 – Test the connection

From a developer machine with an active Vouch session:

# Log in if you have not already
vouch login

# Connect to a configured server
ssh alice@server.example.com

The connection should succeed without prompting for a password or key passphrase. To verify that certificate authentication was used, check the server’s auth log:

# On the server
sudo grep "Accepted certificate" /var/log/auth.log

You should see an entry like:

Accepted publickey for alice from 192.168.1.100 port 54321 ssh2: ED25519-CERT SHA256:... ID "alice@example.com" serial 42 CA ED25519 SHA256:...

Troubleshooting

“Permission denied (publickey)”

  • Confirm you have an active Vouch session: run vouch status.
  • Verify the Vouch agent is running and ~/.ssh/config includes the IdentityAgent line.
  • Check that the server has TrustedUserCAKeys pointing to the correct CA public key.
  • If using AuthorizedPrincipalsFile, verify that the file for the target user contains one of the certificate’s principals (email or username).

“Certificate has expired”

  • SSH certificates issued by Vouch are valid for 8 hours. Run vouch login to get a fresh certificate.

Agent not found

  • Run vouch login to start the agent, or restart it with vouch setup ssh.
  • Verify the socket path exists: ls -la ~/.vouch/ssh-agent.sock.

Server rejects the certificate even though it was signed by the right CA

  • Check AuthorizedPrincipalsFile permissions. The file and its parent directory must be owned by root and not writable by group or others.
  • Ensure the principals file is in the correct location (/etc/ssh/auth_principals/<username>).
  • Review /var/log/auth.log (or /var/log/secure on RHEL-based systems) for detailed error messages.

Connection falls back to password authentication

  • The server may not have TrustedUserCAKeys configured, or sshd may not have been restarted after the configuration change.
  • Run ssh -v user@server to see which authentication methods are attempted. Look for Offering public key: ... ED25519-CERT in the debug output.

IDE Remote Development

Because Vouch configures ~/.ssh/config with its agent, tools that build on top of SSH work automatically:

  • VS Code Remote-SSH – Open remote folders and terminals on any server trusted by the Vouch CA. No additional extension configuration is needed.
  • JetBrains Gateway – Connect to remote development environments using the same SSH certificate.
  • scp / rsync / sftp – File transfers use the Vouch SSH agent transparently.

As long as the Vouch agent is running and you have an active session, any tool that uses the system SSH client will authenticate with your Vouch certificate.