Skip to main content
NetBird Selfservice implements multiple layers of security to protect your VPN network infrastructure and ensure that only authorized users can access and manage network resources.

​
Core Security Features

The application provides enterprise-grade security through several key mechanisms:

Domain Restriction

Limit access to users from specific email domains using OAuth authentication

Address Validation

Comprehensive validation prevents dangerous or invalid network addresses

Ownership Controls

Users can only modify resources they created, with admin override

API Token Security

Secure storage and handling of NetBird API credentials

​
Authentication & Authorization

​
OAuth Integration

NetBird Selfservice uses OAuth 2.0 for secure authentication:
  • Google Workspace Integration: Primary authentication method via Google OAuth
  • Domain Restriction: Optional enforcement of allowed email domains
  • Stateless Sessions: Secure session management with Laravel Sanctum
  • Automatic User Provisioning: Users are created on first successful login
The OAuth implementation is extensible and supports any Laravel Socialite provider, not just Google.

​
Role-Based Access Control

The application implements a simple but effective permission model: Regular Users:
  • View their own resources
  • Create new resource requests (requires approval)
  • Edit and delete their own resources
  • Cancel pending requests
Administrators:
  • All regular user permissions
  • Approve or deny resource requests
  • Manage all resources regardless of owner
  • Access activity logs
  • Direct resource creation (no approval needed)
Admin access is granted based on the NETBIRD_ADMIN_EMAIL environment variable. Ensure this is set to a trusted email address.

​
Address Validation & Blocking

​
Blocked Address Ranges

To protect your network infrastructure, the following address ranges are automatically blocked: 
// Source: app/Rules/ValidResourceAddress.php:17-30
private array $blockedCidrs = [
    '0.0.0.0/0',      // All IPv4 traffic
    '::/0',           // All IPv6 traffic
    '0.0.0.0/1',      // Half of all IPv4 traffic
    '128.0.0.0/1',    // Other half of all IPv4 traffic
    '10.0.0.0/8',     // Private network (Class A)
    '172.16.0.0/12',  // Private network (Class B)
    '192.168.0.0/16', // Private network (Class C)
    '127.0.0.0/8',    // Loopback
    '169.254.0.0/16', // Link-local
    '224.0.0.0/4',    // Multicast
    '240.0.0.0/4',    // Reserved
    '255.255.255.255/32', // Broadcast
];
These blocks prevent users from accidentally or maliciously routing all traffic through the VPN or exposing internal network ranges.

​
Validation Rules

Every resource address must pass validation:
  1. Format Validation: Must be a valid IPv4, IPv6, CIDR notation, or domain name
  2. Blocked Range Check: Compared against the blocked CIDR list
  3. Wildcard Prevention: Overly broad wildcards like * or *.* are rejected
  4. Domain Validation: Domain names must follow RFC standards (max 253 chars, labels max 63 chars)
// Source: app/Rules/ValidResourceAddress.php:37-61
public function validate(string $attribute, mixed $value, Closure $fail): void
{
    $value = trim((string) $value);

    if ($value === '') {
        $fail('The :attribute is required.');
        return;
    }

    // Check for blocked dangerous addresses
    if ($this->isBlockedAddress($value)) {
        $fail('The :attribute contains a blocked or dangerous address range.');
        return;
    }

    // Try to validate as IP, CIDR, or domain
    if (! $this->isValidIpv4($value)
        && ! $this->isValidIpv6($value)
        && ! $this->isValidCidr($value)
        && ! $this->isValidDomain($value)) {
        $fail('The :attribute must be a valid IP address, CIDR notation, or domain name.');
    }
}

​
Session Security

​
Session Management

NetBird Selfservice uses Laravel’s robust session management:
  • Database Storage: Sessions stored in database for scalability
  • 120-minute Default Lifetime: Configurable via SESSION_LIFETIME
  • HTTP-Only Cookies: Prevents XSS attacks by blocking JavaScript access
  • SameSite Protection: Default lax setting mitigates CSRF attacks
  • Session Regeneration: Token regenerated on logout to prevent fixation attacks
// Source: app/Http/Controllers/Auth/GoogleController.php:48-54
public function logout(): RedirectResponse
{
    Auth::logout();

    request()->session()->invalidate();
    request()->session()->regenerateToken();

    return redirect()->route('home');
}
For production environments, enable SESSION_SECURE_COOKIE=true to ensure cookies are only transmitted over HTTPS.

​
API Token Protection

​
NetBird API Token

The NETBIRD_API_TOKEN is the most sensitive credential in the application:
  • Full Network Access: Has complete control over your NetBird network
  • Environment Variable Storage: Never committed to version control
  • Server-Side Only: Token is never exposed to client-side code
  • Encrypted at Rest: Laravel encrypts sensitive environment variables
Critical Security Requirement:
  • Never commit .env files to version control
  • Rotate API tokens regularly
  • Use separate tokens for development and production
  • Limit token permissions in NetBird dashboard if possible

​
Generic Error Messages

To prevent information disclosure, the application implements generic error messaging: 
// Source: app/Http/Controllers/ResourceApprovalController.php:75-83
catch (\Exception $e) {
    report($e);

    return view('pages.approval-result', [
        'success' => false,
        'message' => 'An error occurred while creating the resource.',
        'resource' => $pendingResource,
    ]);
}
  • Internal Logging: Detailed errors logged server-side via report()
  • Generic User Messages: Users see friendly, non-technical error messages
  • No Stack Traces: Production mode hides detailed error information

​
Activity Logging

All resource operations are logged for audit purposes:
  • Comprehensive Tracking: Create, update, delete, approve, deny actions
  • User Attribution: Every action links to the performing user
  • Resource Details: Full details of what changed and when
  • Tamper-Resistant: Logs are append-only database records
Regularly review activity logs to identify suspicious patterns or unauthorized access attempts.

​
Domain Restriction Enforcement

When NETBIRD_ALLOWED_DOMAIN is configured, the application enforces strict domain checking: 
// Source: app/Http/Controllers/Auth/GoogleController.php:24-31
$allowedDomain = config('netbird.allowed_domain');
if ($allowedDomain) {
    $emailDomain = substr(strrchr($googleUser->getEmail(), '@'), 1);
    if (strcasecmp($emailDomain, $allowedDomain) !== 0) {
        return redirect()->route('login')
            ->withErrors(['email' => 'Only users with @'.$allowedDomain.' email addresses are allowed.']);
    }
}
  • Case-Insensitive Matching: Prevents bypass via case variation
  • Post-OAuth Check: Validates after successful OAuth but before account creation
  • Rejection Message: Clear feedback to unauthorized users
Domain restriction is optional but strongly recommended for production deployments to prevent unauthorized access.

​
Production Security Checklist

Before deploying to production:
  • Set APP_ENV=production
  • Set APP_DEBUG=false
  • Configure NETBIRD_ALLOWED_DOMAIN
  • Use HTTPS exclusively (APP_URL with https://)
  • Enable SESSION_SECURE_COOKIE=true
  • Rotate APP_KEY from default
  • Secure NETBIRD_API_TOKEN with proper permissions
  • Set strong database credentials
  • Configure proper firewall rules
  • Enable log monitoring and alerting
  • Set up regular database backups
  • Review and test OAuth callback URLs

​
Next Steps

Configuration

Learn how to configure security settings

Best Practices

Discover security best practices and recommendations

Build docs developers (and LLMs) love

Get started for freeTalk to us