There are a growing number of articles around which explain about the setup and use of SSH certificates, likethe Wikibooks Certificate-based Authentication cookbook.

This article goes into detail where the others stop: Most articles describe how the principal in the certificate (-n argument tossh-keygen when signing the user's key) needs to be set to the name of the user on the target host. There are however many more options that can be used on the server as well as in the certificate to manage access.

Advanced principals

By default, OpenSSH requires the name of the user logging in to be among the principals in the certificate. That is, if certificate based authentication is used, 'bob' needs to be in the list of principals to be able to:

$ssh bob@server01.example.com

Next to this default, servers have 3 mechanisms for setting up more advanced authentication setups using principals.

AuthorizedPrincipalsFile

Using this directive, a global or per-user list of principals can be configured for access to the server. That is to say that if the server is configured with anauthorized_principals file:

# /etc/ssh/sshd_config# for a global configuration:AuthorizedPrincipalsFile /etc/ssh/authorized_principals# for per-user configuration, relative to $HOME:AuthorizedPrincipalsFile .ssh/authorized_principals

which contains

access-any-user

Then, if bob has a certificate namedany_bob with theaccess-any-user principal, he can authenticate to the server asany user:

bob@client$ssh-oCertificateFile=any_bob-cert.pub-i any_bob sshd@server01.example.comThis account is currently not available.

The responseThis account is currently not available. indicates the authentication was successful and thenologin shell was executed.

Remark: Using the AuthorizedPrincipalsFile directive disables the default behaviour to accept certificates listing the target username among the principals.

Per-principal command restriction

The authorized principals file supports the same options as the authorized keys file does. Assumingserver01 has a user namedwacky with a regular login shell, if we change/etc/ssh/authorized_principals to contain:

command="/usr/bin/date" access-any-user

Then:

bob@client$ssh-oCertificateFile=any_bob-cert.pub-i any_bob wacky@server01.example.comSat Mar 30 15:29:44 CET 2024

The source from which is being connected can be restricted using this method using thefrom= option. See for more options the documentation of theauthorized_keys file.

Certificate based restrictions

Certificates can come with their own restrictions, independent of the restrictions specified by the server. The ones to highlight here areforce-command andsource-address. In case aforce-command restriction in the certificate conflicts with thecommand restriction in the authorized principals file (i.e. they are not the same string), the mechanism is considered a mismatch (and the next mechanism - e.g. password based - is tried).

Certificate identity (-I) and sequence numbers (-z)

Although most sources hostnames for host certificates and<user>@<host> for user certificates, these can be any string value. They serve two purposes:

1. To identify the certificate that was presented during authentication, in the system logs (syslog or journalctl); and
2. To identify the certificate in the Key Revocation List (KRL)

Many articles don't specify a sequence number, but specifying one is definitely desirable to be able to revoke specific certificates.

Dynamic authorization of principals

The configuration optionAuthorizedPrincipalsCommand is a global setting which may be used to configure dynamic authorized principal list generation using an external command:

AuthorizedPrincipalsCommand /usr/local/bin/dynamic-principals "%u %s"AuthorizedPrincipalsCommandUser dedicateduser

Thesshd_config man page lists the supported tokens. Each returned line on standard output must conform to the same requirements as the lines from a static authorized principals file.

Prerequisites

To authenticate servers to clients:

• A host certificate authority (CA) key pair

• A host CA'spublic keydeployed to clients; configured using the@cert-authority known_hosts-marker either through

  • global configuration (/etc/ssh/ssh_known_hosts)
  • user specific configuration (~/.ssh/authorized_keys)

  In case of a user-specified CA in authorized_keys, a principals list needs to be specified with theprincipals= option.

To authenticate clients to servers:

• A client CA key pair
• A client CA'spublic keydeployed to servers; configured through/etc/ssh/sshd_config using theTrustedUserCAKeys configuration directive

Note: neither the client CA nor the host CA require a certificate of their own.

Conclusion

Although by default the target user name must be among the principals in the certificate, this is not a hard requirement: principals can be listed statically or dynamically on the server resulting in a successful authentication when a non-empty intersection between the server and certificate principals exists. This allows for a setup where principals define roles rather than login accounts.

Using the concepts presented in this article (especially the - certificate-based - command restriction) in combination with command restrictions in e.g.sudo opens opportunities for fine-grained control over user and admin access.