Skip to content

SSH Certificate Authority

Watchgrid includes a built-in SSH Certificate Authority (CA) that issues short-lived certificates — eliminating the need to manage authorized_keys files across your fleet.

How It Works

Instead of copying SSH public keys to every device, Watchgrid signs your SSH key with a trusted CA certificate. Every provisioned device already trusts this CA, so your signed certificate grants access automatically.

Certificate Type Validity Use Case
User certificates 24 hours SSH into devices
Host certificates 365 days Devices prove their identity

Security Features

  • Short-lived certificates — user certs expire after 24 hours, limiting exposure
  • Source address restriction — user certs are locked to the WireGuard subnet (100.64.0.0/10)
  • Certificate revocation — revoked certs are tracked in a CRL that devices check on each heartbeat
  • Full audit trail — every certificate issuance is logged

Requesting a User Certificate

  1. Go to System → PKI / SSH CA
  2. In the Request User Certificate section:
  3. Paste your SSH public key (e.g., contents of ~/.ssh/id_ed25519.pub)
  4. Optionally enter a username
  5. Click Request Certificate
  6. Click Download to save the signed certificate file (*-cert.pub)
  7. Place the certificate alongside your private key:
# If your key is ~/.ssh/id_ed25519, save the cert as:
~/.ssh/id_ed25519-cert.pub

# Then SSH normally — the cert is used automatically
ssh admin@pi-sensor-1.wg

The certificate is valid for 24 hours. After that, request a new one.

CA Status

The PKI page displays:

  • CA operational status — whether the CA keys are loaded and functional
  • Total certificates issued
  • Active / Expired / Revoked counts
  • User vs. Host certificate breakdown

Certificate Audit

A table at the bottom lists all issued certificates:

Column Description
Type User or Host
Username The principal on the certificate
Serial Unique certificate serial number
Issued When the certificate was signed
Expiry When the certificate expires
Status Active (green), Expired (gray), or Revoked (red)

Host Certificates

Host certificates are issued automatically during device provisioning. They prove the device's identity to connecting SSH clients, preventing man-in-the-middle attacks.

To trust host certificates on your workstation, add this to ~/.ssh/known_hosts:

@cert-authority *.wg <contents of ca_host_key.pub>

The CA host public key is available at:

http://YOUR_SERVER:8080/api/ssh/ca-host-key

CA Key Storage

CA keys are stored in a Docker volume (watchgrid-ssh-ca) mapped to /etc/watchgrid/:

  • ca_user_key / ca_user_key.pub — signs user certificates
  • ca_host_key / ca_host_key.pub — signs host certificates

Back up your CA keys

Losing the CA private keys invalidates all issued host certificates. Every device would need to be reprovisioned. Back up the watchgrid-ssh-ca volume in production.