RDP Guard : Linux - Install & Test Guide

For: anyone testing Authyo RDP Guard on a Linux server (no prior Authyo
knowledge needed). Follow the steps in order.
Covers: Ubuntu / Debian and RHEL / Rocky / Alma / Amazon Linux.
Version: 1.1.5 | Updated: 2026-07-03

0. What this product does (30-second version)

Normally, logging into a Linux server over SSH asks for a password.
Authyo RDP Guard adds a second step: after the password, it sends a
one-time code (OTP) to a registered email/phone, and the user must enter
that code to get in. This protects the server even if someone steals the
password.

You will:

Install a small package on the server.
Activate it with a one-time key you copy from the Authyo website.
Log in over SSH and confirm it now asks for an OTP (this proves it works).
(Optional) Test "Deactivate" — turning the guard off from the website makes
the server go back to password-only login.

1. What you need before starting

Tick each box before you begin:

A Linux server you can log into (Ubuntu 20.04/22.04/24.04, or
RHEL/Rocky/Alma 8/9, or Amazon Linux 2023).
Administrator access on that server — i.e. you can run commands with
sudo (or you are the root user).
Internet access from the server — it must be able to reach
app.authyo.io on the internet. (Test: run
curl -I https://app.authyo.io — you should get an HTTP/... response,
not a timeout.)
An Authyo account login at https://app.authyo.io so you can copy the
one-time key and (later) click "Deactivate".
An email address or phone number you can check — the OTP will be sent
there during the test. (Email is the most reliable; use that.)
The install file for your Linux type (your Authyo contact will give
you the download link, or get it from the portal's RDP Guard page):
- Ubuntu / Debian → authyo-gatekeeper_1.1.5-1_amd64.deb
- RHEL / Rocky / Alma / Amazon Linux → authyo-gatekeeper-1.1.5-1.x86_64.rpm

⚠️ GOLDEN SAFETY RULE — read this once:
While testing, keep your current SSH window open and open a SECOND SSH
window to test new logins. If anything goes wrong, your first window is
still logged in and you can undo the change. Never close your only session
during setup.

2. Which Linux do I have? (if unsure)

Run this on the server:

cat /etc/os-release | head -2

If it says Ubuntu or Debian → follow Path A (the .deb).
If it says Rocky, AlmaLinux, Red Hat, CentOS, or
Amazon Linux → follow Path B (the .rpm).

3. Install

Copy the install file onto the server first (e.g. with scp, or download it
directly on the server with wget <link>). Then:

Path A — Ubuntu / Debian (`.deb`)

# Go to wherever you put the file, then install it:
sudo apt-get update
sudo dpkg -i authyo-gatekeeper_1.1.5-1_amd64.deb

# If it complains about missing dependencies, this one command fixes it:
sudo apt-get install -f -y

Path B — RHEL / Rocky / Alma / Amazon Linux (`.rpm`)

# Use dnf (or yum on older systems) — NOT "rpm -i" — so dependencies install too:
sudo dnf install -y ./authyo-gatekeeper-1.1.5-1.x86_64.rpm
# Older systems:
# sudo yum install -y ./authyo-gatekeeper-1.1.5-1.x86_64.rpm

Confirm it installed:

authyo-configure --version

You should see authyo-configure 1.1.5. ✅

4. Get your one-time activation key from the website

Log into https://app.authyo.io.
Go to the RDP Guard page.
Find (or add) the server row for this machine.
Click "Get license key".
A one-time key starting with ENRL- appears (e.g.
ENRL-XA9W-FF5G-QXWS-64ET-5QNY). Click Copy.

This key is valid for 60 minutes and can be used once. If it expires,
just click "Get license key" again for a fresh one.

5. Activate the server (the easy one-key way)

On the server, run the setup wizard:

sudo authyo-configure

Answer the prompts:

"Do you have an enrollment key (ENRL-...)? [Y/n]" → type y and Enter.
"API endpoint" → just press Enter (it defaults to https://app.authyo.io).
"Enter your enrollment key (ENRL-...)" → paste the key you copied
(right-click to paste in most terminals), press Enter.
- You should see: "Enrolling this machine with Authyo..." then
  "Enrolled and activated. No Client ID/Secret needed." ✅
- (If it says the key is invalid/expired, get a fresh one from the website
  — step 4 — and try again.)
Contacts — WHO gets the OTP (this is important, read carefully):
- Username → type admin (this is a catch-all: it will receive the
  OTP for ANY user who logs in — simplest for testing).
- Phone or Email → type the email address you can check (e.g.
  you@example.com).
- Channel → type 2 for Email (Email is the most reliable; SMS
  may need extra setup).
- "Add another contact?" → type N.
Security Policy — press Enter to accept the defaults, EXCEPT:
- "Trust device hours" → set to 0 (so it asks for OTP every time —
  needed to see the effect during testing).
"Exempt usernames" → this is a safety list of users who log in with
password only (no OTP). Type a username you can always use as a backup, e.g.
admin (or your own admin username). This is your lockout safety net.
"Enroll Google Authenticator?" → type N (optional; skip for the
basic test).
Review the summary, then "Write this config...? [Y/n]" → type Y.
- You'll see ✓ Wrote /etc/authyo/gatekeeper.conf and
  ✓ Added pam_authyo.so to /etc/pam.d/sshd. ✅

You never typed a Client ID, Client Secret, or long license key — the one
ENRL- key handled all of it. That's the point.

6. TEST IT — prove the OTP now works

⚠️ Keep your current window open. Do the test in a SECOND SSH window.

Open a new terminal / new SSH window and log into the server as a
normal user (not one on the exempt list). For example, from your PC:

ssh someuser@<server-ip>

What you should see:

someuser@server's password:            ← enter the normal password
Authyo verification for someuser
OTP sent via Email to you***com.        ← the OTP was emailed
Enter the OTP, or:
  [R] Resend (tries your next channel)
> ______                                 ← type the code from your email

Enter the password.
Check the email inbox you configured — an OTP code arrived.
Type the code → you're logged in. ✅

🎉 That's the proof it works: login now requires the password AND an OTP.

Prefer not to use a full SSH session? You can also just run
sudo authyo-configure --test — it sends a real test OTP to your contact and
confirms delivery works (note: this spends a small amount of Authyo wallet
balance).

7. (Optional) Test "Deactivate" — the guard steps aside

This shows what happens when you turn the guard off for a server from the
website: it goes back to password-only login (no OTP).

On the website (https://app.authyo.io → RDP Guard), find this server →
Servers → click Deactivate.
Back on the server, tell it to refresh immediately (instead of waiting up to
15 minutes):
```
sudo systemctl start authyo-gatekeeper-heartbeat.service
```
Open a new SSH window and log in again:
```
ssh someuser@<server-ip>
```
- Expected: it asks for the password only — NO OTP — and logs you in. ✅

To turn the guard back on: re-activate the server on the website (or re-run
sudo authyo-configure with a fresh key), then run the heartbeat command again.

8. Did it work? Quick self-check

Run this to see the recent decisions the guard made:

sudo tail -n 20 /var/log/authyo/gatekeeper.log

A login that asked for OTP shows: SENDOTP_OK ... via=Email then GATE_PASS.
A stepped-aside (deactivated) login shows: GATE_STEPASIDE ... activation=deactivated.

Check overall status any time:

sudo authyo-configure --status

9. If something goes wrong (troubleshooting)

Symptom	Cause & fix
`authyo-configure: command not found`	The package didn't install. Re-run the install step (§3). On `.rpm`, make sure you used `dnf`/`yum`, not `rpm -i`.
Enrollment key says "invalid / expired"	The `ENRL-` key is one-time and lasts 60 min. Get a fresh one from the website (§4).
No OTP arrives during login, but it lets you in anyway	The OTP channel is misconfigured. The log shows `SENDOTP_..._ERR ... invalid sender address`. Re-run `sudo authyo-configure` and set the contact to Email with a real address. (SMS may need sender setup in Authyo.)
Login hangs or "cannot reach Authyo"	The server can't reach `app.authyo.io`. Test: `curl -I https://app.authyo.io`. Fix the server's internet/firewall/DNS.
I'm locked out / OTP won't come	Use your first (still-open) SSH window, OR log in as an exempt user (§5 step 6, password-only). To fully undo: `sudo cp /etc/pam.d/sshd.authyo-backup-* /etc/pam.d/sshd` (restores the original SSH config, removing the guard).
Deactivate didn't take effect	It refreshes on a timer (up to 15 min). Force it: `sudo systemctl start authyo-gatekeeper-heartbeat.service`, then try logging in again.

Emergency "remove the guard completely":

sudo authyo-configure --uninstall     # unhooks pam_authyo from SSH (restores backup)

Your SSH logins go back to normal (password-only) immediately.

10. Cheat-sheet (all the commands in one place)

# Install (Ubuntu/Debian)
sudo dpkg -i authyo-gatekeeper_1.1.5-1_amd64.deb && sudo apt-get install -f -y
# Install (RHEL/Rocky/Alma/Amazon)
sudo dnf install -y ./authyo-gatekeeper-1.1.5-1.x86_64.rpm

authyo-configure --version                 # confirm 1.1.5
sudo authyo-configure                       # activate (paste ENRL key) + set contact
sudo authyo-configure --test                # send a test OTP
sudo authyo-configure --status              # show current config
sudo tail -n 20 /var/log/authyo/gatekeeper.log   # see what happened at login

# Deactivate test
sudo systemctl start authyo-gatekeeper-heartbeat.service   # force refresh now

# Undo everything
sudo authyo-configure --uninstall           # remove guard from SSH

Questions? Contact your Authyo representative. Keep your first SSH session open
while testing — it's your safety net.