Skip to content
ssoossh

Hosts overview

For whoever administers the machines people log in to. A target host needs one thing to accept ssoossh certificates over SSH, and optionally a second thing if local operations – sudo, su, a console login, an SSH second factor – should go through the same approval.

What a host needs

Section titled “What a host needs”

Trust the CA in sshd. One line of sshd_config pointing TrustedUserCAKeys at the ssoossh CA public key. That is the whole requirement for certificate-based SSH login. It is added beside whatever the host already accepts: authorized_keys files and any AuthorizedKeysCommand keep working until you choose to retire them. See Trusting the CA in sshd and the adoption FAQ.

Optionally, install pam_ssoossh. A PAM module that authenticates a local account by asking ssoosshd for a short-lived certificate, showing the person at the terminal how to get it approved, and validating what comes back. It implements the auth stack only, and it is wired into individual services – sudo, su, sshd, login – one at a time, by you. Installing the package writes nothing into /etc/pam.d. See Installing pam_ssoossh.

Nothing on a host ever holds a CA private key, and nothing on a host is registered with the server. The relationship is one-way: the host holds the CA’s public half and decides for itself what a certificate signed by it may do.

I want X, configure Y

Section titled “I want X, configure Y”
I want Configure
SSH logins by certificate, alongside authorized_keys or in place of it TrustedUserCAKeys in sshd_config – sshd trust
To decide which certificate principals may log in as which local account over SSH AuthorizedPrincipalsFile or AuthorizedPrincipalsCommand – sshd trust
sudo approved in a browser instead of a typed password pam_ssoossh in /etc/pam.d/sudo – sudo and su
The same for su pam_ssoossh in /etc/pam.d/su – sudo and su
An approval as a second factor on an SSH login pam_ssoossh in /etc/pam.d/sshd plus AuthenticationMethods – sshd keyboard-interactive
A login at a serial console, a BMC or a VM console, where there is no browser pam_ssoossh with mode=console in /etc/pam.d/login – console login
Identity provider usernames that do not match local account names to work anyway A principals map – the principals map
To say who may become root, or a shared deploy account, on this machine A principals map – the principals map
To rotate the CA without an outage List both keys in both files – sshd trust, the trusted CA file
To offboard someone Disable them in the identity provider. Nothing on the host changes – FAQ
To lock client settings across a fleet The enforce file or platform policy – client settings enforcement
Directory users and groups to exist on a host with nothing provisioned per host ssoossh-nss and systemd in nsswitch.conf – directory users on a host

A host’s trust relationships

Section titled “A host’s trust relationships”
flowchart LR
    accTitle: What a target host trusts, and where each file comes from
    accDescr {
      ssoosshd holds the CA private key and publishes the matching CA public
      key. That public key is copied to two places on each target host:
      /etc/ssh/ca.pub, which sshd reads through TrustedUserCAKeys, and
      /etc/ssoossh/ca.pub, which pam_ssoossh reads through trusted-ca-file. A
      third file, /etc/ssoossh/principals.yaml, is the principals map
      pam_ssoossh consults. pam_ssoossh — loaded into sudo, su, sshd and login
      — reaches the server over HTTPS to request and await approval.
    }
    Server["ssoosshd (holds the CA private key)"]
    CA["ssoossh CA public key"]
    Server -->|publishes| CA

    subgraph Host["Target host"]
        Trusted["/etc/ssh/ca.pub"]
        SSHD["sshd"]
        CAFile["/etc/ssoossh/ca.pub"]
        Map["/etc/ssoossh/principals.yaml"]
        PAM["pam_ssoossh in sudo, su, sshd, login"]
    end

    CA -->|copied to| Trusted
    CA -->|copied to| CAFile
    Trusted -->|TrustedUserCAKeys| SSHD
    CAFile -->|trusted-ca-file| PAM
    Map -->|principals-map| PAM
    PAM -->|HTTPS, request and approval| Server

Two independent trust paths, both anchored on the same public key:

  • sshd reads TrustedUserCAKeys and verifies the certificate an incoming SSH client presents. It never talks to ssoosshd.
  • pam_ssoossh talks to ssoosshd over HTTPS to get a certificate issued for this attempt, then verifies it against trusted-ca-file and decides which local account it authorizes using principals-map. Both files are root-owned on the host, which is what makes “this person may become root here” a statement about this machine rather than about every machine that trusts the CA.

The two ca.pub paths can be the same file. It is the same authorized_keys-format public key either way.

Where to go next

Section titled “Where to go next”