Guide SSH server administration

Palo Alto Networks SSH Manager · vSSH CLI

SSH server administration

This guide is for the people who run the hosts users log in to. It covers making an OpenSSH server trust certificates from SSH Manager, mapping certificate identities to local accounts, and letting clients trust host certificates.

The parts of certificate trust

Four pieces make certificate-based SSH work on a host:

• TrustedUserCAKeys in sshd_config points to a file of CA public keys. sshd accepts any user certificate signed by one of those keys.
• AuthorizedPrincipals decides which certificate principals may log in as which local user.
• Host certificates (optional) let clients verify the host without a trust-on-first-use prompt.
• @cert-authority lines in a client's known_hosts tell the client which CA signs host certificates.

You configure the first two on the server. The last two are for host-key trust, covered at the end.

Inspect current trust

Start by seeing what the host trusts now.

sudo vssh openssh server show

It prints the config file and owner, the TrustedUserCAKeys file and the fingerprints of the CA keys in it, the AuthorizedPrincipals settings, and host keys and certificates. Run it before and after any change to confirm the result. See openssh.

Trust the CA

Retrieve the CA key and place it yourself. This works on any platform.

vssh service ca retrieve \
  --use-to-configure openssh_server \
  --out-file /etc/ssh/trusted_user_ca_keys \
  --template "Users - Web Admins"

Then add the line to sshd_config and reload:

TrustedUserCAKeys /etc/ssh/trusted_user_ca_keys

sudo sshd -t && sudo systemctl reload sshd

sshd -t checks the config before you reload, so a typo does not lock you out. Details are in Configure OpenSSH server for client authentication.

Map principals to accounts

A certificate lists one or more principals (usernames it is valid for). AuthorizedPrincipals controls which of those may become which local account. Use it to keep certificate identities separate from local usernames.

Example: allow anyone whose certificate carries the web-admins principal to log in as the local deploy user. In sshd_config:

AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

Then create /etc/ssh/auth_principals/deploy containing:

web-admins

Now a user presenting a valid certificate with the web-admins principal can log in as deploy, and nothing else grants that access. Reload sshd after the change.

Let clients trust host certificates

The steps above let a host verify users. You can also let users verify the host, which removes the "authenticity of host cannot be established" prompt and protects against a spoofed server.

Produce a known_hosts entry that trusts host certificates from the CA:

vssh service ca retrieve \
  --use-to-configure openssh_client \
  --out-file ~/.ssh/known_hosts

This writes a line beginning with @cert-authority *. Distribute it to clients (or add it to the system-wide /etc/ssh/ssh_known_hosts) so any host presenting a valid host certificate is trusted without a prompt.

A rollout checklist

• Inspect the host first with vssh openssh server show.
• Configure trust with service ca retrieve and a sshd_config edit.
• Validate with sshd -t before every reload.
• Restrict logins with AuthorizedPrincipals rather than trusting every principal.
• Distribute an @cert-authority entry so clients trust host certificates.
• Confirm the result with vssh openssh server show.

Related pages

• openssh
• service
• Configure OpenSSH server for client authentication
• Retrieving the public keys of your SSH CAs
• Securing SSH access