OpenSSH certificate principals define login authority

An OpenSSH user certificate is a signed statement about a public key, an identity, and a set of principals and options. The certificate can make key distribution easier, but it moves critical authorization decisions into the signing policy and the server's principal map. A server that trusts a certificate authority without constraining principals has delegated more authority than its operators may realize.

The manual for ssh-keygen describes a certificate as a public key, identity information, principal names, and options signed by a certification authority. The server manual explains that TrustedUserCAKeys establishes which CAs are trusted for user authentication. AuthorizedPrincipalsFile then limits which principal names are accepted, but that file is only consulted for CAs trusted through TrustedUserCAKeys; it is not consulted for CAs trusted through an authorized_keys entry in the same way.

Separate identity from authority

The certificate's key ID is not the same as an accepted Unix account. The principal list controls which account names the certificate may authenticate as. A signing service should issue the narrowest principal set needed for a workload or user role. A broad principal such as admin or a wildcard may be convenient during an incident, but it should not be the default for routine issuance.

Use the server's principal policy to map principals to accounts deliberately. If two environments use the same CA, the server-side policy must distinguish them. A development certificate should not become a production login because the same principal string exists in both systems. Scope CA trust by host or environment where the deployment supports it.

Keep the certificate's validity period short enough to limit a leaked private key. Do not assume that short validity replaces revocation. OpenSSH supports key revocation lists through ssh-keygen, and operators need a tested path to distribute a KRL or otherwise disable a compromised principal. Record the issuer, serial, key ID, principal set, and issuance time in the access log.

Treat critical options as compatibility contracts

OpenSSH certificates can carry options that restrict or extend how a certified key is used. A critical option that the server does not recognize causes the server to refuse authorization. That behavior is useful because an unknown restriction cannot be silently ignored. It also means a certificate with a new critical option may fail across an older fleet after an upgrade or partial rollout.

Review the options accepted by every server version before changing the certificate issuance policy. Test with the exact OpenSSH version and configuration used in production. A certificate that works on an administrator's laptop but fails on an appliance or bastion is not a completed deployment.

Do not treat the certificate's comment or key ID as a reliable unique identity. Include a stable issuer-side identifier in records, but make authorization depend on the signed principal and the server policy. If a workflow uses a certificate to run a command, separately restrict the account shell and the allowed commands where the environment supports it.

Audit the signing path

The CA private key is a high-value secret. Keep it offline or in a controlled signing service, require strong operator authentication, and log each signing decision. Separate account authentication from certificate issuance for automated workloads. An automation system that can mint an arbitrary principal is effectively an administrator of every host that trusts the CA.

Review the server configuration for TrustedUserCAKeys, AuthorizedPrincipalsFile, AuthorizedPrincipalsCommand, AuthorizedKeysCommand, and any per-key restrictions. Test the ordering and fallback behavior. A missing principals file, a wrong path, or a configuration reload failure can change who is accepted without changing the certificate.

Monitor certificate authentication by CA, principal, server, and result. Alert on a new principal for a privileged account, an unexpected issuer, repeated authentication failures, or a certificate used after its expected retirement. Do not collect private keys or full certificates in application logs when a key ID and serial are enough.

Test revocation and rollover

Issue a short-lived test certificate and a revoked test certificate. Verify acceptance and rejection on each target host. Replace the CA key on a schedule and keep the old CA trusted only for the documented overlap. Remove the old trust when all certificates have expired.

Certificates make SSH authorization programmable. That is their value and their risk. The safe deployment states which CA may speak for which principal, which server may trust it, how a certificate is revoked, and who can sign. The certificate signature proves who issued the statement. The server policy decides whether the statement is allowed to log in.

References

• OpenBSD, ssh-keygen(1) manual page
• OpenBSD, sshd_config(5) manual page