VPN Selfservice

BETA SOFTWARE

This software is provided "as is" without warranty of any kind, express or implied. This is beta software and may contain bugs, errors, or security vulnerabilities. Use at your own risk.

A self-service web application for managing NetBird VPN network resources. Allows employees to request IP addresses, subnets, or domains to be added to the VPN network for accessing customer resources.

Features

• Resource Management: Add, edit, and delete VPN network resources (IPs, CIDRs, domains)
• Approval Workflow: Non-admin users submit requests that require admin approval
• Google OAuth: Secure authentication via Google Workspace
• Domain Restriction: Limit access to specific email domains
• Activity Logging: Track all resource changes
• Ownership Controls: Users can only modify their own resources

Screenshots

Requirements

• PHP 8.3+
• Composer
• Node.js & npm
• MySQL/MariaDB or SQLite
• NetBird account with API access
• Google Cloud Console project for OAuth // Or any other Laravel Socialite Supported OAuth Provider

Installation

# Clone the repository
git clone <repository-url>
cd netbird-ip

# Install dependencies
composer install
npm install

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

# Run migrations
php artisan migrate

# Build assets
npm run build

Configuration

Environment Variables

APP_NAME="VPN Selfservice"
APP_URL=https://your-domain.test

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=netbird_ip
DB_USERNAME=root
DB_PASSWORD=

# Google OAuth (Required)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.test/auth/google/callback

# NetBird API (Required)
NETBIRD_API_URL=https://api.netbird.io
NETBIRD_API_TOKEN=your-api-token
NETBIRD_NETWORK_ID=your-network-id
NETBIRD_NETWORK_NAME="Your Network Name"

# NetBird Settings
NETBIRD_ADMIN_EMAIL=admin@example.com
NETBIRD_EGRESS_IP=99.99.99.99
NETBIRD_RESOURCE_GROUP_NAME="Resources for Employees"
NETBIRD_USER_GROUP_NAME="Employees"

# Security (Recommended)
NETBIRD_ALLOWED_DOMAIN=example.com

OAuth Setup // Google Example

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. Select Web application
6. Add authorized redirect URI: https://your-domain.test/auth/google/callback
7. Copy the Client ID and Client Secret to your .env file

NetBird API Setup

1. Log in to your NetBird dashboard
2. Go to Settings > Access Tokens
3. Create a new API token with appropriate permissions
4. Copy the token to NETBIRD_API_TOKEN
5. Find your Network ID in the URL or network settings
6. Create the required groups in NetBird:
   • A user group (e.g., "Employees") - users who can access resources
   • A resource group (e.g., "Resources for Employees") - where resources are assigned

Usage

For Regular Users

1. Sign in with your Google account
2. Click "New Resource" to request a new resource
3. Enter the resource details (name, IP/domain, description)
4. Wait for admin approval
5. Once approved, the resource is accessible via VPN

For Admins

Admins (configured via NETBIRD_ADMIN_EMAIL) can:

• Create resources directly without approval
• Approve or deny pending requests
• Edit or delete any resource
• View the activity log

Security

Implemented Measures

• Domain Restriction: Only users with emails from NETBIRD_ALLOWED_DOMAIN can sign in
• Ownership Checks: Users can only modify their own resources
• Address Validation: Validates IPs, CIDRs, and domain names
• Blocked Addresses: Dangerous ranges like 0.0.0.0/0, private networks, and loopback are blocked
• Generic Error Messages: Internal errors are logged but not exposed to users

Recommendations

1. Always set NETBIRD_ALLOWED_DOMAIN to restrict access
2. Keep NETBIRD_API_TOKEN secure - it has full network access
3. Ensure only trusted users have the admin email
4. Regularly review the activity log
5. Run security audits periodically

Development

# Start development server
composer run dev

# Run tests
php artisan test

# Format code
vendor/bin/pint

License

MIT