SSH Certificate Authentication on macOS: Setup Guide

SSH certificate authentication on macOS lets you log into remote servers using a signed public key instead of a password or a manually managed key list. You generate a key pair, have a certificate authority (CA) sign the public key, and then configure your Mac and the server to trust that CA. This guide walks through the entire process, from generating keys to troubleshooting common issues.

Why Use SSH Certificates Instead of Plain Keys?

Standard SSH key authentication works by copying your public key to each server’s ~/.ssh/authorized_keys file. This becomes unwieldy when you manage many servers or users: adding a new user means touching every machine, and revoking access means removing keys everywhere. SSH certificates solve this by introducing a certificate authority (CA). The CA signs your public key, producing a certificate that contains your identity, a validity period, and optional restrictions. Servers only need to trust the CA’s public key. When you connect, the server verifies your certificate against the CA’s key, so you never need to edit authorized_keys again. This approach scales to hundreds of servers and users, and it allows short-lived certificates that automatically expire, improving security.

Prerequisites: What You Need on Your Mac

Before you start, ensure your Mac meets these requirements:

macOS with OpenSSH (comes preinstalled on all modern versions).
Access to a certificate authority. This can be a dedicated CA server, a tool like Vault or step-ca, or simply a separate key pair you designate as the CA.
SSH client configuration file at ~/.ssh/config (you may need to create it).
Root or sudo access on the remote server to configure the CA trust.

You do not need any additional software on your Mac; everything is built into the ssh command.

Step-by-Step: Generate a Key Pair and Get It Signed

Generate a key pair (if you don’t already have one): ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "your_email@example.com". This creates a private key (id_ed25519) and a public key (id_ed25519.pub).
Create a CA key pair (if you don’t have one). On your CA machine, run: ssh-keygen -t ed25519 -f ~/.ssh/ca_key -C "my-ca". The public key (ca_key.pub) will be trusted by servers.
Sign the user’s public key. On the CA machine, run: ssh-keygen -s ca_key -I user_id -n username -V +52w ~/.ssh/id_ed25519.pub. This produces a certificate file id_ed25519-cert.pub. The -I option is a key ID (any string), -n specifies the username(s) allowed, and -V sets validity (here, 52 weeks).
Copy the certificate to your Mac (if generated elsewhere) and place it next to your private key, e.g., ~/.ssh/id_ed25519-cert.pub. The SSH client automatically looks for a certificate with the same base name as the private key and a -cert.pub suffix.

Now your Mac has a signed certificate. The private key remains on your Mac, never leaving it.

Configuring the Server to Trust Your CA

The remote server must be told to trust your CA’s public key. Edit /etc/ssh/sshd_config on the server and add:

TrustedUserCAKeys /etc/ssh/ca_key.pub

Then copy the CA’s public key (ca_key.pub) to /etc/ssh/ca_key.pub on the server and restart SSH: sudo systemctl restart sshd (or sudo service ssh restart on older systems). Now any certificate signed by that CA will be accepted, provided the username in the certificate matches the account you’re logging into.

You can also restrict which usernames are allowed by adding AuthorizedPrincipalsFile and AuthorizedPrincipalsCommand options, but for a basic setup, the above is enough.

Connecting from Your Mac

Once the server trusts the CA, you can connect normally:

ssh username@server.example.com

If your private key is not in the default location, specify it with -i ~/.ssh/id_ed25519. The SSH client will automatically present the certificate if it finds id_ed25519-cert.pub next to it. You can also define per-host settings in ~/.ssh/config:

Host myserver
    HostName server.example.com
    User username
    IdentityFile ~/.ssh/id_ed25519
    CertificateFile ~/.ssh/id_ed25519-cert.pub

Now ssh myserver will use the certificate.

Common Problems and How to Fix Them

Certificate not being used: Ensure the certificate file is named exactly id_ed25519-cert.pub (or matches your key’s base name) and is in the same directory. Check with ssh -v to see if the client offers the certificate.
Permission denied: The server may not trust the CA. Verify the TrustedUserCAKeys path and that the CA public key is correct. Also confirm the username in the certificate matches the remote account.
Certificate expired: Check the validity period with ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub. If expired, get a new certificate.
Private key permissions: SSH requires private keys to be readable only by your user. Run chmod 600 ~/.ssh/id_ed25519.
Certificate not found: If you specified CertificateFile in config, make sure the path is correct. Otherwise, the client looks for id_ed25519-cert.pub automatically.

Security Considerations and Best Practices

Certificates are only as secure as the CA key. Protect the CA private key with strong permissions and store it offline if possible. Use short certificate lifetimes (e.g., 1 week) and renew them periodically, which reduces the risk if a key is compromised. Always use a passphrase on your private key to protect it at rest. Consider using an SSH agent to avoid typing the passphrase repeatedly. Also, never share your private key or certificate; they are tied to your identity.

Alternatives to SSH Certificates

If certificates seem overkill, alternatives include:

Standard key-based auth: Simple but requires managing authorized_keys on each server.
SSH keys with a central management tool: Tools like Ansible can push keys to many servers, but they still use plain keys.
Hardware security keys (e.g., YubiKey): Store your private key on a hardware token, but you still need to distribute public keys.
SSH config shortcuts: Not an authentication method, but reduces typing.

Certificates are the most scalable and secure option for larger environments.

Frequently Asked Questions

How do I check if my certificate is valid?

Run ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub to display the certificate’s contents, including validity period and allowed principals. You can also use ssh -v to see which authentication methods are offered during a connection.

Can I use the same certificate for multiple servers?

Yes, as long as all servers trust the same CA and the username in the certificate matches the account on each server. You can also use a wildcard principal like * to allow any username, but that is less secure.

What happens when the certificate expires?

You will no longer be able to authenticate. You need to get a new certificate signed by the CA. This is a feature: it forces periodic re-authentication and reduces the window for misuse.

Can I revoke a certificate?

Yes, but it requires additional setup. You can use a Certificate Revocation List (CRL) or an Online Certificate Status Protocol (OCSP) responder, but these are not built into OpenSSH by default. Simpler is to use short validity periods and re-issue frequently.

Do I need to install anything on my Mac?

No, OpenSSH is preinstalled on macOS. You only need the ssh-keygen and ssh commands, which are already available.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →