Two-factor sign-in for Ubuntu: SSH, desktop, sudo

What it protects

• SSH, scp, sftp and tunnels, once per connection.
• The desktop login screen and lock screen (GDM), and the text console.
• sudo, sudo -i, su and polkit admin prompts, such as installing software.
• Each is opt-in: SSH through sshd’s PAM file, everything local through one pam-auth-update profile, and only for members of the u2mfa group.

A fleet, or your own laptop

How a login works

1. 1The user runs ssh, scp or sftp, and sshd accepts their key as normal.
2. 2sshd runs its PAM stack, and pam_u2auth.so sends a push for that user. The push names the machine and the source IP.
3. 3The terminal shows “select 47” with the prompt “Press Enter once approved, or type a code”.
4. 4The phone shows three numbers. The user taps 47 and presses Enter, in either order, and the session opens.
5. 5A wrong number or Deny disconnects at once, and the phone does not ring again. Three wrong codes also disconnect.

Two ways to install it

• PAM module (recommended). It gates authentication itself, so ssh, scp, sftp, tunnels and remote commands all pass the same prompt once per connection. It includes offline codes.
• ForceCommand (login_u2auth), for admins who won’t edit PAM. It supports push with number matching only: no offline codes, sftp can’t show the number, and SSH forwarding must be turned off for gated users.

One app for your whole fleet

• Create one U2 Secured app for all your machines. Each user pairs their phone once, and any machine can then push to them. A single computer can be a fleet of one: that is how to get push on your own laptop.
• Register each machine. It gets its own name and key: the phone says which machine a login is on, its offline decisions reach the sign-in log, and revoking it cuts off that machine without touching the others.
• A key can pair a phone as any user, so root on any machine holds a credential for the whole fleet. Run production as its own app if that matters to you.
• Access is still decided on each machine, by group membership, the account and the SSH key. U2 Secured only answers “is this really bob?”
• Every login is one push, and plan quotas count them.

When U2 Secured can’t be reached

Logins fail closed, but users with offline codes still get in. Each user gets a TOTP entry in their authenticator app, and one-time backup codes, both checked on the machine with no network call. This also covers a phone with no data: the TOTP code works offline on the phone. A user with no offline codes is refused while U2 Secured is unreachable, unless you choose failmode=safe, which turns MFA off whenever an attacker can block outbound traffic.

The rollout, page by page

1. 1Install the package on every machine. Installing changes nothing.
2. 2Create the app and its key, and write /etc/u2auth/u2auth.conf.
3. 3Enrol each user once, then gate sshd for the u2mfa group.
4. 4Optionally gate the login screen, lock screen, sudo, su and admin prompts on desktops.
5. 5Test every outcome from a second session.
6. 6Register each machine, so it has its own name and key and reports its sign-ins.
7. 7Read the sign-in log, including sign-ins decided offline.
8. 8When a machine is retired: deregister it, undo the SSH lines, then remove the package.

What you’ll need

• A U2 Secured app for the fleet and its API key (rka_…), created in this portal.
• Each user’s phone with the U2 Secured Authenticator app.
• Root on each machine, and the u2auth .deb for its architecture (amd64 or arm64), or Go 1.22+ and the PAM headers to build from source.
• A break-glass account that will never be in the gated group, with its key kept offline.