Installing Authyo RDP Guard on Windows

Version: 1.1.3 | Updated: 2026-08-20
Verified on: Windows 11 23H2 + Windows Server 2022 (both Workgroup) ✅
Supported: Windows 10 (1607+), Windows 11, Windows Server 2016 / 2019 / 2022 / 2025 — 64-bit
One download: AuthyoGatekeeperSetup-1.1.3.exe. See Supported Windows versions.

⚠️ Check the prerequisites first.
90% of "Authyo tile doesn't appear" and "RDP signs me in without OTP"
tickets come from a missed prerequisite — almost always NLA still on for
RDP, no OTP recipient saved on the portal, or the server unable to reach
app.authyo.io. Read Pre-requisites and
Recovery before installing on each target
server. You do not need to pre-install .NET, and you never need a
Client ID or Secret — the setup EXE and the license key handle both.
After installing, the Configurator's Diagnostics tab re-runs all of
this on the box and offers one-click fixes (see
Diagnostics).

Authyo RDP Guard adds an OTP challenge to the Windows logon screen. After
install, every RDP sign-in — including a reconnect that lands on the lock
screen — requires both a valid Windows password and a one-time code sent to
a pre-configured admin contact. The standard password tile is hidden for remote
sessions, so there is no way around the Authyo tile.

At the physical or serial console the Authyo tile appears alongside the
normal password tile and the user may pick either. That pass-through is
deliberate — it is your recovery route, together with Google Authenticator
(which is verified on the server itself and so survives an Authyo outage) and
backup codes (which still need Authyo reachable). See
Break-glass options.

⚠️ A server with no OTP recipients is not protecting anything. Until at
least one contact is saved in its portal policy, sign-in falls straight
through to the Windows password and the log records GATE_FAILOPEN_NOCONTACT.
That is deliberate — a half-set-up server must never lock you out — but do not
mistake it for protection. See
step 1b.

⚠️ Read this first

Authyo RDP Guard installs as a Windows Credential Provider — it
participates in the OS sign-in flow. While the installer is small and
the uninstall is clean, you should:

Pilot on one server first. Don't roll out to the whole fleet on day
one. Install on a single staging machine, sign in via the new tile a
few times, then expand.
Configure a break-glass path before you rely on it. On the portal, add
at least one exempt (bypass) user (password-only) and set up Google
Authenticator (TOTP) for an admin. TOTP works even when Authyo is
unreachable — it is the one recovery path that survives an outage on a
remote RDP box. The Configurator's Diagnostics (check #8) tells you if
this server has no offline recovery.
Keep a second local Administrator account active before installing.
Have a system restore point if you're paranoid.

If anything goes wrong at the logon screen: Safe Mode gets you back in — Windows
does not load third-party credential providers there, so the plain password tile
is available to any local admin. To remove the product from Safe Mode, run
authyo-rescue.ps1: Settings → Apps → Uninstall does not work in Safe Mode,
because Windows Installer is not one of the services Safe Mode starts.

⚠️ One catch that bites exactly when you need it not to. RDP Guard can
only be upgraded, repaired or uninstalled by the same administrator account
that installed it (or by a deployment tool running as SYSTEM). Any other
admin — including the rescue account above — gets a refusal dialog, and cannot
open the Configurator either. So do the Safe Mode uninstall from the account
you installed with. If that account is gone or unusable, clear the lock
first from an elevated prompt:
Remove-ItemProperty 'HKLM:\SOFTWARE\Authyo\Gatekeeper' -Name InstallOwnerSid -Force
then uninstall as normal. See Recovery.

What's in the box

One file: AuthyoGatekeeperSetup-1.1.3.exe (≈3 MB) — the only Windows
download in the portal, and the only one you need.

It is a bootstrapper: it checks whether this PC already has the .NET Desktop
Runtime, downloads and installs it silently if not, and then runs the product
installer. On a PC that already has .NET 8, 9 or 10 it installs nothing extra
and goes straight to the wizard.

Why not a plain .msi? There used to be one, and it required you to
install .NET yourself first. If you skipped that step the install failed — in
the worst case after the credential provider was already registered. The
.exe removes that failure mode entirely, so it is now the only thing shipped.
A bare MSI is still built for GPO / SCCM mass deployment, where the
deployment tool needs an MSI and .NET is pushed separately — ask support for
it; it is deliberately not on the download page.

Files installed

Path	Purpose
`C:\Program Files\Authyo\Gatekeeper\Authyo.Gatekeeper.CredentialProvider.dll`	The Credential Provider that adds the Authyo tile to the logon screen
`C:\Program Files\Authyo\Gatekeeper\Authyo.Gatekeeper.Bridge.dll`	C++/CLI shim that hosts the .NET 8 runtime inside LogonUI
`C:\Program Files\Authyo\Gatekeeper\Authyo.Gatekeeper.Core.dll`	Managed library — HTTP client, JWT, DPAPI, SQLite trust cache, TOTP
`C:\Program Files\Authyo\Gatekeeper\Authyo.Gatekeeper.Configurator.exe`	WPF wizard for setup + the Diagnostics self-check
`C:\Program Files\Authyo\Gatekeeper\Authyo.Gatekeeper.Service.exe`	Background heartbeat service — installed and started as Authyo RDP Guard Heartbeat (`AuthyoGatekeeperHeartbeat`), LocalSystem, Automatic. Keeps license state, the kill switch and policy fresh, and repairs the tile registration if something removes it.
`C:\Program Files\Authyo\Gatekeeper\Ijwhost.dll` + SQLite libs	.NET 8 host + dependencies
`C:\ProgramData\Authyo\Gatekeeper\`	Where `config.json`, `trust.db`, and logs live after first run

Registry entries

Key	Purpose
`HKLM\SOFTWARE\Classes\CLSID\{B251F0AF-6D20-4C4D-90ED-4ADE0D8256D7}`	COM registration of the CP
`HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\{B251F0AF-...}`	Tells LogonUI to load us
`HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Provider Filters\{B251F0AF-...}`	Filter registration (hides the password tile on RDP sessions)
`HKLM\SOFTWARE\Authyo\Gatekeeper\InstallOwnerSid`	Install-owner lock — the SID of the admin who installed. Upgrade, repair, uninstall and the Configurator are refused for any other admin account. Not written when the installer runs as SYSTEM, so Intune / SCCM / GPO / RMM deployments are never locked. Delete this value to clear the lock.

Plus an Add/Remove Programs entry ("Authyo RDP Guard", published by "Authyo") and a Start Menu shortcut to the Configurator.

What happens if it fails

Worth reading before you put this on a production server, because it is the
question that matters most and the answer is short.

If any part of RDP Guard cannot start, the Authyo option is simply not shown and
you sign in with your normal Windows password.

That covers every case we know of: the .NET runtime missing, our files missing or
damaged, a version mismatch after a bad upgrade, antivirus quarantining a
component, an unreadable configuration, or the agent failing for a reason we have
not thought of. Every call between the Windows sign-in screen and our software is
individually protected, and every one of them fails the same way — towards
letting you in.

The worst case is "the extra sign-in step is missing", not "the machine will not
start".

What this does not protect you from

Two things behave differently, and both are deliberate:

A deliberate lock-out policy. If Block sign-in if Authyo is unreachable
is on (the default) and Authyo cannot be reached, sign-in is refused rather
than allowed. That is a policy decision working as designed, not a failure —
and it is why an authenticator is required. See
Break-glass options.
A lapsed licence. OTP stops being enforced and the normal Windows password
returns. The machine keeps working; the protection does not. See
Remote kill-switch.

What the agent reports to Authyo

For support and license management, the background heartbeat service sends a
small identity inventory for this server about every 15 minutes. This is
disclosed here on purpose — it is not hidden, and you can see it in the agent
log (gatekeeper.log). It lets Authyo recognise which server a support ticket
is about and confirm a license is on the machine you think it is.

Reported by the agent	Added by Authyo's server
Hostname, OS version	Approximate location (city / country)
System UUID (SMBIOS), MAC address(es)	Hosting provider / network name
Windows domain or workgroup	The public IP the heartbeat came from
Agent version
Enabled local Windows account names — so the portal can offer them as a pick-list when you add an OTP recipient
Which of those accounts have a Google Authenticator enrolled — names only, never the secret

Location is derived by Authyo from the IP the heartbeat arrives on — the
agent has no GPS and never sends a location. No OTP codes, passwords,
authenticator secrets, or contact details are part of this inventory. It is
sent only by the background service, never while someone is signing in, and is
stored by Authyo for support and license management. If you would like a copy of
what is held for your servers, contact Authyo support.

Pre-requisites


OS	64-bit Windows 10 / 11 or Windows Server 2016–2025 — see the full matrix below (workgroup or domain-joined)
.NET Desktop Runtime	Version 8 or newer. You do not have to install this — `AuthyoGatekeeperSetup.exe` installs it if missing.
Administrator rights	Required at install time and to launch the Configurator (and see the install-owner note below)
Network reachable	Machine must reach `app.authyo.io` over HTTPS (443). The setup EXE also reaches `builds.dotnet.microsoft.com` only when .NET is missing.
A server added on the portal	Add it under RDP Guard at https://app.authyo.io. One server per license; adding one charges your wallet for the first month.
Its license key	The only thing you type into the Configurator. Get it with Get license key next to that server. You never enter a Client ID or Secret. The key is a one-time token — it expires in 60 minutes, so fetch it when you are ready to install, not in advance.
At least one OTP recipient	Saved under that server's policy on the portal. Without one the server activates but enforces no OTP at all — see step 1b.
The right admin account	Whichever account runs the installer is the only one that can later upgrade, repair or uninstall it, or open the Configurator. Use a shared/service admin account, not a personal one that may be deleted.
NLA turned off for RDP	Required if you want OTP on RDP — see the warning directly below

⚠️ If you are protecting RDP, you must turn NLA off — one command, one time.
Network Level Authentication is on by default on Windows Server 2016 and
newer. With NLA on, the RDP client validates the password before the server
ever draws a logon screen, so no credential provider runs — including ours.
The result is an RDP session that signs in with no OTP at all, silently. It
is not a failure you will notice; it just quietly is not protecting you.
# Run ONCE on each server, elevated, after installing.
# Works in both Windows PowerShell 5.1 and PowerShell 7.
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp' `
    -Name UserAuthentication -Value 0
The Configurator's Diagnostics tab checks this for you and warns if NLA is
still on. Full detail, and the security trade-off of turning NLA off, in
Using Authyo RDP Guard with Remote Desktop.
Console-only (no RDP) deployments can leave NLA alone.

Supported Windows versions

64-bit (x64) only — there is no 32-bit or ARM64 build. That is our build, not
a .NET limitation (Microsoft ships x86 and ARM64 runtimes), so installing an
ARM64 runtime will not help — the credential provider itself is x64.

Windows	Supported	Notes
Windows 11 — all versions	✅ Yes	Verified on 23H2
Windows 10 — 1607 and newer (incl. 21H2, 22H2, LTSC 2019/2021)	✅ Yes	1507/1511 are not supported
Windows Server 2025	✅ Yes	Desktop Experience — Server Core: see note below
Windows Server 2022	✅ Yes	Verified. Desktop Experience — Server Core: see note below
Windows Server 2019	✅ Yes	Desktop Experience — Server Core: see note below
Windows Server 2016	✅ Yes	Desktop Experience — Server Core: see note below
Windows Server 2012 / 2012 R2	⚠️ Only with ESU	Out of Microsoft support; .NET only runs there with an Extended Security Update subscription. Not recommended, not tested by us.
Windows 8.1 / 8 / 7, Server 2008 / 2008 R2	❌ No	.NET 8+ does not run on them
32-bit (x86) or ARM64 Windows	❌ No	x64 build only

On Server Core there is no interactive logon screen, so the credential
provider tile never appears — what you get is OTP on RDP sessions, which is
usually the point on a Core box anyway.

⚠️ Server Core is not a self-service install today. A server is activated
from the Configurator, and the Configurator is a desktop (WPF) app — there is
no command-line, silent, or portal-side way to activate one. Until a server is
activated it has no configuration on disk and the agent stays inert, so a Core
box can be installed but never brought into service. Talk to Authyo support
before deploying to Server Core — and do not add the server on the portal
first, because adding one charges your wallet.

⚠️ Domain controllers: treat these as a special case. A DC has no local
accounts, and locking yourself out of a DC is a bad afternoon. Pilot on a
member server first and make sure a break-glass path works before you go near
one.

Which .NET you already have, and what happens

The agent targets .NET 8 but is built with RollForward=Major, so a newer
runtime satisfies it. What the setup EXE does in each case:

Already on the PC	What happens	Downloads anything?
.NET Desktop Runtime 9 or 10	Installs nothing extra, runs on the runtime you have	No
.NET Desktop Runtime 8	Installs nothing extra	No
.NET Framework 3.5 only	Installs .NET Desktop Runtime 8 alongside it	Yes (≈58 MB)
.NET Framework 4.8 only	Installs .NET Desktop Runtime 8 alongside it	Yes (≈58 MB)
.NET 6 or 7 only (too old)	Installs .NET Desktop Runtime 8 alongside it	Yes (≈58 MB)
ASP.NET / console runtime only (no Desktop)	Installs the Desktop runtime	Yes (≈58 MB)

.NET Framework 3.5 and 4.8 are a different product from modern .NET — they
live in different folders and never conflict. Nothing already on the machine is
removed, replaced, or upgraded; .NET installs side by side by design.

If the PC has no internet access to builds.dotnet.microsoft.com, install the
runtime manually first from https://dotnet.microsoft.com/download/dotnet/8.0
(".NET Desktop Runtime 8.0.x — x64"), then run the setup EXE as normal; it will
detect it and skip the download.

To see what you have:

dotnet --list-runtimes

A line containing Microsoft.WindowsDesktop.App 8. (or 9. / 10.) means
nothing will be downloaded.

Install — step by step

The short version: add the server on the portal, copy its license key,
run one .exe on the server, paste the key, click Activate. That is the
whole install. There is no Client ID, no Client Secret, and nothing to save.

What is configured where

This is the single most common source of confusion, so it is worth reading once.
The Configurator on the server is not where you set up your policy any more:

Setting	Where you set it
Who gets the OTP (admin contacts, names, addresses)	Portal — RDP Guard → your server → policy
Channels (Email / SMS / WhatsApp / Voice) and their order	Portal
Exempt (bypass) users	Portal
Remember-device / trust window	Portal
Google Authenticator (TOTP) enrolment	Portal — "Set up authenticator" next to each person
Outbound webhook	Portal
Team Login mode	Portal
Activating this server with its license key	Configurator (once)
Testing delivery from this server	Configurator — Send test OTP from this server
Emergency access checks, diagnostics, sign-in history	Configurator

Portal changes reach the server on their own — on its next check-in, on the next
sign-in, or immediately when the server is online. Nothing needs re-saving on the
box, which is why the Configurator has no Save button.

1. Add the server on the portal, and copy its license key

Log into https://app.authyo.io → RDP Guard.

Click Add a server, pick the application it belongs to, and confirm. This
charges your wallet for the first month and creates one license — one
license protects one server.
Find the new server in the list and click Get license key.
Copy the key it shows.

⚠️ The key is shown once, works once, and expires in 60 minutes.
Copy it straight onto the server you are about to install on. If you lose it,
or you come back to it tomorrow, just click Get license key again — a fresh
key costs nothing and does not create a second server or a second charge.

1b. Add at least one OTP recipient

Still on the portal, on the same server row, open its policy / OTP recipients
and add the people who will sign in. A brand-new license has an empty policy,
and an empty policy protects nothing — so do this now, before you install.

For each person:

Name (Windows username) — the exact Windows username, as Windows spells
it (case-insensitive; a leading DOMAIN\ is ignored). A row named admin or
Administrator acts as the catch-all for everyone else. This server has not
checked in yet, so the name pick-list is still empty — type the username by
hand. Once it checks in, later edits offer the accounts it reported.
Channels — tick Email / SMS / WhatsApp / Voice call. The number on each
pill is the delivery order: 1 gets the first OTP, 2 and up are used by
each Resend.
Email / Phone — the address, or country code + number, for that person.

Save the policy.

⚠️ With no recipients, this server is not protected — and it will not look
broken. Activation still succeeds, the Authyo tile still appears, and
Windows still logs you in. What actually happens is that the gate gives up and
falls through to the plain Windows password, logging
GATE_FAILOPEN_NOCONTACT. Step 5's Send test OTP from this server also
refuses to send. The fail-open is deliberate — a half-configured server must
never lock you out — but until this step is done, the server is not enforcing
anything.

2. Download the installer

Still in RDP Guard, download AuthyoGatekeeperSetup-1.0.91.exe from the
Windows card. That is the only Windows download — there is no second file to
choose between.

Download it on the server you are protecting: RDP into that server, open the
portal there, and download it locally. Nothing to copy across, and the license key
is already on your clipboard.

3. Run the installer

Right-click AuthyoGatekeeperSetup-1.1.3.exe → Run as administrator.

You may see a Windows SmartScreen warning. Click More info → Run anyway.

If this PC has no modern .NET yet, the first thing you see is a short "Installing
Microsoft .NET Desktop Runtime" step — that is expected, it needs internet, and
it takes a minute or two. If .NET 8, 9 or 10 is already there, the wizard appears
immediately and nothing extra is installed.

The installer then:

Shows the license agreement
Asks for an install location (default: C:\Program Files\Authyo\Gatekeeper\)
Installs files, writes registry entries, registers the Credential Provider
Installs the background heartbeat service
Offers to launch the Authyo RDP Guard Configurator at the end

Keep the Launch Authyo Gatekeeper Configurator checkbox ticked (it still
carries the older product name) and click Finish. Windows shows a UAC prompt
before the Configurator opens — accept it; the Configurator needs elevation.

4. Activate with the license key

The Configurator opens on the Setup tab.

Paste the license key into License key.
Click Activate.

That is the entire configuration step. The server redeems the key at Authyo,
receives its own credentials and policy back, and seals them to this machine with
Windows DPAPI. You do not type a Client ID, a Client Secret, an API endpoint,
or any contacts — the key gets the credentials, and the server pulls down the
recipients you saved in step 1b.

On success the Setup tab collapses the activation form and shows a banner
confirming the server is live, plus a summary of the policy it just pulled
(contacts, exempt users, trust window, fail mode).

Read the contact count on that summary. If it says none, this server will
not enforce OTP — go back to the portal, add a recipient (step 1b), then
re-open the Configurator, which re-pulls the policy each time it opens.

Now open the Diagnostics tab and click Run diagnostics. It does not run
by itself, and it is where the NLA and break-glass warnings appear — the two
things that most often turn a working install into either a lock-out or a
silently unprotected RDP session.

If Activate fails, the message says why. The usual causes are a key that has
already been used or has passed its 60 minutes (get a fresh one), no route to
app.authyo.io on 443, or a proxy/TLS-inspection appliance in the way.

There is no offline activation. The Configurator contains a legacy
Advanced panel for entering a Client ID, Secret and RDPG- key by hand,
but it is collapsed on every launch and no setting, flag or command-line
argument reveals it — and it would not help anyway, since it calls the same
Authyo endpoint. A server must be able to reach app.authyo.io to activate.

5. Send a test OTP from the server

Click Send test OTP from this server.

This is worth doing every time, because it tests the things only this machine can
tell you about: that the server itself can reach Authyo through your firewall or
proxy, that its sealed credentials work, and that the first contact's channel
actually delivers. It sends a real OTP to the first contact in the policy.

If it fails, the message reports the real reason from Authyo (bad channel
priority, unreachable address, blocked network) rather than a generic error.

This is a different test from the portal's own send button. The portal's test
proves Authyo can deliver; this one proves this server can.

Press Win+L to lock the screen. You should see the Authyo RDP Guard tile
alongside the standard Windows tiles.

Type your Windows username
Type your Windows password (the field has a reveal/eye button)
Click the → arrow (Submit)
Wait for the OTP. The prompt names the channel and masked recipient, e.g.
"OTP sent via Email to nav***com"
Type the OTP (this field has a reveal button too)
Click → again

Windows logs you in.

⚠️ If you were not asked for a code, this server is not protected yet.
A password-only sign-in through the Authyo tile is not success — it means
the policy has no contact matching the username you signed in with (most often
because no policy was saved on the portal at all), so the gate deliberately
failed open rather than lock you out. The tile appears either way, so the
screen looks identical to a working install.

Confirm which one you got:
Select-String GATE_FAILOPEN_NOCONTACT 'C:\ProgramData\Authyo\Gatekeeper\logs\gatekeeper.log'
A hit means unprotected. Fix it on the portal by adding a contact whose
Name is the Windows username (or an Administrator catch-all), then sign
in again and expect the OTP prompt.

Who receives the OTP is decided by the policy you set on the portal. With
per-user routing, it goes to the contact whose Name matches the Windows username
signing in (case-insensitive; a leading DOMAIN\ is ignored), with admin /
Administrator as the catch-all. The first OTP goes to one contact — never a
fan-out to every channel at once.

If the OTP doesn't arrive: after a short countdown a Resend OTP link
appears. The tile shows a 60-second countdown; the server accepts a resend
after 30 seconds. Each resend auto-advances to that person's next channel
(e.g. Email → Sms → Whatsapp) and the link updates to "Resend OTP – try Sms".
Only one OTP is ever valid at a time — a resend invalidates the previous code.

If Authyo cannot deliver at all, the tile then reveals the free break-glass
options — "I have a backup code" and, if enrolled, Google Authenticator. These
appear only after the paid OTP path fails.

7. Verify it's working

Open PowerShell as Administrator and run:

Get-Content 'C:\ProgramData\Authyo\Gatekeeper\logs\gatekeeper.log' -Tail 10

You should see a sequence like:

INFO   user=naveen ip=console GATE_START
INFO   user=naveen ip=console SENDOTP_OK contact='naveen' via=Email to=nav***com maskId=...
INFO   user=naveen ip=console JWT_VERIFIED
INFO   user=naveen ip=console GATE_PASS

GATE_PASS is the final success marker. Others you may see: BACKUPCODE_OK,
TOTP_BREAKGLASS GATE_PASS, GATE_DISABLED (server kill-switch), LICENSE_OK /
LICENSE_LAPSED, GATE_FAIL_OPEN (allowed because Authyo was unreachable and
fail-open was configured), GATE_STEPASIDE (the license lapsed or the seat was
deactivated, so OTP is off and the normal password
tile is shown instead).

Back on the portal, the server should now show as checked in. If it still shows as
never seen after a few minutes, the heartbeat service is not reaching Authyo — run
Run diagnostics in the Configurator.

Diagnostics (built-in self-check)

The Configurator has a Diagnostics tab that runs 10 checks and offers
one-click fixes. Click Run diagnostics any time; it also runs by itself right
after you activate the server, and again after any one-click fix so you can see
the item turn green.

#	Check	Severity
1	Config folder exists and is writable	✅ critical
2	Folder ACL is Administrators + SYSTEM only	one-click fix
3	Config file valid & secrets decrypt (DPAPI)	✅ critical
4	.NET Desktop Runtime 8 or newer present	✅ critical
5	Credential Provider registered	warn only (advises re-running the installer)
6	Install DLLs present	✅ critical
7	NLA status (advisory for RDP)	warn only
8	At least one break-glass recovery path	warn only
9	Current user can actually sign in	warn only
10	Authyo reachable	warn only

A critical failure means this server cannot gate a sign-in correctly and needs
fixing before you rely on it. Warn only items are worth reading but do not stop
anything — note that #7 (NLA) and #8 (break-glass) are the two that most often
turn a working install into a lock-out or a silently unprotected RDP session, so do
not skim past them.

One-click fixes are offered for creating the config folder and tightening the
folder ACL. Save diagnostics for support writes a bundle you can send us.

Day-to-day usage

Using Authyo RDP Guard with Remote Desktop (RDP)

Install Authyo RDP Guard on the server you want to protect, not on
the client machines. When someone connects with mstsc, the server's
logon screen renders inside the RDP window and your Authyo tile appears
there exactly like on the physical console.

Several people sharing one desktop? If a team hands off long-running work
on one machine and needs to resume the same session (apps still open) while
each person still signs in with their own OTP, see
TEAM-LOGIN.md. It's an optional mode you turn on per license
in the portal.

One-time server prep — disable NLA. Network Level Authentication is
on by default on Windows Server 2022 and bypasses Credential Providers.
On every server where you install RDP Guard, disable NLA so the RDP login
renders through LogonUI and our tile fires:

# Run on the server (elevated) once after installing RDP Guard.
# Registry rather than WMI: Get-WmiObject does not exist in PowerShell 7.
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp' `
    -Name UserAuthentication -Value 0

Important — console vs RDP. The credential-provider filter hides
the standard password tile only for remote (RDP) sessions. At the
physical console — and at a cloud serial console (AWS EC2 Serial,
Azure Serial Console, GCP serial) or hypervisor console — the normal
password tile is always shown. That console path is your recovery route
if OTP ever can't be delivered on a remote box.

Test from a client:

mstsc /v:your-server.example.com

RDP reconnect to a disconnected session also fires the OTP gate
(Windows raises CPUS_UNLOCK_WORKSTATION). Each reconnect = another OTP.
This is intended security behavior.

Multiple servers, one webhook — telling them apart

If you point several servers at the same logging webhook URL, every
log line now carries the server's identity so your receiver can filter by
it. The JSON envelope is:

{ "ReportingStatus": {
    "Subject":    "RdpGuardLog",
    "ServerHost": "WIN-DB01",
    "LicenseKey": "RDPG-XXXX-XXXX-XXXX-XXXX",
    "Timestamp":  "2026-07-01T14:23:45+05:30",
    "Level":      "INFO",
    "Message":    "user=naveen ip=console GATE_PASS",
    "Raw":        "2026-07-01T14:23:45+05:30  INFO   user=naveen ip=console GATE_PASS"
} }

ServerHost is the machine name (automatic — no config needed).
LicenseKey is the server's license key (omitted while a box is
not yet activated). It is not secret to you — you own both ends.
Subject is RdpGuardLog on Windows and PamGuardLog on Linux, so
you can also tell the two platforms apart.

Set the webhook on the portal, on the same RDP Guard page as the rest of the
policy (leave it blank to disable it). It reaches the server with the next policy
sync — there is nothing to edit on the box. Delivery is fire-and-forget: a slow or
down receiver never delays a sign-in, and the on-disk log is always the source of
truth.

Adding or changing admin contacts

Do it on the portal: RDP Guard → find the server → edit its policy. There is
nothing to change on the server itself, and no Configurator visit needed.

The change reaches the server on its own — pushed immediately if it is online,
otherwise on its next check-in or at the next sign-in. No reboot, no restart.

If you want to confirm a change landed on a particular server, open the
Configurator there: the Setup tab prints the policy it currently holds
(contacts, exempt users, trust window, fail mode). It also re-pulls the policy
from the portal each time you open it, so what you see is current.

Break-glass options

You have four ways to get in when the normal OTP can't be delivered — but read
the "works offline" column carefully, because only one of them survives an Authyo
outage, and Team Login mode disables two of them (exempt users and the
trusted-device window are both ignored in team mode — see
TEAM-LOGIN.md):

Method	Works offline (Authyo down)?	Where you set it up
Google Authenticator (TOTP)	✅ Yes — verified locally on the server	Portal — "Set up authenticator" next to the person
Backup code	❌ No — needs Authyo reachable	Portal — RDP Guard page → "Emergency backup codes" → Manage backup codes
Exempt (bypass) user	✅ Yes — but local console only, not RDP	Portal — exempt users in the server's policy
Trusted device window	❌ No on a portal-activated server — the trust cache is ignored whenever Authyo is unreachable	Portal — remember-device hours in the policy

Backup codes: generated from the RDP Guard page ("Emergency backup codes"
→ Manage backup codes), default 10, displayed as XXXX-XXXX-XXXX, each
usable once. On the tile, click "I have a backup code" and type it. They are
per application and shared by every server under it — generating a new
batch immediately invalidates the previous batch on all of them.
TOTP / backup-code prompts only appear AFTER the paid OTP fails —
this protects your OTP spend while keeping recovery available.

The one true lock-out is: remote RDP and Authyo unreachable and no
TOTP enrolled. The trust window and exempt users do not save you here —
when the agent cannot verify a fresh policy it deliberately ignores both.

The portal enforces the prevention for you. While one of a license's servers
is connected, saving its policy is refused until every person on it has an
authenticator enrolled — in Team login too, where the authenticator belongs to
the person signing in rather than to the shared Windows account. It is not
tied to the fail-closed setting; an authenticator is required either way.

The check only applies while a server is reachable, because enrolling stores
the code on the server itself and needs a live connection. If every server on a
license is offline the policy still saves, and the requirement re-applies the
moment one reconnects — which is also the moment you can satisfy it.

If you do reach the locked-out state, recovery needs console or serial access
to sign in locally and disable the gate. See
RUNBOOK-authyo-down-recovery.md.

Temporarily disabling OTP

Rename — do not delete — C:\ProgramData\Authyo\Gatekeeper\config.json
(e.g. to config.json.off). With no config present the Authyo tile hides and
users sign in via the standard Windows password tile. Rename it back to
re-enable.

⚠️ Deleting it is irreversible and destroys your offline break-glass.
config.json holds the DPAPI-sealed client secret, the license key and
activation binding, the node key, and every Google Authenticator (TOTP)
enrolment secret on this server. Delete it and those enrolments are gone —
the one recovery path that survives an Authyo outage — and the server must be
activated again from scratch with a fresh license key.

Remote kill-switch (from the portal)

An admin can disable a specific server from the Authyo portal. On the
next sign-in the gate fails closed and denies the login (log marker
GATE_DISABLED) until it's re-enabled. The flag is cached from the periodic
heartbeat, so it survives a brief network outage.

⚠️ Disable is the only portal action that blocks sign-in — the others do the
opposite. Once a license is Blocked and the paid period has ended, or the
seat is Deactivated, or the license lapses / is suspended / is cancelled,
the guard steps aside: the Authyo tile disappears, OTP stops being enforced,
and users sign in with the plain Windows password (log marker
GATE_STEPASIDE). Re-activate on the portal to enforce OTP again. Plan for
this — a billing lapse leaves the server MFA-free, it does not lock anyone
out.

Logs

File	What's in it
`C:\ProgramData\Authyo\Gatekeeper\logs\gatekeeper.log`	Plain-text log of every sign-in attempt (markers above)
Windows Event Viewer → Application	Anything that fails before our log is initialized — useful if the CP itself can't load

Logs are append-only. Nothing rotates or trims them — gatekeeper.log
grows without bound, so include it in whatever housekeeping you already run on
the server.

Recovery — emergency access

If the Authyo tile ever blocks you, in rough order of preference:

Another break-glass path: TOTP code, backup code, or a bypass user
at the console (see Break-glass options).
Console / serial access: the password tile is never hidden at the
physical or cloud-serial console. Sign in there and disable the gate.
Safe Mode: reboot with Shift+Restart → Troubleshoot → Advanced →
Startup Settings → 4. Third-party credential providers don't load
in Safe Mode, so the plain password tile works. Sign in → Settings →
Apps → Authyo RDP Guard → Uninstall.
⚠️ Windows Installer does not run in Safe Mode. MSIServer is not in
Safe Mode's service list, so Settings → Apps → Uninstall and msiexec /x
both fail there with "The Windows Installer Service could not be
accessed". Either use the rescue script (it does not need Windows
Installer), or enable the service first from an elevated prompt:
```
reg add "HKLM\SYSTEM\CurrentControlSet\Control\SafeBoot\Minimal\MSIServer" /VE /T REG_SZ /F /D "Service"
reg add "HKLM\SYSTEM\CurrentControlSet\Control\SafeBoot\Network\MSIServer" /VE /T REG_SZ /F /D "Service"
net start msiserver
```
⚠️ Uninstall only works from the account that installed it. Any
other administrator gets a refusal dialog. If that account is gone,
clear the lock first from an elevated prompt, then uninstall:
```
Remove-ItemProperty 'HKLM:\SOFTWARE\Authyo\Gatekeeper' -Name InstallOwnerSid -Force
```
Emergency rescue script (authyo-rescue.ps1), run elevated:
```
powershell -ExecutionPolicy Bypass -File .\authyo-rescue.ps1
```
It best-effort uninstalls the product and force-removes the
credential-provider registry keys. By default it KEEPS your config;
add -PurgeData to also delete C:\ProgramData\Authyo\Gatekeeper\.

Get this script before you need it. It ships as authyo-rescue.ps1
in the release package. It is not installed by the setup EXE, so keep a
copy off the server alongside your other break-glass material —
during a live lockout you cannot fetch it from the machine that is
locking you out.

It also sets HKLM\SOFTWARE\Authyo\Gatekeeper\DisableSelfHeal = 1
and stops/disables the Authyo RDP Guard Heartbeat service — both
are required, because the service's tamper guard otherwise restores
the registration within 15 minutes. Neither is undone by a later
install: before reinstalling, delete DisableSelfHeal and set the
service back to Automatic, or the new install will not self-heal.
Reboot (or lock+unlock) afterward and sign in with the normal password.
Install-media recovery (last resort): boot from Windows install
media → Repair → Command Prompt. The recovery environment's HKLM is
WinPE's own registry, so load the installed system's hive first.
Check which letter the OS is on with dir D:\Windows (under WinRE it is
usually D:, not C:) and substitute it below:
```
reg load HKLM\OFFSW D:\Windows\System32\config\SOFTWARE
reg add "HKLM\OFFSW\Authyo\Gatekeeper" /v DisableSelfHeal /t REG_DWORD /d 1 /f
reg delete "HKLM\OFFSW\Microsoft\Windows\CurrentVersion\Authentication\Credential Provider Filters\{B251F0AF-6D20-4C4D-90ED-4ADE0D8256D7}" /f
reg delete "HKLM\OFFSW\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\{B251F0AF-6D20-4C4D-90ED-4ADE0D8256D7}" /f
reg delete "HKLM\OFFSW\Classes\CLSID\{B251F0AF-6D20-4C4D-90ED-4ADE0D8256D7}" /f
reg unload HKLM\OFFSW
```
→ reboot and sign in with the normal Windows password.

⚠️ Delete all three keys, and set DisableSelfHeal first. Removing
only the Credential Providers key leaves the filter registered — on
RDP that still hides every other credential provider while ours is now
unregistered, leaving a logon screen with no usable tile at all, which
is worse than where you started. And without DisableSelfHeal, the
heartbeat service's tamper guard restores every value at the next boot, so
the gate simply comes back.

Uninstall

Which method you need depends on whether Windows is running normally.

Situation	Method	Works?
Windows running normally	Settings → Apps → Uninstall	✅ Yes — the normal way
Locked out at the logon screen	Console/serial, or Safe Mode + `authyo-rescue.ps1`	✅ Yes
Safe Mode, via Add/Remove Programs	needs Windows Installer enabled first	⚠️ Not by default
WinRE / "Repair your computer"	nothing to uninstall — Windows is not running	❌ No — offline registry edit only

Whichever method you use: RDP Guard can only be removed by the same
administrator account that installed it (or by a deployment tool running as
SYSTEM). Any other admin gets a refusal. To clear that lock:
Remove-ItemProperty 'HKLM:\SOFTWARE\Authyo\Gatekeeper' -Name InstallOwnerSid -Force

Normal uninstall (Windows running)

Settings → Apps → Installed apps → Authyo RDP Guard → Uninstall

Use Settings rather than a script: the portal ships an .exe bootstrapper which
registers its own Add/Remove entry alongside the MSI's, and Settings removes
the right one. A Win32_Product script removes only the MSI and leaves the
bootstrapper's entry orphaned.

The uninstaller stops and removes the Authyo RDP Guard Heartbeat service, the
Authyo DLLs, the registry entries, the Start Menu shortcut and the Add/Remove
entry. It does not remove C:\ProgramData\Authyo\Gatekeeper\ (your
config.json, trust.db and TOTP secrets), so a reinstall can pick up where you
left off. For a full purge afterwards:

Remove-Item 'C:\ProgramData\Authyo' -Recurse -Force

If you disabled NLA for RDP and are removing RDP Guard, re-enable it:

Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp' `
    -Name UserAuthentication -Value 1

After uninstall the next Win+L shows only the standard Windows password tile. No
reboot required.

Safe Mode

Safe Mode always gets you in — Windows does not load third-party credential
providers there, so the plain password tile is available to any local admin. But
Add/Remove Programs does not work in Safe Mode: MSIServer is not one of the
services Safe Mode starts, so Settings → Apps and msiexec /x both fail with
"The Windows Installer Service could not be accessed" (error 1601).

Two options:

Run authyo-rescue.ps1 (below). It needs no Windows Installer, and it is
what restores the password login. Then run a normal uninstall later, once
Windows is booting normally, to remove the files and the Add/Remove entry.

Or enable Windows Installer in Safe Mode first, then uninstall normally:

reg add "HKLM\SYSTEM\CurrentControlSet\Control\SafeBoot\Minimal\MSIServer" /VE /T REG_SZ /F /D "Service"
reg add "HKLM\SYSTEM\CurrentControlSet\Control\SafeBoot\Network\MSIServer" /VE /T REG_SZ /F /D "Service"
net start msiserver

WinRE / "Repair your computer"

You cannot uninstall from here. Windows is not running, so there is no
Windows Installer, no services and no Add/Remove Programs. The only thing
available is editing the installed system's registry offline — see
Recovery, step 5. That removes the tile; do a
proper uninstall once the machine boots normally again.

`authyo-rescue.ps1` — the emergency tool

Ships in the release package next to the installer. Keep a copy off the
server, with your other break-glass material: during a real lock-out you cannot
download it from the machine that is refusing your login.

It is not the normal way to uninstall. It exists for one job: get the standard
Windows password login back, even when the install is broken, the MSI will not
run, or you are in Safe Mode.

Run it elevated, from the console, serial console, or Safe Mode:

powershell -ExecutionPolicy Bypass -File .\authyo-rescue.ps1

Add -PurgeData to also delete C:\ProgramData\Authyo\Gatekeeper\
(config, trust cache and every Google Authenticator secret on this server).
Leave it off unless you want a completely clean slate.

What it does, in order — every step is best-effort, so a later step still runs if
an earlier one fails:

Step	Action	Why
0	Requires elevation; refuses to run otherwise	The keys it edits are machine-wide
1	Tries a clean MSI uninstall	The tidy path when it is available. Skipped automatically in Safe Mode, where Windows Installer cannot run
1b	Sets `DisableSelfHeal=1`, stops and disables the heartbeat service	Mandatory. The service's tamper guard re-creates the registration within 15 minutes, and at boot. Without this, the rescue silently undoes itself
2	Force-deletes the three registration keys — Credential Provider Filters, Credential Providers, and the CLSID	This is what restores the password login, and it works even when step 1 failed
3	Deletes the data folder — only with `-PurgeData`	Config is kept by default so you can reinstall cleanly
4	Re-checks the keys and reports COMPLETE or PARTIAL	PARTIAL means a permissions problem; it prints the keys to delete by hand

Then reboot (or lock and unlock) and sign in with your normal Windows
password.

⚠️ Before you reinstall, undo step 1b. DisableSelfHeal and the disabled
service are not reverted by a later install, so the new install will not
self-heal its registration:
Remove-ItemProperty 'HKLM:\SOFTWARE\Authyo\Gatekeeper' -Name DisableSelfHeal -Force
Set-Service AuthyoGatekeeperHeartbeat -StartupType Automatic

The script changes nothing about your Windows accounts or passwords. It only
removes Authyo's hooks into the logon screen.

Troubleshooting

The Authyo tile doesn't appear on the lock screen

Check the portal first — this is the most common cause. If the server was
never activated, its seat was Deactivated / Removed, or its license
lapsed, was suspended or cancelled (or was Blocked and the paid period
has since ended), the agent hides its own tile on purpose — the "step aside"
state. Sign-in falls back to the plain Windows password with no OTP, and
reinstalling will not bring the tile back.

Confirm it either way:

The last GATE_STEPASIDE line in
C:\ProgramData\Authyo\Gatekeeper\logs\gatekeeper.log
The Configurator's Setup tab — a red banner reads "This server is
DEACTIVATED — OTP is NOT being enforced"

The fix is on the portal: re-activate the server, or renew the license. The tile
returns on the next sign-in.

Only once the server is genuinely active, check the box itself:

# Confirm the config exists and is readable
Get-Content 'C:\ProgramData\Authyo\Gatekeeper\config.json'

# Confirm the Credential Provider is registered
$clsid = '{B251F0AF-6D20-4C4D-90ED-4ADE0D8256D7}'
Test-Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\$clsid"

# Confirm the .NET Desktop Runtime (8 or newer)
dotnet --list-runtimes   # expect Microsoft.WindowsDesktop.App 8.0.x

If all three are fine, run the Configurator's Diagnostics tab — it
pinpoints the failing prerequisite. Note that it checks prerequisites only: it
does not flag a deactivated seat, so rule that out first.

"OTP did not verify"

OTP expired (default 5 minutes) or you used an older one — use the most
recent code (a resend invalidates the previous one).
Retry up to 5 times within the maskId's lockout budget.

"Windows rejected the credentials"

The OTP verified but Windows didn't accept the password:

Confirm the username matches a local or domain account.
Confirm the password on the standard tile.
Microsoft Account (MSA) sign-ins use the MSA tile, not the Authyo tile.

RDP signs in WITHOUT an OTP

NLA is enabled — it bypasses credential providers. Disable NLA (see
RDP).

RDP is stuck at logon / "Cannot reach Authyo"

The machine couldn't reach app.authyo.io and blockOnAuthyoUnreachable
is true (the default, fail-closed). Confirm DNS/HTTPS/firewall:

nslookup app.authyo.io
Invoke-WebRequest https://app.authyo.io/ -UseBasicParsing

Use a break-glass path to get in (TOTP works offline).

⚠️ Do not fix this by hand-editing config.json. Policy sync overwrites
blockOnAuthyoUnreachable from the portal on every sync
(PolicyManager.ApplyTo), so a local edit reverts on the next check-in and the
server locks up again — usually at the worst moment. Change it where it is
owned: the portal's policy editor, "Block sign-in if Authyo is unreachable
(recommended — fail closed)". Clearing that checkbox is fail-open —
not recommended for production — and note that with server-authoritative
policy enabled, a stale or unverified policy also falls back to this setting.

Collecting a diagnostics bundle for support

Open the Configurator → Diagnostics tab → Save diagnostics for support.
It writes a single .zip — diagnostic results, agent logs, a redacted copy
of config.json, and version/OS details — then opens Explorer with the file
selected. Email it to support@authyo.io.

If the Configurator will not start, collect the same material by hand:

Compress-Archive `
    -Path 'C:\ProgramData\Authyo\Gatekeeper\logs',
          'C:\ProgramData\Authyo\Gatekeeper\config.json' `
    -DestinationPath "C:\authyo-diagnostics-$(Get-Date -Format yyyyMMdd-HHmmss).zip"

⚠️ The raw config.json is not redacted. The secret blobs
(clientSecretEncrypted, nodeKeyEncrypted, secretEncrypted) are DPAPI
machine-scope and useless off this box — but the file also holds every OTP
contact's name, email address and phone number in clear text, plus the
RDPG- license key, the exempt-user list, the shared team account name and
the webhook URL. Review it, and strip anything you would rather not send,
before emailing it. The Configurator's own button redacts for exactly this
reason — prefer it when you can.

Security notes

Client Secret + TOTP secrets on disk: encrypted with Windows DPAPI
machine-scope. Only the local SYSTEM context (which LogonUI runs as) can
decrypt. The blobs are useless if exfiltrated to another machine.
OTP transport: HTTPS to app.authyo.io, TLS 1.2+, server-cert
validated by the default Windows trust store.
JWT verification: every OTP/backup-code verify response carries a
JWT signed with HMAC-SHA256 using your Client Secret. RDP Guard validates
the signature locally — a forged "success" response without a valid
JWT is rejected even if the HTTP body says success: true.
TOTP break-glass: verified fully offline (RFC 6238) with a
single-use replay guard (lastUsedStep) — a code can't be replayed.

Safe Mode signs in without an OTP

Windows does not load third-party credential providers in Safe Mode. That is what
makes Safe Mode a guaranteed recovery route if the tile ever misbehaves — and it
is the same reason Safe Mode is a way to sign in without an OTP. The Windows
password is still required; the second factor is not.

This is Windows behaviour, not something RDP Guard can override. Every
third-party MFA credential provider has it. We state it plainly rather than let
you discover it in an audit:


Needs a valid Windows password	Yes — Safe Mode is not an authentication bypass
Needs the OTP	No
Needs access to the boot menu	Yes — physical console, hypervisor console, or serial console
Possible over plain RDP	No — you cannot choose Safe Mode from an RDP session

On a cloud server this is a high bar. Selecting Safe Mode needs console-level
access before Windows starts, which on EC2/Azure means the provider's console or
a deliberate boot-configuration change — both of which are themselves privileged
operations you can audit. On a physical machine at a desk, it is trivial.

What to do about it, in order of how much it costs you:

Treat console access as equivalent to admin access. Anyone who can boot
the machine to Safe Mode and knows a password is inside. Lock down the
hypervisor/iLO/serial console the same way you lock down Domain Admin.
BitLocker with a TPM+PIN. The PIN is required before Windows starts, so a
Safe Mode boot cannot happen unattended, and boot-configuration edits trigger
recovery-key prompts.
Alert on Safe Mode boots. Windows records the boot type; a Safe Mode boot
on a production server is worth an alert whether or not it was authorised.

⚠️ Do not "fix" this by removing Safe Mode. It is the recovery path this
guide depends on — disabling it means a broken credential provider, an expired
licence, or a lost install account leaves you with no way in short of booting
from install media. The trade is deliberate: a bypass that needs console access
and a password, in exchange for never being permanently locked out of your own
server.

Server-authoritative policy (optional, off by default): when enabled,
the server's signed policy (HMAC-SHA256, with anti-rollback versioning)
must be freshly verified before local exempt/trust short-circuits are
honored, so a local config.json edit can't grant a bypass. Ship it
off unless you specifically need it.
Trust device cache: trust.db is a SQLite file storing source-IP +
username fingerprints (no passwords, no tokens). Bounded TTL, default 0.
No bypass of Windows auth: RDP Guard layers OTP on top of the
standard Windows logon. A valid OTP with a wrong Windows password is
still rejected by LSA.

For the full threat model, see SECURITY.md.

Support

Documentation: https://app.authyo.io/gatekeeper/downloads
Email: support@authyo.io
License: Apache-2.0 (the Linux PAM module) + Proprietary (the Windows
Credential Provider). See LICENSE in the install directory.

RDP Guard : Windows