Skip to main content
WireGuard Easy supports Time-based One-Time Password (TOTP) two-factor authentication to add an extra layer of security to user accounts.

​
Overview

Two-factor authentication requires users to provide both their password and a time-based code from an authenticator app when logging in.

​
Benefits

Enhanced Security

Protects against password compromise and unauthorized access

TOTP Standard

Compatible with all standard authenticator apps

User Control

Each user manages their own 2FA settings

Recovery Options

Can be disabled with password verification

​
Enabling 2FA

Users can enable 2FA from their profile settings:
1

Navigate to Profile

Click your user menu in the top right and select “My Profile” or navigate to /me.
2

Locate 2FA Section

Scroll down to the “Two-Factor Authentication” section.
3

Click Enable 2FA

Click the “Enable 2FA” button to begin the setup process.
4

Scan QR Code

A QR code appears on screen. Scan it with your authenticator app:Recommended Apps:
  • Google Authenticator (iOS/Android)
  • Microsoft Authenticator (iOS/Android)
  • Authy (iOS/Android/Desktop)
  • 1Password (iOS/Android/Desktop)
  • Bitwarden (iOS/Android/Desktop)
5

Save Backup Key

Write down or securely store the displayed backup key. This allows manual entry if QR scanning fails.
Store this key securely! It’s needed for recovery if you lose access to your authenticator app.
6

Enter Verification Code

Enter the 6-digit code from your authenticator app to verify setup.
7

Confirm Activation

Click “Enable 2FA” to complete activation. Your account is now protected with two-factor authentication.
After enabling 2FA, you’ll be required to enter a code from your authenticator app every time you log in.

​
Setting Up Authenticator Apps

Detailed setup instructions for popular authenticator apps:
1

Install the App

Download Google Authenticator:
2

Open the App

Launch Google Authenticator on your device.
3

Add Account

Tap the ”+” button and select “Scan a QR code”.
4

Scan QR Code

Point your camera at the QR code displayed in WireGuard Easy.
5

Account Added

The account appears with a 6-digit code that refreshes every 30 seconds.

​
Logging In with 2FA

Once 2FA is enabled, the login process requires an additional step:
1

Enter Credentials

On the login page, enter your username and password as usual.
2

Click Sign In

Submit the login form.
3

2FA Code Requested

If credentials are correct, an additional field appears requesting the 2FA code.
4

Open Authenticator App

Open your authenticator app and locate the WireGuard Easy entry.
5

Enter 6-Digit Code

Type the current 6-digit code into the 2FA field.
The code refreshes every 30 seconds. If it’s about to expire, wait for the new code to avoid timing issues.
6

Complete Login

Click “Sign In” again to complete authentication and access the interface.

​
Remember Me Option

The “Remember Me” checkbox on the login page:
  • Extends session duration
  • Still requires 2FA code on first login
  • Reduces frequency of re-authentication
  • Device-specific (doesn’t affect other devices)
Even with “Remember Me” enabled, 2FA is required for the initial login. Subsequent logins on the same device may not require a code until the session expires.

​
Disabling 2FA

Users can disable two-factor authentication from their profile:
1

Navigate to Profile

Go to your user profile at /me.
2

Locate 2FA Section

Scroll to the “Two-Factor Authentication” section.
3

Enter Current Password

For security, you must verify your identity by entering your current password.
4

Click Disable 2FA

Click the “Disable 2FA” button.
5

Confirm Deactivation

Confirm the action. Your account returns to password-only authentication.
Disabling 2FA reduces your account security. Only disable if absolutely necessary, and consider re-enabling as soon as possible.

​
Troubleshooting 2FA

​
Code Not Accepted

Problem: TOTP codes are time-sensitive. Clock drift causes invalid codes.Solution:
  • Ensure your device time is set to automatic
  • Verify the server time is correct
  • Check timezone settings on both devices
  • Use NTP to synchronize server clock
Test:
# On server, check time:
date

# Enable NTP synchronization:
sudo timedatectl set-ntp true
Problem: Each code can only be used once.Solution:
  • Wait for the next code (codes refresh every 30 seconds)
  • Don’t submit the same code multiple times
  • Ensure browser/app isn’t auto-retrying
Problem: Using code from a different account or service.Solution:
  • Verify you’re using the correct entry in your authenticator app
  • Check the account name matches your WireGuard Easy server
  • Delete and re-setup if you have duplicate entries
Problem: QR code scan didn’t properly register.Solution:
  • Disable and re-enable 2FA to get a new QR code
  • Try manual entry with the secret key
  • Use a different authenticator app
  • Check for app updates

​
Lost Access to Authenticator

Scenarios and Solutions:
If you have backup codes:
  • Use the backup code to log in
  • Disable 2FA
  • Re-enable with a new device
If you don’t have backup codes:
  • Contact your administrator
  • Admin can disable 2FA for your account
  • Re-enable 2FA after regaining access
Prevent Lockout: Before your device becomes unavailable, either export your authenticator accounts, enable cloud backup, or securely store backup codes.

​
Admin: Resetting User 2FA

Administrators can disable 2FA for locked-out users:
This feature is typically accessed through direct database manipulation or a future admin interface. Proceed with caution and verify user identity before resetting 2FA.

​
Security Best Practices

​
Choosing an Authenticator

Cloud Backup

Apps: Authy, 1Password, BitwardenPros: Recovery if device is lostCons: Depends on provider security

Local Only

Apps: Google Authenticator (without transfer)Pros: No cloud exposureCons: Difficult recovery

Multi-Device

Apps: 1Password, Bitwarden, AuthyPros: Access from multiple devicesCons: More devices to secure

Encrypted Vault

Apps: 1Password, BitwardenPros: Strong encryption, password protectedCons: Requires separate app subscription

​
Backup and Recovery

1

Save Backup Codes

When enabling 2FA, securely store the displayed secret key:
  • Write it down on paper
  • Store in a password manager
  • Keep in a safe or secure location
  • Never store in plain text on devices
2

Multiple Authenticators

For critical access, set up the same account in multiple apps:
  • Primary device authenticator
  • Backup device authenticator
  • Password manager with TOTP support
3

Test Before Logging Out

After enabling 2FA:
  • Open an incognito/private window
  • Test the login process
  • Verify codes work
  • Only close original session after confirming
4

Regular Reviews

Periodically verify your 2FA setup:
  • Ensure authenticator app is up to date
  • Test backup methods still work
  • Update backup codes if you re-enable 2FA

​
Technical Details

​
TOTP Algorithm

WireGuard Easy implements standard TOTP (RFC 6238): 
Algorithm: TOTP (Time-based One-Time Password)
Hashing: HMAC-SHA1
Code Length: 6 digits
Time Step: 30 seconds
Window: ±1 step (allows for clock drift)

​
QR Code Format

The generated QR code contains a TOTP URI: 
otpauth://totp/WireGuardEasy:username?secret=SECRET&issuer=WireGuardEasy
Components:
  • otpauth://totp/: Protocol and type
  • WireGuardEasy: Issuer name
  • username: User identifier
  • secret=SECRET: Base32-encoded secret key
  • issuer=WireGuardEasy: Issuer parameter

​
API Endpoints

Setup 2FA: 
POST /api/me/totp
Content-Type: application/json

{
  "type": "setup"
}

Response:
{
  "type": "setup",
  "uri": "otpauth://totp/...",
  "key": "BASE32SECRET"
}
Enable 2FA: 
POST /api/me/totp
Content-Type: application/json

{
  "type": "create",
  "code": "123456"
}

Response:
{
  "type": "created",
  "success": true
}
Disable 2FA: 
POST /api/me/totp
Content-Type: application/json

{
  "type": "delete",
  "currentPassword": "password123"
}

Response:
{
  "type": "deleted",
  "success": true
}

​
FAQ

No, WireGuard Easy only supports TOTP-based authentication through authenticator apps. SMS 2FA is considered less secure and is not implemented.
2FA is optional for each user. Administrators can encourage or require it through policy, but the system doesn’t enforce it by default.
Changing your password does not affect your 2FA setup. The same authenticator codes continue to work.
Yes! You can scan the QR code with multiple authenticator apps during initial setup. All apps generate the same valid codes.
TOTP is more secure than SMS 2FA and provides strong protection against:
  • Password-only attacks
  • Phishing (unless attacker performs real-time MITM)
  • Credential stuffing
  • Brute force attempts
Hardware keys (FIDO2/WebAuthn) are more secure but less convenient.

Build docs developers (and LLMs) love

Get started for freeTalk to us