SSH User Certificates

1. The Problem User Certificates Solve

Managing SSH access at scale with traditional keys is painful:

2. How User Certificates Work

The flow is straightforward:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    User     │     │     CA      │     │   Server    │
│  (has key)  │────▶│  (signs)    │     │ (trusts CA) │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       │  1. Send pub key  │                   │
       │──────────────────▶│                   │
       │                   │                   │
       │  2. Get cert back │                   │
       │◀──────────────────│                   │
       │                   │                   │
       │  3. Connect with cert                 │
       │──────────────────────────────────────▶│
       │                   │                   │
       │                   │  4. Verify cert   │
       │                   │     against CA    │

What's happening:

1. User generates a normal key pair (nothing special required)
2. CA signs the public key → creates a certificate
3. Server trusts the CA, not individual keys
4. Certificate contains: identity, allowed usernames (principals), validity period, and restrictions

→ See our SSH Certificate Anatomy demo to explore certificate fields interactively.

3. Anatomy of a User Certificate

User certificates contain specific fields that control access:

The principals field is particularly important—it determines which usernames the certificate holder can log in as.

4. Signing a User Certificate

Here's how to sign a user's public key:

ssh-keygen -s /path/to/user_ca \
  -I "patrick@example.com-20250114" \
  -n patrick,admin \
  -V +1d \
  ~/.ssh/id_ed25519.pub

Flag breakdown:

Output: Creates ~/.ssh/id_ed25519-cert.pub alongside the original key.

Verify the certificate:

ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub

This displays all certificate details including principals, validity, and extensions.

5. Server Configuration

Servers need two things to trust user certificates:

# /etc/ssh/sshd_config

# Trust certificates signed by this CA
TrustedUserCAKeys /etc/ssh/user_ca.pub

# Map principals to local users (optional but recommended)
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

Restart sshd after changes:

systemctl restart sshd

6. Principals: The Access Control Layer

Principals are where SSH certificates become powerful.

Create /etc/ssh/auth_principals/root:

admin
emergency-access

Now anyone with the admin or emergency-access principal in their certificate can SSH as root.

Example directory structure:

/etc/ssh/auth_principals/
├── root          # Contains: admin, emergency-access
├── deploy        # Contains: deploy, ci-cd
├── patrick       # Contains: patrick, developer
└── monitoring    # Contains: monitoring, observability

This enables role-based access control:

• Issue certificates with role principals (admin, developer, deploy)
• Servers define which roles can access which accounts
• No authorized_keys changes needed when people join or leave

7. Certificate Extensions and Restrictions

Fine-grained control over what certificate holders can do:

Extensions (permissions granted):

Critical Options (restrictions):

Example: Locked-down CI/CD certificate

ssh-keygen -s /path/to/user_ca \
  -I "github-actions-deploy" \
  -n deploy \
  -V +1h \
  -O source-address="192.30.252.0/22" \
  -O force-command="/opt/deploy/run.sh" \
  -O no-port-forwarding \
  -O no-pty \
  deploy_key.pub

This certificate:

• Is only valid for 1 hour
• Can ONLY connect from GitHub's IP range
• Can ONLY run the deploy script
• Cannot get a shell or create tunnels

8. Short-Lived Certificates: The Best Practice

Why 1-24 hour validity is recommended:

Solutions:

1. Integrate with SSO - Sign certificate at login
2. Use a signing service - HashiCorp Vault, step-ca, Venafi
3. Wrapper scripts - Auto-refresh before expiration

Example with HashiCorp Vault:

# User authenticates to Vault, gets signed certificate
vault write -field=signed_key ssh/sign/developer \
  public_key=@~/.ssh/id_ed25519.pub > ~/.ssh/id_ed25519-cert.pub

# Certificate valid for configured TTL (e.g., 8 hours)
# Transparent to user - just works until end of workday

9. Migration Strategy

Moving from authorized_keys to certificates doesn't have to be big-bang.

10. Troubleshooting

Common issues and their solutions:

Debug command:

ssh -vvv user@server 2>&1 | grep -i cert

Look for:

• Offering public key: ... ED25519-CERT - Client is trying certificate
• Server accepts key: ... ED25519-CERT - Success!
• Certificate invalid: - Check the specific error message

FAQ

Related Guides