Setting up NearAuth for SSH to Linux servers
When you're done, people SSH to your servers with a short-lived certificate that the NearAuth app on their
computer gets only while their phone is with them. Certificates last 10 minutes, so there are no long-lived
SSH keys to steal, and a session watcher on the server ends open sessions soon after someone's access ends.
You'll need: root on each Linux server (OpenSSH server, systemd for the session
watcher), outbound HTTPS from the server to
secure.nearauth.ai, and NearAuth set up on each
person's phone and Mac or Windows computer. Below,
YOUR_COMPANY_ID stands for your Company ID, which is shown in the admin console.
Sign in to see your company's own values filled in.
1. Give each person their Linux username
On the
Users page, click
Change UID for each person and
enter the account name they log in to servers with (lowercase letters, digits,
_ or
-,
up to 32 characters). Their certificate is only valid for that name, so they connect with
ssh <UID>@server.
2. Set up people's computers
- Each person needs the NearAuth app on their phone and on the Mac or Windows computer they SSH from
(instructions). The
computer app gets and renews their certificate automatically.
- Mac: the app shows a one-time message with a Copy button.
Paste that line at the very top of
~/.ssh/config (before any Host lines):
Include "~/Library/Group Containers/group.ai.nearauth/ssh/config"
The first time, macOS may ask whether Terminal can access data from other apps: choose Allow.
- Windows: the app adds its settings to
%USERPROFILE%\.ssh\config itself.
- If an SSH login is refused, the computer prints why (for example that the phone isn't connected).
3. Install NearAuth on each server
Keep a second root session open (one that doesn't use NearAuth) until you've tested. Then, on the server:
curl -fO https://secure.nearauth.ai/linux/install-nearauth-ssh.sh
sudo bash install-nearauth-ssh.sh --company YOUR_COMPANY_ID --users alice,bob --create-users --banner --watcher-dry-run
The script downloads and checks your company's NearAuth certificate authority, tells sshd to trust it, and
installs the session watcher. It tests sshd's configuration before reloading and puts the old files back if
anything is wrong, and it's safe to run again.
--users a,b: the people (their UIDs from step 1) who will log in to this server.
--create-users: create any of those accounts that don't exist yet.
--banner: show a short notice before login explaining what to check if a login is refused.
--watcher-dry-run: the session watcher only logs what it would do. Drop it once you've tested.
--lockdown: only NearAuth certificates for those users. Their passwords are locked and their
old authorized_keys are set aside. Add it once NearAuth logins work.
Until you use
--lockdown, people can still log in the way they did before, so you can switch
over gradually.
4. Test
- With your phone nearby, run
ssh <your UID>@server from your computer. It should log you in
without a password or key prompt.
- Turn off Bluetooth on your phone or walk away, wait a minute, and try again: the login should be refused,
with a message saying why.
- When that works, run the install command again with
--lockdown and without
--watcher-dry-run. Now an open session ends within about a minute of the person's access
ending.
If a login is refused
- "Permission denied (publickey)": check that the person is logging in as their UID
from step 1, that their phone is connected, and (on a Mac) that the Include line is at the top of
~/.ssh/config.
- On the person's computer,
ssh -v should show Offering public key: ... ED25519-CERT.
- On the server,
sudo sshd -T | grep -i trustedusercakeys should show
/etc/ssh/nearauth_user_ca.pub, and journalctl -u ssh (or -u sshd)
shows sshd's reason.
Removing NearAuth from a server
curl -fO https://secure.nearauth.ai/linux/uninstall-nearauth.sh
sudo bash uninstall-nearauth.sh --dry-run
Check the plan it shows, then run it again without
--dry-run. It removes the SSH setup above and any
older NearAuth server software, gives locked-down users their old keys back, and keeps a backup of everything
it removes. Questions: help@NearAuth.ai or 607-238-3533.