Skip to main content

SSH Client and Host Onboarding Guide

QUICKQuickest

PREREQUISITE:

ul

sudo -iu akadmin vw unlock

n00b

cat /etc/ssh/ssh_host_ed25519_key

ul

vim ~/.ssh/authorized_keys
# type-y type-y

n00b

ssh -i /etc/ssh/ssh_host_ed25519_key ul
# test ^
cat /etc/ssh/ssh_host_ed25519_key.pub | ssh ul "sudo sign-host-key n00b -l n00b0x" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub
sudo chmod 644 /etc/ssh/ssh_host_ed25519_key-cert.pub
printf 'HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub\n' | sudo tee /etc/ssh/sshd_config.d/10-cert.conf
sudo sshd -T -f /etc/ssh/sshd_config | grep -q HostCertificate || echo fail
sudo systemctl reload sshd

UNLOCK VAULTWARDEN

The CA signing keys reside in Vaultwarden and are kept in volatile memory for 1 hour once unlocked. Before onboarding, log into ul and unlock the vault:

sudo -iu akadmin vw unlock

WORKFLOW 1: ONBOARDING A NEW HOST (Server Host Certificate)

Host certificates allow clients to verify the authenticity of a server automatically without manual fingerprint checks ("The authenticity of host ... can't be established").

1. Generate Host Keypair on New Machine

On the machine being onboarded,onboarded "n00b", generate its standard Ed25519 host key (if it does not already exist):

sudo ssh-keygen -t ed25519 -f /etc/ssh/ssh_host_ed25519_key -N ""

2. Out-of-Band Bootstrap & Verification

To guarantee the key is not corrupted or truncated by a typo before signing, verifyVerify it using authorized_keys first:

  1. Copy the host'n00b's public key text (/etc/ssh/ssh_host_ed25519_key.pub) out-of-band (e.g., via console, terminal paste, or phone).
  2. Add it to ~/.ssh/authorized_keys on ul: 
    # On ul:
echo "<ssh_host_ed25519_key.pub content>" >> ~/.ssh/authorized_keys
    ul.
  3. Test SSH connectivity from the new host to ul: 
    ssh -i /etc/ssh/ssh_host_ed25519_key ul

If this login succeeds, the public key is proven 100% valid and operational.Verified!

3. Mint Signed Host Certificate

From the new host, stream the public key over that verified SSH connection directly into sign-host-key:

cat /etc/ssh/ssh_host_ed25519_key.pub | ssh -t ul "sudo sign-host-key <hostname> [principals]" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub
    Interactive Label: The script prompts for an inventory label on your terminal (e.g. Enter inventory label for this host [<hostname>]: ). Automated Label: You can pass --label <name> or -l <name> to skip the prompt: 
    cat /etc/ssh/ssh_host_ed25519_key.pub | ssh ul "sudo sign-host-key bmo95 -l studio-pc" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub
    • Custom Principals: To specify custom DNS names or IP addresses: 
      cat /etc/ssh/ssh_host_ed25519_key.pub | ssh -t ul "sudo sign-host-key danknasty danknasty,danknasty.drheck.dev,10.0.0.1,fd77:7777:5010::1" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub
    • Set file permissions on the new host: 
      sudo chmod 644 /etc/ssh/ssh_host_ed25519_key-cert.pub

    4. Configure sshd on the New Host

    Add the host certificate to the SSH daemon configuration on the new host (/etc/ssh/sshd_config or /etc/ssh/sshd_config.d/10-cert.conf):

    HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

    Reload the SSH daemon:

    sudo systemctl reload sshd
# or on OpenBSD: doas rcctl reload sshd

    5. De-provision Bootstrap Key

    Remove the temporary bootstrap entry from ~/.ssh/authorized_keys on ul.ul.

    WORKFLOW 2: ONBOARDING A NEW USER (Client User Certificate)

    User certificates allow clients to log into servers without putting per-user public keys in .ssh/authorized_keys.

    1. Generate User Keypair on Client Workstation

    On your laptop or workstation:

    ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "workstation-label"

    2. Out-of-Band Bootstrap & Verification

    1. Copy ~/.ssh/id_ed25519.pub out-of-band and temporarily append it to ~/.ssh/authorized_keys on ul.
    2. Confirm login works: 
      ssh ul

    3. Mint Signed User Certificate

    From your client workstation, pipe your public key into sign-user-key:

    cat ~/.ssh/id_ed25519.pub | ssh -t ul "sudo sign-user-key <ldap_username>" > ~/.ssh/id_ed25519-cert.pub
chmod 644 ~/.ssh/id_ed25519-cert.pub

    Note: The principal <ldap_username> must exactly match the Authentik/LDAP username on ul.

    4. De-provision Bootstrap Key

    Remove the raw public key from ~/.ssh/authorized_keys on ul.

    5. Verify Certificate Authentication

    Test login with verbose output:

    ssh -v ul

    Confirm the server accepts the certificate:

    Server accepts key: pkalg ssh-ed25519-cert-v01@openssh.com

    CLIENT CONFIGURATION: TRUSTING THE HOST CA

    To ensure client workstations trust all servers signed by the DrHeck Host CA without fingerprint prompts, add this line to /etc/ssh/ssh_known_hosts (system-wide) or ~/.ssh/known_hosts:

    @cert-authority * ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIC0m1wzW2e50529d+E3iA7x8iM3Q8qS5q7iVjGvF8e7d

    (Replace with the actual public key from /etc/ssh/drheck_ca_host_key.pub).

    QUICK REVOCATION REFERENCE

    Every signed key is automatically archived in /etc/ssh/ca_inventory/.

    • List all signed keys: 
      revoke-key --list
    • Revoke a key immediately: 
      sudo revoke-key <label>