Network Configuration - Nexus Access Vault

Overview

Nexus Access Vault supports network isolation, allowing you to restrict access to internal VPN networks only. This guide covers setting up Netbird VPN integration and configuring the application for VPN-only access.

Security Best Practice: For production deployments handling sensitive access management, we strongly recommend restricting access to an internal VPN network only.

Network Modes

Nexus Access Vault supports two network modes:

Internal Mode

Access restricted to VPN network only. Users must be connected to your Netbird/VPN to access the portal.

Public Mode

Open to public internet. Suitable for development or when using other security controls.

Set the mode using the VITE_NETWORK_MODE environment variable:

# Internal mode (VPN required)
VITE_NETWORK_MODE="internal"

# Public mode
VITE_NETWORK_MODE="public"

Netbird VPN Setup

Netbird is a modern, WireGuard-based VPN solution that’s perfect for securing Nexus Access Vault. This section covers the complete setup.

Prerequisites

Netbird Account

Create a free account at https://netbird.io or deploy your own self-hosted Netbird instance.

Setup Key

Generate a setup key in the Netbird dashboard:

Navigate to Setup Keys
Click Create Setup Key
Set expiration and usage limits
Copy the setup key for use during installation

Server Installation

Ubuntu/Debian
CentOS/RHEL
Docker

# Install Netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect to your network
netbird up --setup-key <your-setup-key>

# Verify connection
netbird status

# Install Netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect to your network
netbird up --setup-key <your-setup-key>

# Verify connection
netbird status

docker run -d \
  --name netbird \
  --cap-add=NET_ADMIN \
  --network host \
  -e NB_SETUP_KEY=<your-setup-key> \
  netbirdio/netbird:latest

See ZITADEL_NETBIRD_SETUP.md:105-111 for the basic installation commands.

Get Your Netbird IP

After connecting to Netbird, get your assigned IP address:

netbird status

Output will show something like:

Peer name: nexus-vault-server
Status: Connected
NetBird IP: 100.64.1.10
Public key: AbCdEf123...

Note the NetBird IP - this is what you’ll use for VITE_INTERNAL_HOST. See ZITADEL_NETBIRD_SETUP.md:113-118

Application Network Configuration

Environment Variables

Configure the network mode and internal host:

.env

# Network Configuration
VITE_NETWORK_MODE="internal"
VITE_INTERNAL_HOST="100.64.1.10"  # Your Netbird IP

See .env.example:14-18 and Environment Variables for details.

Vite Server Configuration

The default Vite configuration binds to all interfaces:

vite.config.ts

export default defineConfig({
  server: {
    host: "::",  // Binds to all IPv6 and IPv4 interfaces
    port: 8080,
  },
});

See vite.config.ts:8-11

Binding to :: (all interfaces) allows connections from both localhost and the Netbird network. The firewall will restrict external access.

Production: Bind to Specific Interface

For production deployments, you can bind only to the Netbird interface:

vite.config.ts

export default defineConfig({
  server: {
    host: "100.64.1.10",  // Your Netbird IP only
    port: 8080,
  },
});

See ZITADEL_NETBIRD_SETUP.md:120-138 for server binding recommendations.

Firewall Configuration

Configure your firewall to allow connections only from the Netbird network.

UFW (Ubuntu)

# Allow from Netbird subnet (100.64.0.0/10 is Netbird's default)
sudo ufw allow from 100.64.0.0/10 to any port 8080

# Deny all other connections to port 8080
sudo ufw deny 8080

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

See ZITADEL_NETBIRD_SETUP.md:140-148

firewalld (CentOS/RHEL)

# Create a rich rule to allow Netbird subnet
sudo firewall-cmd --permanent --add-rich-rule='
  rule family="ipv4"
  source address="100.64.0.0/10"
  port port="8080" protocol="tcp" accept'

# Block all other traffic to 8080
sudo firewall-cmd --permanent --add-rich-rule='
  rule family="ipv4"
  port port="8080" protocol="tcp" reject'

# Reload firewall
sudo firewall-cmd --reload

iptables

# Allow from Netbird subnet
sudo iptables -A INPUT -p tcp -s 100.64.0.0/10 --dport 8080 -j ACCEPT

# Deny all other connections
sudo iptables -A INPUT -p tcp --dport 8080 -j DROP

# Save rules
sudo iptables-save > /etc/iptables/rules.v4

Nginx Reverse Proxy

For production deployments, use Nginx as a reverse proxy with SSL termination.

Basic Configuration

/etc/nginx/sites-available/nexus-vault

server {
    listen 100.64.1.10:80;
    server_name vault.internal.company.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SSL/TLS Configuration

/etc/nginx/sites-available/nexus-vault-ssl

server {
    listen 100.64.1.10:443 ssl http2;
    server_name vault.internal.company.com;

    # SSL certificates
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Proxy settings
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 100.64.1.10:80;
    server_name vault.internal.company.com;
    return 301 https://$server_name$request_uri;
}

See ZITADEL_NETBIRD_SETUP.md:150-170 for Nginx configuration example. Enable the site:

sudo ln -s /etc/nginx/sites-available/nexus-vault-ssl /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Internal DNS Configuration

For easier access, configure internal DNS to resolve a friendly name to your Netbird IP.

Using Netbird’s Built-in DNS

Netbird supports DNS management:

Navigate to DNS in Netbird dashboard
Click Add Nameserver
Add your internal domain records
Map vault.internal.company.com → 100.64.1.10

Using /etc/hosts

For simple setups, add to each client’s /etc/hosts:

# Add to /etc/hosts
100.64.1.10  vault.internal.company.com

Using Pi-hole or AdGuard Home

If you run Pi-hole or AdGuard Home on your network:

Add a local DNS record
Domain: vault.internal.company.com
IP Address: 100.64.1.10

Authentication Configuration

Zitadel Redirect URI

When using VPN-only access, update your Zitadel redirect URI to use the internal address:

.env

VITE_ZITADEL_REDIRECT_URI="http://100.64.1.10:8080/auth/callback"

# Or if using internal DNS:
VITE_ZITADEL_REDIRECT_URI="https://vault.internal.company.com/auth/callback"

Important: The redirect URI must be added to the allowed redirect URIs in your Zitadel application configuration.

See ZITADEL_NETBIRD_SETUP.md:18-23 and .env.example:8-12

Update Zitadel Application

In your Zitadel instance:

Navigate to your OIDC application
Go to Redirect URIs
Add: http://100.64.1.10:8080/auth/callback (or your internal domain)
Save changes

Client Access

Installing Netbird on Client Devices

Users need Netbird installed to access the portal:

Windows
macOS
Linux
iOS/Android

Download from https://netbird.io/downloads
Run installer
Enter setup key or login with SSO
Connect to network

# Using Homebrew
brew install netbird

# Connect to network
netbird up --setup-key <setup-key>

# Install
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect
netbird up --setup-key <setup-key>

Accessing the Portal

Once connected to Netbird, users can access the portal:

http://100.64.1.10:8080

# Or if using internal DNS:
https://vault.internal.company.com

See ZITADEL_NETBIRD_SETUP.md:172-183 for user flow.

User Flow

Connect to VPN

User connects to Netbird VPN using the Netbird client.

netbird status
# Should show: Status: Connected

Access Portal

User navigates to the internal IP or domain:

http://100.64.1.10:8080

Authenticate with Zitadel

User clicks “Sign in with Kappa4 Manager” and is redirected to Zitadel for authentication.

Redirected Back

After authentication, user is redirected back to the portal via the callback URL.

Access Dashboard

User sees their dashboard with access to resources based on their groups and permissions.

See ZITADEL_NETBIRD_SETUP.md:172-183

Alternative VPN Solutions

While this guide focuses on Netbird, you can use other VPN solutions:

Tailscale

Tailscale is another WireGuard-based VPN similar to Netbird:

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Connect
sudo tailscale up

# Get IP
tailscale ip -4

Use the Tailscale IP for VITE_INTERNAL_HOST.

WireGuard

For a self-hosted solution, use WireGuard directly:

Set up WireGuard server
Configure client peers
Use WireGuard subnet (e.g., 10.0.0.0/24) in firewall rules
Use server’s WireGuard IP for VITE_INTERNAL_HOST

OpenVPN

OpenVPN is a traditional VPN solution:

Set up OpenVPN server
Distribute client certificates
Configure firewall to allow OpenVPN subnet
Use server’s VPN IP for VITE_INTERNAL_HOST

Testing Network Isolation

Test VPN Access

From a device connected to VPN:

# Should succeed
curl http://100.64.1.10:8080

Test External Access

From a device NOT connected to VPN:

# Should fail (connection refused/timeout)
curl http://YOUR_PUBLIC_IP:8080

If external access works, review your firewall rules. The application should be accessible ONLY via VPN.

Troubleshooting

Cannot access portal from VPN

Verify Netbird is connected: netbird status
Check Netbird IP: netbird status | grep IP
Test server connectivity: ping 100.64.1.10
Verify application is running: curl localhost:8080
Check firewall allows Netbird subnet: sudo ufw status
Ensure server is bound to correct interface

Authentication redirect fails

Verify VITE_ZITADEL_REDIRECT_URI uses internal IP/domain
Check redirect URI is added in Zitadel application
Ensure redirect URI matches exactly (http vs https, trailing slashes)
Test Zitadel is accessible from server: curl https://manager.kappa4.com
Check browser console for OIDC errors

External access not blocked

Verify firewall rules are active: sudo ufw status
Check rules are in correct order (allow before deny)
Ensure firewall is enabled: sudo ufw enable
Test from external IP: curl http://YOUR_PUBLIC_IP:8080
Check no port forwarding rules bypass firewall

Netbird not connecting

Check setup key is valid and not expired
Verify network connectivity to Netbird servers
Check logs: netbird service logs
Try disconnect and reconnect: netbird down && netbird up
Verify account status in Netbird dashboard

SSL certificate issues

For internal networks, use self-signed certificates
Generate certificate: openssl req -x509 -nodes -days 365 ...
Install certificate on client devices
Or use Let’s Encrypt with DNS challenge for internal domains
Configure Nginx with correct certificate paths

See ZITADEL_NETBIRD_SETUP.md:198-221 for additional troubleshooting tips.

Security Considerations

Network Isolation Security

Benefits of VPN-only access:

Zero Trust Network: Access only from authorized VPN peers
No Public Exposure: Application not accessible from internet
Encrypted Transport: All traffic encrypted via WireGuard
Audit Trail: Netbird logs all connections
Device Management: Control which devices can connect
IP Allowlisting: Easy to implement additional IP-based rules

See ZITADEL_NETBIRD_SETUP.md:223-229

Additional Security Measures

Device Authorization

In Netbird dashboard:

Enable Peer Approval mode
Review and approve new peers manually
Set peer expiration policies
Monitor connected peers regularly

Network Segmentation

Use Netbird’s network policies:

Create peer groups (e.g., “admins”, “users”)
Define access control policies between groups
Restrict which peers can access the vault server
Implement least-privilege access

Logging and Monitoring

Monitor access:

Enable Netbird activity logs
Monitor application logs: pm2 logs nexus-vault
Review Nginx access logs: tail -f /var/log/nginx/access.log
Set up alerts for suspicious activity
Review audit logs in the portal regularly

Next Steps

Environment Variables

Configure network mode and internal host

Zitadel OIDC

Set up authentication for VPN access

Self-Hosted Deployment

Complete deployment guide

Admin Panel

Manage users and access permissions

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

​Overview

​Network Modes

Internal Mode

Public Mode

​Netbird VPN Setup

​Prerequisites

​Server Installation

​Get Your Netbird IP

​Application Network Configuration

​Environment Variables

​Vite Server Configuration

​Production: Bind to Specific Interface

​Firewall Configuration

​UFW (Ubuntu)

​firewalld (CentOS/RHEL)

​iptables

​Nginx Reverse Proxy

​Basic Configuration

​SSL/TLS Configuration

​Internal DNS Configuration

​Using Netbird’s Built-in DNS

​Using /etc/hosts

​Using Pi-hole or AdGuard Home

​Authentication Configuration

​Zitadel Redirect URI

​Update Zitadel Application

​Client Access

​Installing Netbird on Client Devices

​Accessing the Portal

​User Flow

​Alternative VPN Solutions

​Tailscale

​WireGuard

​OpenVPN

​Testing Network Isolation

​Test VPN Access

​Test External Access

​Troubleshooting

​Security Considerations

Network Isolation Security

​Additional Security Measures

​Next Steps

Environment Variables

Zitadel OIDC

Self-Hosted Deployment

Admin Panel

Build docs developers (and LLMs) love

Overview

Network Modes

Netbird VPN Setup

Prerequisites

Server Installation

Get Your Netbird IP

Application Network Configuration

Environment Variables

Vite Server Configuration

Production: Bind to Specific Interface

Firewall Configuration

UFW (Ubuntu)

firewalld (CentOS/RHEL)

iptables

Nginx Reverse Proxy

Basic Configuration

SSL/TLS Configuration

Internal DNS Configuration

Using Netbird’s Built-in DNS

Using /etc/hosts

Using Pi-hole or AdGuard Home

Authentication Configuration

Zitadel Redirect URI

Update Zitadel Application

Client Access

Installing Netbird on Client Devices

Accessing the Portal

User Flow

Alternative VPN Solutions

Tailscale

WireGuard

OpenVPN

Testing Network Isolation

Test VPN Access

Test External Access

Troubleshooting

Security Considerations

Additional Security Measures

Next Steps