OpenSSH Certificate Cheatsheet

Quick Reference

Create a Certificate Authority

An OpenSSH certificate authority is an SSH key pair used to sign other public keys.

Create a User CA

ssh-keygen -t ed25519 -f user_ca -C "SSH User CA"

Creates:

user_ca
user_ca.pub

user_ca is the CA private key.

user_ca.pub is the CA public key distributed to systems that trust certificates signed by this authority.

Protect the CA private key. Compromise of this key can allow unauthorized certificates to be issued.

Create a Separate Host CA

ssh-keygen -t ed25519 -f host_ca -C "SSH Host CA"

Creates:

host_ca
host_ca.pub

Use separate user and host CA keys in production to maintain distinct trust boundaries.

Display the CA Public Key Fingerprint

ssh-keygen -lf user_ca.pub

The fingerprint can be used to verify the identity of the CA public key during distribution.

Generate User Keys

Generate an Ed25519 key pair for a user:

ssh-keygen -t ed25519 -f user_key -C "alice@example.com"

Creates:

user_key
user_key.pub

The private key remains with the user.

Only the public key is submitted to the CA for signing.

The CA does not need access to the user's private key.

Sign User Certificates

Basic User Certificate

ssh-keygen -s user_ca \
  -I alice-001 \
  -n alice \
  -V +1h \
  user_key.pub

This creates:

user_key-cert.pub

Options:

Sign for Multiple Principals

ssh-keygen -s user_ca \
  -I alice-002 \
  -n alice,deploy,readonly \
  -V +1h \
  user_key.pub

The certificate contains three principals:

alice
deploy
readonly

The target server determines which principals are authorized for the account being accessed.

A principal appearing in the certificate does not automatically grant access to a corresponding operating system account.

Sign with a Serial Number

ssh-keygen -s user_ca \
  -I alice-003 \
  -z 1001 \
  -n alice \
  -V +1h \
  user_key.pub

The -z option sets the certificate serial number.

Serial numbers can support issuance tracking and certificate revocation.

Use a controlled, unique serial allocation process for certificates issued by the same CA.

Restrict Source Addresses

ssh-keygen -s user_ca \
  -I alice-office \
  -n alice \
  -V +1h \
  -O source-address=192.0.2.0/24 \
  user_key.pub

The source-address critical option restricts the client source addresses from which the certificate may be accepted.

This is an additional restriction, not a replacement for network security controls.

Disable PTY Allocation

ssh-keygen -s user_ca \
  -I alice-no-pty \
  -n alice \
  -V +1h \
  -O clear \
  -O permit-port-forwarding \
  user_key.pub

-O clear removes the default certificate permissions.

The example then selectively restores port forwarding without permitting PTY allocation.

Certificate extensions interact with server configuration. An extension permitting a feature does not override a server-side restriction that disables it.

Configure SSH Servers

Install the Trusted User CA

Copy the CA public key to the server:

sudo install -m 0644 user_ca.pub /etc/ssh/user_ca.pub

Configure /etc/ssh/sshd_config:

TrustedUserCAKeys /etc/ssh/user_ca.pub

This tells OpenSSH to trust user certificates signed by the specified CA.

It does not automatically authorize every principal or account.

Validate Configuration

sudo sshd -t

If validation succeeds, reload the SSH service using the appropriate command for the operating system.

For example, on systems using a service named sshd:

sudo systemctl reload sshd

On systems where the service is named ssh, use the corresponding service name.

Do not close an existing administrative session until certificate authentication has been tested successfully.

Certificate Principals

Principals define identities or roles that a certificate may represent.

The server must determine whether a certificate principal is authorized for the target account.

Configure an Authorized Principals File

In sshd_config:

TrustedUserCAKeys /etc/ssh/user_ca.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

For the local account deploy, create:

/etc/ssh/auth_principals/deploy

Example contents:

production-deploy
release-engineer

A certificate containing either authorized principal may satisfy this part of the authorization policy for the deploy account, subject to the remaining SSH authentication checks and restrictions.

Sign a Certificate for a Role

ssh-keygen -s user_ca \
  -I alice-deploy \
  -n production-deploy \
  -V +15m \
  user_key.pub

The user can attempt to connect as:

ssh -i user_key deploy@server.example.com

The server evaluates whether the production-deploy principal is authorized for the deploy account.

Dynamic Principal Authorization

OpenSSH also supports AuthorizedPrincipalsCommand.

This allows authorized principals to be obtained through an external command rather than a static file.

The command and its execution identity must be configured securely.

Dynamic authorization can support integration with centralized identity and access management systems.

Connect Using Certificates

Automatic Certificate Discovery

If the private key is:

~/.ssh/user_key

And the certificate is:

~/.ssh/user_key-cert.pub

OpenSSH normally discovers the certificate automatically when the corresponding identity is used.

Connect with:

ssh -i ~/.ssh/user_key alice@server.example.com

Explicit Certificate Configuration

Add to ~/.ssh/config:

Host production
    HostName server.example.com
    User deploy
    IdentityFile ~/.ssh/user_key
    CertificateFile ~/.ssh/user_key-cert.pub
    IdentitiesOnly yes

Connect with:

ssh production

Debug Certificate Authentication

ssh -vvv -i ~/.ssh/user_key deploy@server.example.com

Verbose output helps identify which identities and certificates the client offers and how authentication proceeds.

Host Certificates

Host certificates allow SSH clients to authenticate servers through a trusted host CA.

This is particularly useful when servers are frequently provisioned or replaced.

Generate a Host CA

ssh-keygen -t ed25519 -f host_ca -C "SSH Host CA"

Sign a Host Public Key

ssh-keygen -s host_ca \
  -I server01 \
  -h \
  -n server.example.com,server01.example.com \
  -V +52w \
  ssh_host_ed25519_key.pub

The -h option specifies a host certificate.

The -n option defines valid hostnames or host identities.

The validity period is illustrative. Production host certificate lifetimes should reflect the organization's issuance and renewal capabilities.

Configure the SSH Server

In sshd_config:

HostKey /etc/ssh/ssh_host_ed25519_key
HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

The host certificate must correspond to the configured host private key.

Trust the Host CA on Clients

Add an entry to the client's known_hosts file:

@cert-authority *.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...

Replace the abbreviated public key with the complete contents of host_ca.pub.

The hostname pattern defines where the CA is trusted.

The CA key should be distributed through a trusted administrative process.

Do not disable SSH host verification as a substitute for configuring host CA trust.

Inspect Certificates

Display Certificate Details

ssh-keygen -Lf user_key-cert.pub

The output includes information such as:

• Certificate type.
• Signing CA.
• Key identifier.
• Serial number.
• Valid principals.
• Validity interval.
• Critical options.
• Extensions.

Inspect a Host Certificate

ssh-keygen -Lf ssh_host_ed25519_key-cert.pub

Display a Public Key Fingerprint

ssh-keygen -lf user_key.pub

Display a Certificate Fingerprint

ssh-keygen -lf user_key-cert.pub

Certificate inspection is useful when diagnosing principal mismatches, expired credentials and unexpected certificate options.

Certificate Validity

OpenSSH certificates include a validity interval.

The -V option controls when the certificate becomes valid and when it expires.

Fifteen-Minute Certificate

ssh-keygen -s user_ca -I short-lived -n alice -V +15m user_key.pub

One-Hour Certificate

ssh-keygen -s user_ca -I hourly -n alice -V +1h user_key.pub

One-Day Certificate

ssh-keygen -s user_ca -I daily -n alice -V +1d user_key.pub

Explicit Validity Window

ssh-keygen -s user_ca \
  -I scheduled \
  -n alice \
  -V 20261023090000:20261023170000 \
  user_key.pub

The explicit timestamps above are illustrative.

OpenSSH interprets these timestamps according to the signing environment's time settings.

Validity and Existing Sessions

Certificate expiration prevents the certificate from being accepted for new authentication after its validity period.

It does not automatically terminate SSH sessions that were established while the certificate was valid.

Organizations requiring immediate session termination must implement additional controls.

Clock Synchronization

Certificate validation depends on time.

Ensure clients, servers and certificate issuance systems maintain reliable clock synchronization.

Significant clock differences can cause otherwise legitimate certificates to be rejected.

Certificate Revocation

OpenSSH supports Key Revocation Lists, or KRLs.

KRLs can identify public keys and certificates that should no longer be accepted.

Create a Revocation List

ssh-keygen -k -f revoked_keys.krl user_key-cert.pub

This creates a KRL containing a revocation for the specified certificate.

Check Whether a Certificate Is Revoked

ssh-keygen -Q -f revoked_keys.krl user_key-cert.pub

The command reports whether the supplied certificate is revoked by the KRL.

Configure Server-Side Revocation

In sshd_config:

RevokedKeys /etc/ssh/revoked_keys.krl

The revocation file must be readable by the SSH daemon.

If the configured revocation file cannot be read, OpenSSH may refuse public-key authentication.

Revocation at Scale

A KRL must be distributed to the systems expected to enforce it.

Short-lived certificates reduce the period during which compromised credentials remain usable for new authentication, but they do not provide immediate revocation.

For production deployments, establish a clear process for revoking certificates, updating authorization and responding to compromised CA keys.

Troubleshooting OpenSSH Certificates

Permission Denied (publickey)

Possible causes:

• The server does not trust the issuing CA.
• The certificate has expired or is not yet valid.
• The certificate principal is not authorized.
• The client is not presenting the expected certificate.
• The private key does not match the certificate.
• Server configuration or file permissions prevent authentication.
• A certificate restriction or server policy rejects the connection.

Start with:

ssh -vvv -i user_key alice@server.example.com

Then inspect the certificate:

ssh-keygen -Lf user_key-cert.pub

Certificate Is Not Offered

Confirm that the certificate filename matches the private key filename with the -cert.pub suffix.

Alternatively, configure CertificateFile explicitly.

Inspect effective client configuration with:

ssh -G server.example.com

Certificate Principal Not Authorized

Inspect the certificate:

ssh-keygen -Lf user_key-cert.pub

Check the server's AuthorizedPrincipalsFile, AuthorizedPrincipalsCommand or applicable account principal-matching configuration.

The certificate principal must be acceptable for the account being accessed.

Certificate Expired

Inspect the validity interval:

ssh-keygen -Lf user_key-cert.pub

Request or issue a new certificate after performing the appropriate identity and authorization checks.

Do not simply increase certificate lifetimes to avoid implementing renewal.

Unknown Certificate Authority

Verify that the server trusts the correct user CA public key.

Check:

TrustedUserCAKeys

For host certificates, verify that the client trusts the correct host CA through its known_hosts configuration.

Host Certificate Rejected

Check:

• Host certificate validity.
• Hostname principals.
• Trusted host CA.
• Host certificate and private key correspondence.
• Host certificate configuration on the server.

Use verbose client diagnostics:

ssh -vvv server.example.com

Server-Side Diagnostics

Inspect SSH server logs using the operating system's logging facilities.

On a system using systemd and a service named sshd:

sudo journalctl -u sshd

Service names and logging locations vary by operating system.

For advanced troubleshooting, use an isolated test SSH daemon with an appropriate debug configuration rather than disrupting a production SSH service.

ssh-keygen Certificate Options Reference

Common Certificate Options

Certificate permissions and server configuration are evaluated together.

A certificate extension does not override a server-side restriction.

Consult the installed OpenSSH manual for options supported by the deployed version.

Production Best Practices

OpenSSH certificates provide a strong foundation for scalable SSH authentication, but secure deployment requires more than generating a CA key pair.

Managing Certificates at Scale

The commands in this cheatsheet demonstrate the native OpenSSH certificate mechanisms.

For small environments, manual certificate signing may be sufficient.

At larger scales, the challenge shifts from cryptography to operations: authenticating users, approving access, issuing certificates, maintaining policy and handling credential lifecycle events.

SSH Teams builds on OpenSSH certificate authentication to provide managed, short-lived SSH access using existing SSH clients and servers.

It is designed to reduce reliance on permanently authorized individual SSH keys without requiring a proprietary SSH protocol or mandatory bastion host.

Explore SSH Teams

https://jadaptive.com/sshteam

Further Reading

OpenSSH Certificates: The Complete Guide to SSH Certificate Authentication

Understand the OpenSSH certificate trust model, certificate authorities, user and host certificates, principals, short-lived credentials and certificate management.

/guides/openssh-certificates/

OpenSSH Manual Pages

Consult the official OpenSSH documentation for version-specific options and configuration behavior.

• ssh-keygen(1)
• ssh(1)
• ssh_config(5)
• sshd_config(5)