Skip to main content
Multi-Factor Authentication (MFA) adds an additional layer of security to your NetBird network by requiring users to provide two or more verification factors to gain access.

​
MFA Through Identity Providers

NetBird leverages your configured identity provider’s MFA capabilities rather than implementing its own MFA system. This approach provides:
  • Centralized Security: Manage MFA policies in one place
  • Consistent Experience: Users use familiar MFA methods from your IdP
  • Advanced Features: Access IdP-specific features like adaptive authentication
  • Reduced Complexity: No separate MFA system to maintain

​
Supported MFA Methods by IdP

Different identity providers support various MFA methods:
Auth0 supports multiple MFA methods:
  • SMS one-time passwords (OTP)
  • Push notifications via Auth0 Guardian
  • Time-based OTP (TOTP) apps like Google Authenticator
  • Email OTP
  • WebAuthn/FIDO2 security keys
  • Biometric authentication
Configure MFA in your Auth0 dashboard under Security > Multi-factor Auth.

​
Enforcing MFA for NetBird Access

To require MFA for NetBird authentication:
1

Enable MFA in Your IdP

Configure and enable MFA in your identity provider’s admin console.
Test MFA with a small group of users first before enforcing organization-wide.
2

Set MFA Policy

Create an authentication policy that requires MFA for NetBird application access.Example for Auth0:
{
  "name": "NetBird MFA Enforcement",
  "actions": [{
    "action": "require-multifactor-authentication"
  }],
  "applications": ["netbird-client-id"]
}
3

Test Authentication

Verify users are prompted for MFA when logging into NetBird clients.
4

Monitor Compliance

Review authentication logs to ensure MFA is being used consistently.

​
IdP-Specific Configuration

​
Auth0 MFA Enforcement

// Create an Auth0 Rule to enforce MFA for NetBird
function(user, context, callback) {
  // Check if this is the NetBird application
  if (context.clientName === 'NetBird') {
    // Require MFA
    context.multifactor = {
      provider: 'any',
      allowRememberBrowser: false
    };
  }
  callback(null, user, context);
}

​
Azure AD Conditional Access

Create a Conditional Access policy:
  1. Navigate to Azure AD > Security > Conditional Access
  2. Create new policy:
    • Name: NetBird MFA Required
    • Users: Select target users/groups
    • Cloud apps: Select NetBird application
    • Grant: Require multi-factor authentication
  3. Enable the policy

​
Okta Sign-On Policy

  1. Go to Security > Authentication Policies
  2. Add Rule to your NetBird app:
    • Rule Name: Require MFA
    • Prompt for factor: Every sign on
    • Re-authentication frequency: Every time

​
User Enrollment

Guide users through MFA enrollment:
1

Notify Users

Inform users about upcoming MFA requirement and enrollment deadline.
2

Provide Instructions

Share step-by-step guides for enrolling MFA devices with your IdP.
3

Offer Support

Set up help desk resources to assist with enrollment issues.
4

Grace Period

Consider a grace period where MFA is encouraged but not required.

​
Backup Authentication Methods

Always configure backup authentication methods to prevent lockouts:

Backup Codes

Generate one-time backup codes users can print and store securely.

Multiple Devices

Allow users to register multiple MFA devices.

Alternative Methods

Enable SMS or email as fallback when primary method unavailable.

Admin Recovery

Establish admin procedures for MFA reset requests.

​
Periodic Re-Authentication

NetBird supports periodic re-authentication to ensure users remain authorized:

​
Login Expiration

Peers added via SSO can be configured to require periodic re-authentication: 
{
  "Settings": {
    "PeerLoginExpirationEnabled": true,
    "PeerLoginExpiration": 604800  // 7 days in seconds
  }
}
  • Minimum: 1 hour (3600 seconds)
  • Maximum: 180 days (15552000 seconds)
  • Only applies to peers added via SSO login (not setup keys)

​
Inactivity Expiration

Automatically expire inactive peer sessions: 
{
  "Settings": {
    "PeerInactivityExpirationEnabled": true,
    "PeerInactivityExpiration": 2592000  // 30 days in seconds
  }
}
Peers added with setup keys are not subject to login expiration. Only peers added through interactive SSO login can be expired and require re-authentication.

​
Monitoring and Compliance

​
Authentication Logs

Monitor MFA usage through your IdP’s logging:
  • Track successful MFA authentications
  • Identify failed MFA attempts
  • Review MFA enrollment rates
  • Detect anomalous authentication patterns

​
Compliance Reporting

Generate reports to demonstrate MFA compliance:
Use Auth0 logs to export authentication events:
# Export Auth0 logs via Management API
curl -X GET 'https://YOUR_DOMAIN.auth0.com/api/v2/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data-urlencode 'q=type:f' \
  --data-urlencode 'fields=date,type,description,user_name'
Access Azure AD sign-in logs:
  1. Navigate to Azure AD > Monitoring > Sign-ins
  2. Filter by NetBird application
  3. Export to CSV or connect to Azure Sentinel for advanced analytics
Query Okta system logs:
# Get MFA events via Okta API
curl -X GET 'https://YOUR_DOMAIN.okta.com/api/v1/logs' \
  -H 'Authorization: SSWS YOUR_API_TOKEN' \
  --data-urlencode 'filter=eventType eq "user.authentication.auth_via_mfa"'

​
Troubleshooting

Possible causes:
  • MFA policy not applied to NetBird application
  • User already has active session with valid MFA
  • Policy exceptions or exclusions in effect
Solutions:
  • Verify policy assignment in IdP
  • Force user logout and re-login
  • Review policy conditions and exclusions
Possible causes:
  • Time synchronization issues with TOTP
  • Network connectivity problems
  • Incompatible authenticator app
Solutions:
  • Ensure device time is synchronized (NTP)
  • Check network firewall rules
  • Try alternative MFA method
  • Use IdP’s recommended authenticator app
Recovery steps:
  1. Verify user identity through established procedures
  2. Use admin console to reset MFA for the user
  3. Have user re-enroll MFA devices
  4. Provide backup codes for future use
Document your MFA reset procedures and require proper authorization for security.

​
Best Practices

1

Phased Rollout

Deploy MFA in phases:
  • Start with IT/admin users
  • Expand to privileged users
  • Roll out to all users
2

User Education

Provide comprehensive training:
  • Explain why MFA is important
  • Demonstrate enrollment process
  • Share troubleshooting resources
3

Multiple Factors

Encourage users to register multiple MFA methods for redundancy.
4

Regular Audits

Periodically review:
  • MFA enrollment rates
  • Authentication success rates
  • Backup method usage
  • Policy effectiveness
5

Adaptive Authentication

Leverage IdP adaptive authentication features:
  • Risk-based MFA prompts
  • Device trust evaluation
  • Location-based policies
  • Impossible travel detection

​
Next Steps

Posture Checks

Add device security requirements

Access Control

Configure network access policies

Build docs developers (and LLMs) love

Get started for freeTalk to us