SSH Certificates

Overview

SSH certificates provide a fundamentally different approach to device authentication compared to passwords and SSH keys. Instead of distributing public keys to every device and managing authorized_keys files, you deploy a single CA public key to each device and then issue short-lived certificates to users and automation processes on demand.

NetStacks includes a built-in SSH Certificate Authority (CA) in the Controller. The CA signs user certificates with configurable validity periods — 8 hours for interactive sessions and 1 hour for automated tasks by default. Certificates are identity-bound, containing the username and permitted principals, so access is traceable and auditable without managing individual keys on each device.

• Built-in SSH CA — no external PKI infrastructure required
• Short-lived certificates that expire automatically (8hr interactive, 1hr automated)
• Identity binding — certificates contain the user identity and permissions
• No key distribution — devices trust the CA, not individual user keys
• Central revocation capability
• Complete audit trail for every certificate issued

How It Works

Certificate Authority Architecture

The Controller maintains one or more SSH Certificate Authorities, each with an encrypted private key stored in the vault and a public key distributed to managed devices. The CA private key is encrypted with AES-256-GCM and never leaves the Controller. Each CA tracks a serial number counter (next_serial) to ensure every certificate has a unique identifier.

Certificate Signing Flow

1. User requests access — The user initiates a connection to a device through the Terminal or API
2. Controller generates a key pair — A temporary key pair is created for this session
3. CA signs the certificate — The Controller's CA signs the public key with the user's identity, permitted principals, and a validity period
4. Certificate is used for authentication — The signed certificate and temporary private key authenticate the SSH session
5. Certificate expires — After the validity period, the certificate is automatically invalid without any action required

Validity Periods

Identity Binding

Every certificate contains the identity of the user who requested it. This includes the username, the principals (device usernames) they are allowed to authenticate as, and any extensions or restrictions. When a device receives a certificate, it can verify not just that the CA issued it, but who it was issued to and what access was granted.

Trust Model

Devices are configured to trust the CA's public key via the TrustedUserCAKeys directive in sshd_config. Once a device trusts the CA, any valid certificate signed by that CA is accepted for authentication — no per-user key deployment is needed. This dramatically simplifies user onboarding and offboarding.

Step-by-Step Guide

Step 1: Configure the Built-in CA

1. Navigate to Credentials → SSH CA in the Admin UI
2. Click Generate CA
3. Enter a name for the CA (e.g., "Production CA")
4. The Controller generates an Ed25519 CA key pair
5. The private key is encrypted and stored in the vault
6. The public key is displayed for distribution to devices
7. Click Set as Default to use this CA for all certificate signing

Step 2: Deploy CA Public Key to Devices

Copy the CA public key to each managed device and configure the SSH server to trust it:

# Copy the CA public key to the device
scp netstacks-ca.pub admin@core-rtr-01:/etc/ssh/netstacks-ca.pub

# On the device, add to sshd_config
echo "TrustedUserCAKeys /etc/ssh/netstacks-ca.pub" >> /etc/ssh/sshd_config

# Restart SSH daemon
systemctl restart sshd

Step 3: Request a Certificate for Interactive Use

1. Open the Terminal and connect to a device that trusts the CA
2. The Controller automatically issues a certificate with an 8-hour validity period
3. The certificate is used for this session and cached for subsequent connections
4. After 8 hours, a new certificate is issued automatically on the next connection

Step 4: Configure Automated Tasks to Use Short-Lived Certs

1. Navigate to Automation → Scheduled Tasks
2. Create or edit a task
3. In the Authentication section, select SSH Certificate
4. The task will receive a 1-hour certificate each time it executes
5. If the task runs for longer than 1 hour, a new certificate is issued mid-execution

Step 5: Revoke a Certificate

1. Navigate to Credentials → SSH CA → Issued Certificates
2. Find the certificate by serial number or user identity
3. Click Revoke
4. The certificate is added to the revocation list
5. Deploy the updated revocation list to devices using the RevokedKeys directive

Code Examples

Generate and Configure the SSH CA

# Create a new CA via the API
curl -X POST https://controller.example.net/api/ssh-ca \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CA",
    "description": "Primary SSH CA for production network devices"
  }'

# Response:
# {
#   "id": "ca-uuid-here",
#   "name": "Production CA",
#   "public_key_openssh": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...",
#   "is_active": true,
#   "is_default": true,
#   "next_serial": 1
# }

Device-Side sshd_config for Trusting the CA

# /etc/ssh/sshd_config additions for NetStacks CA trust

# Trust the NetStacks CA for user authentication
TrustedUserCAKeys /etc/ssh/netstacks-ca.pub

# Optional: restrict which principals (usernames) certificates can authenticate as
# AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

# Optional: revocation list (update when certificates are revoked)
# RevokedKeys /etc/ssh/revoked_keys

Inspect an SSH Certificate

# View the contents of an SSH certificate
ssh-keygen -Lf /tmp/netstacks-cert.pub

# Example output:
# Type: ssh-ed25519-cert-v01@openssh.com user certificate
# Public key: ED25519-CERT SHA256:xR3gN7...
# Signing CA: ED25519 SHA256:kM4pQ2... (using ssh-ed25519)
# Key ID: "netstacks:jsmith:core-rtr-01"
# Serial: 42
# Valid: from 2025-01-15T08:00:00 to 2025-01-15T16:00:00
# Principals:
#         admin
#         netops
# Critical Options: (none)
# Extensions:
#         permit-pty

Sign a Certificate via API

# Request a signed certificate for a specific user and device
curl -X POST https://controller.example.net/api/ssh-ca/sign \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host",
    "principals": ["admin", "netops"],
    "validity": "8h",
    "key_id": "netstacks:jsmith:interactive"
  }'

# Response includes the signed certificate
# {
#   "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNza...",
#   "serial": 43,
#   "valid_before": "2025-01-15T16:00:00Z"
# }

Questions & Answers

Q: What is an SSH certificate?

A: An SSH certificate is a signed statement from a Certificate Authority (CA) that grants a specific public key the right to authenticate as certain usernames on devices that trust the CA. Unlike raw SSH keys, certificates have an expiration time, identity information, and can be centrally revoked.

Q: How do certificates differ from SSH keys?

A: SSH keys require you to deploy each user's public key to every device they need access to. Certificates require you to deploy the CA public key once per device. After that, any user can authenticate with a certificate signed by the CA, and access is controlled entirely from the Controller. Certificates also expire automatically, while SSH keys are permanent until manually removed.

Q: Why are the default validity periods 8 hours and 1 hour?

A: The 8-hour period for interactive sessions aligns with a standard work shift, allowing an engineer to work all day without needing a new certificate. The 1-hour period for automated tasks follows the principle of least privilege — automated processes should have the shortest possible access window to limit the impact of a compromised certificate.

Q: How do I deploy CA trust to network devices?

A: For Linux/Unix devices, copy the CA public key to the device and add TrustedUserCAKeys /etc/ssh/netstacks-ca.pub to /etc/ssh/sshd_config, then restart sshd. For network appliances, certificate support varies by platform — modern Cisco IOS-XE, Juniper Junos, and Arista EOS support SSH certificates. Check your vendor's documentation for the specific configuration commands.

Q: Can I use certificates with all device types?

A: Not all network devices support SSH certificates. Modern Linux hosts, Cisco IOS-XE 16.x+, Juniper Junos 18.x+, and Arista EOS fully support SSH user certificates. Older platforms may only support password or key authentication. For devices that do not support certificates, use SSH keys or passwords stored in the credential vault.

Q: How does certificate revocation work?

A: When you revoke a certificate in NetStacks, it is added to a revocation list. This list must be deployed to devices via the RevokedKeys directive in sshd_config. However, because NetStacks certificates are short-lived (1–8 hours), revocation is often unnecessary — simply stop issuing new certificates for the user and existing ones expire quickly.

Q: What happens if the CA private key is compromised?

A: Generate a new CA immediately, deploy the new CA public key to all devices, and remove the old CA from the TrustedUserCAKeys configuration. All certificates signed by the compromised CA should be treated as untrusted. Because certificates are short-lived, the exposure window is inherently limited.

Troubleshooting

Certificate expired errors

If a connection fails with "certificate has expired":

• The certificate's validity period has passed — request a new one by reconnecting
• Check if the Controller's clock is accurate (certificates use UTC timestamps)
• For automated tasks, ensure the task duration does not exceed the certificate TTL

CA not trusted on device

If authentication fails with "certificate not recognized" or similar:

• Verify the CA public key is correctly installed: cat /etc/ssh/netstacks-ca.pub
• Confirm TrustedUserCAKeys is set in sshd_config and points to the correct file
• Check that sshd was restarted after the configuration change
• Ensure the certificate was signed by the correct CA (organizations may have multiple CAs)

# Verify the CA key is in place and sshd recognizes it
sshd -T | grep trustedusercakeys
# Expected: trustedusercakeys /etc/ssh/netstacks-ca.pub

# Test certificate authentication manually
ssh -o CertificateFile=/tmp/netstacks-cert.pub \
    -i /tmp/netstacks-key \
    admin@core-rtr-01.dc1.example.net

Identity mismatch

If the device rejects the certificate because the principal does not match:

• Verify the certificate includes the correct principal (username) for the target device: ssh-keygen -Lf cert.pub and check the Principals list
• If using AuthorizedPrincipalsFile, ensure the device-side file includes the principal name from the certificate

Clock skew between Controller and devices

SSH certificates use UTC timestamps for validity windows. If the Controller's clock and the device's clock differ by more than a few minutes, certificates may be rejected as "not yet valid" or "expired" even though the validity period should be active.

• Configure NTP on both the Controller host and all managed devices
• Verify time synchronization: timedatectl status on Linux, show clock on network devices
• Certificates include a small grace period, but drifts beyond 5 minutes will cause failures

Related Features

Explore related credential and automation features:

• Credential Vault — How the vault encrypts CA private keys and all other credentials
• SSH Passwords & Keys — Alternative authentication methods for devices that do not support certificates
• Adding Devices — Configure devices to use certificate-based authentication
• Scheduled Tasks — Automate network tasks with short-lived 1-hour certificates
• Audit Logs — Track every certificate issuance and usage event