defguard
  • Introduction
  • User documentation (help)
    • Configuring VPN
      • Defguard Desktop Client
        • Update instance
      • Other WireGuard® Clients
        • Configuring a device for new VPN Location manually
    • Password change / Reset
    • Enrollment & Onboarding
      • With internal Defguard SSO
      • With external SSO (Google/Microsoft/Custom)
    • Setting up 2FA/MFA
    • Desktop Client
    • CLI Client
  • Admin & features
    • Deploying your instance
      • One-line install script
      • Standalone package based installation
      • Docker images and tags
      • Docker Compose
      • Kubernetes
      • Upgrading
      • Gateway
        • Running gateway on MikroTik routers
      • Securing gRPC communication
      • OpenID RSA key
      • Configuration
      • Pre-production and development releases
      • High Availability and Failover
      • Health check
    • Features & configuration
      • Zero-Trust VPN with 2FA/MFA
        • Create/manage VPN Location
        • Network overview
        • Executing custom gateway commands
        • Multi-Factor Authentication (MFA/2FA)
          • MFA Architecture
        • Remote desktop client configuration
        • DNS and domains
      • Remote user enrollment
        • User onboarding after enrollment
      • SSO (OpenID Connect)
        • Portainer
        • Grafana setup
        • Proxmox
        • Matrix / Synapse
        • Django
        • MinIO
        • Vault
      • SMTP for email notifications
      • YubiKey Provisioning
      • Webhooks
      • Forward auth
      • SSH Authentication
      • Network devices
      • Gateway notifications
      • New version notifications
  • Troubleshooting Guide
    • Sending support information
    • Client Windows installer exit codes
    • Client "All traffic" connection issues
    • WebAuthn security keys
  • Enterprise Features
    • License
    • Enteprise features
      • Automatic (real time) desktop client configuration & sync
      • External OpenID providers
        • Google
        • Microsoft
        • Zitadel
        • Keycloak
        • JumpCloud
        • Okta
        • Custom
      • External OIDC secure enrollment
      • VPN & Client behavior customization
      • REST API
      • Access Control List
        • ACL Aliases
      • LDAP and Active Directory integration
        • Configuration
        • Settings table
        • Two-way LDAP and Active Directory synchronization
  • Tutorials
    • Step by step setting up a VPN server
      • Adding additional VPN locations
  • In depth
    • Roadmap
    • Architecture
      • How do VPN statistics work
      • Security concepts
  • For Developers
    • Contributing
    • Environment setup
    • Translations (core/web)
      • Switching language
      • Adding translations
  • Translations (client)
    • Adding translations
  • Contact us
    • Community & Support
Powered by GitBook
On this page
  • Pre-shared keys
  • Authorization process
  • Disconnecting peers

Was this helpful?

Edit on GitHub
  1. Admin & features
  2. Features & configuration
  3. Zero-Trust VPN with 2FA/MFA
  4. Multi-Factor Authentication (MFA/2FA)

MFA Architecture

PreviousMulti-Factor Authentication (MFA/2FA)NextRemote desktop client configuration

Last updated 4 months ago

Was this helpful?

WireGuard by itself does not have a concept of MFA or any additional authorization aside from validating peers cryptographically by their public and pre-shared keys.

Desktop Client MFA functionality is build entirely in defguard as a layer above the WireGuard protocol. Below is a brief explanation of its architecture and the authorization process itself.

Pre-shared keys

Our additional authorization is enabled by using . They are similar to peer public keys but while public keys identify a specific device and are static, pre-shared keys can be safely rotated.

When you configure your defguard location to require MFA it tells the Gateway to not add any peers (clients) to the WireGuard interface unless they are authorized and have a pre-shared key assigned.

On the other side a Client must have a valid pre-shared key (received after successful authorization) to establish a connection to the Gateway.

In typical REST API terms the pre-shared key can be thought of as an analogue to a session token.

Authorization process

To enable MFA functionality Desktop Client uses the to bridge communication between itself and defguard Core. Below is a diagram of the authorization process that is performed each time the Client initiates a connection to an MFA-enabled location:

Disconnecting peers

Since the WireGuard protocol is by definition stateless, there's no native concept of "connection" which would allow us to detect disconnected peers and remove them from the Gateway.

If a disconnected device is detected we mark it as unauthorized, delete the pre-shared key and remove the peer from Gateway interface, thus enforcing a "logout" for our MFA session.

As a workaround we use the latest handshake parameter available for each peer on a WireGuard interface. For each WireGuard connection both sides negotiate a "" about every 2 minutes. We can therefore assume that if the latest handshake value is more than 3 minutes (as a buffer for potential delays) the client has disconnected.

mini-session
pre-shared keys
proxy