Signing in to Linux and Unix servers

Lighthouse reaches Linux and Unix servers over SSH for its Installations (PEM files, PKCS#12 and JKS keystores, Recipes). It signs in with a key, never a password, and only to servers whose host key it knows. Each Installation picks how under Sign in with.

Lighthouse as an SSH CA

Lighthouse has two SSH certificate authorities, made the first time you need them (Settings, Connections, SSH sign-in, Make the CAs, or the first switch-over):

• the sign-in CA (ssh-user-ca) signs Lighthouse's own sign-in certificates;
• the host CA (ssh-host-ca) signs servers' host keys, if you choose.

Both are ECDSA P-384 keys kept in the secret store (DPAPI on the server, or sealed to the group certificate on a group of servers), never in the database.

For each SSH step of a run, Lighthouse makes a new ECDSA key in memory and signs a certificate for it:

• principal: the Installation's account only (sshd also checks the account exists);
• valid: from 2 minutes before now (for clock drift) to 5 minutes after, or what Settings say (1-30);
• source-address: the addresses under Settings, if you give any, so the certificate is useless from anywhere else;
• extensions: none, so no terminal, port, agent or X11 forwarding, and no ~/.ssh/rc;
• key ID: lighthouse <account>@<server> <time> <random>, which sshd writes in its log.

The key and certificate are written to a new folder under %ProgramData%\Lighthouse\ssh\runs (locked like the ssh folder) for ssh to read, and wiped when the step ends. Each certificate is written to the Keeper's Log (ssh-certificate).

An Installation run from an Outpost has the Outpost make the key and ask Lighthouse to sign its public half (POST /outpost/v1/work/<id>/ssh-certificate). Lighthouse signs only for SSH work that Outpost computer is doing right now, set to sign in with a certificate, once per piece of work, with that Outpost's own addresses from Settings. Older Outposts refuse such work (it is a new work kind), so they never fall back to their own key without saying so.

Switching a server over

Servers need to trust the sign-in CA once. On the Installation, press SSH sign-in…, then Switch this server over. Signed in the way the Installation signs in now, Lighthouse:

1. checks sshd's current settings are valid (sshd -t), and changes nothing if they are not;
2. writes /etc/ssh/lighthouse_user_ca.pub, and TrustedUserCAKeys in /etc/ssh/sshd_config.d/10-lighthouse.conf when sshd reads that folder, or otherwise in sshd_config before the first Match. If sshd already trusts another CA file, Lighthouse adds its key to that file instead;
3. optionally writes host certificates and HostCertificate lines;
4. checks again with sshd -t and with what sshd -T says it now uses. On any failure every file goes back as it was;
5. reloads sshd (open sessions stay);
6. signs in with a certificate. Only when that works does the Installation switch to A Lighthouse certificate.

Every changed file is copied first as <file>.lighthouse-<time>. The account needs sudo without a password for this one step. If it has none, do steps 2 and 5 yourself (or with Ansible, Puppet or your image; Settings, Connections, SSH sign-in shows the lines) and press the button anyway: it then only proves the sign-in.

Then the dialog lists the keys in the account's authorized_keys, read with a certificate, and marks the one in this server's ssh folder (when id_ed25519.pub sits beside it). Tick the ones nobody needs and press Remove the ticked keys: Lighthouse removes exactly those lines, keeps a copy of the file and proves a certificate sign-in again.

Tried in the cloud against OpenSSH 9.6 (Ubuntu 24.04): with sshd_config.d, without it (with a Match block), a second run that changes nothing, a CA that is not trusted (refused), and a setting that wins over Lighthouse's (everything put back). Some appliances and old Unix SSH servers do not support certificates; use a stored key for those.

A stored key

For a server that cannot trust a CA, or to keep one group of servers apart, give the Installation its own key: lh secret set installation-web-servers and paste the whole private key file (no passphrase: Lighthouse signs in without a person, and the secret store keeps it encrypted). For an Installation run from an Outpost, set it on the Outpost instead (Settings, Outposts, Secrets, or lh-outpost secret set); it never leaves the Outpost. A team's Installation must use a name starting installation-. A password manager reference works wherever a secret name does.

Host keys

Lighthouse never trusts a host key on first sight. On the Installation, SSH sign-in…, Check host keys asks the server (from Lighthouse, or from its Outpost) for its keys and shows each fingerprint. Compare them with the server's own (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server) and accept the ones that match. When you accept, Lighthouse asks the server again and keeps only keys it still offers with exactly the fingerprints you ticked. Accepted keys are listed, and can be forgotten, under Settings, Connections, SSH sign-in. If a server later offers a different key of the same type, the dialog says so and sign-in is refused until someone accepts the new key.

Lighthouse also trusts:

• known_hosts in %ProgramData%\Lighthouse\ssh (or the Outpost's ssh folder), as before;
• host certificates from its own host CA, for the host pattern under Settings (* unless changed). Tick Also give the server host certificates when switching over: each of the server's host keys is signed for its name, its hostname and hostname -f, for a year (Settings). Your own SSH clients can trust the same CA with the one @cert-authority line Settings shows;
• host CAs of your own, each for a host pattern, under Settings.

Host certificates are not renewed by themselves yet: switch the server over again before they end (Lighthouse still trusts the accepted keys if one runs out).

Who may

Settings, SSH sign-in and every action under SSH sign-in… are for Lighthouse administrators only, and each is written to the Keeper's Log: ssh-ca-made, ssh-host-key-accepted, ssh-host-key-forgotten, ssh-switch-over, ssh-keys-removed, ssh-certificate. A team operator who makes their own Installations can choose how one signs in (a stored key must be the team's installation-… secret) but cannot switch servers over.