Ga naar inhoud

Netbird ZTNA — Configuratie & Installatie

Project: SASE Proof of Concept
Datum: 31-05-2026
Component: Netbird self-hosted (combined server + dashboard + reverse proxy) + Netbird peer op OPNsense
Platform: Externe VPS (Docker Compose) + OPNsense 26.1 op VM1 (PoP Node) + Rocky Linux testclient
Verantwoordelijke: Rieam

Netbird vormt de ZTNA-laag van de SASE-architectuur. Het overlay-netwerk wordt opgebouwd via WireGuard-tunnels die centraal beheerd worden door een self-hosted Netbird-controller op een externe VPS. Authenticatie verloopt via Microsoft Entra ID (OIDC); groepslidmaatschappen worden gesynchroniseerd zodat per-applicatie toegang afgedwongen kan worden op basis van identiteit, niet op basis van statische IP-adressen.


Architectuuroverzicht

flowchart TD
    Entra["Microsoft Entra ID\n(OIDC)"] -->|"openid / profile / email\n+ groups claim"| NB

    subgraph NB["Netbird Server (VPS 204.168.216.41)\nmanagement plane"]
        direction TB
        NBS["netbird-server\n(management + signal + relay + STUN)"]
        NBD["netbird-dashboard\n(web UI)"]
        NBP["netbird-proxy\n(resource proxy)"]
        NBT["netbird-traefik\n(reverse proxy + Let's Encrypt)"]
    end

    NB -->|"WireGuard tunnel (UDP 51820)\nOverlay 100.116.0.0/16"| OPN

    subgraph OPN["OPNsense (VM1)\nNetbird peer + Exit Node + routing peer"]
        direction TB
        wt0["Interface wt0\n(overlay-IP 100.116.74.175)"]
        vtnet1["Interface vtnet1\n(LAN 192.168.50.1/24)"]
        SquidICAP["Squid + ICAP\n(192.168.50.12:13440)"]
        Suricata["Suricata IDS"]
        Unbound["Unbound DNS"]
    end

    OPN --> Rocky

    subgraph Rocky["Rocky Linux testclient"]
        direction TB
        NB_Client["netbird client\n(overlay-IP 100.116.198.151)"]
    end
Het overlay-verkeer verlaat de WireGuard-tunnel op OPNsense (interface wt0) en wordt vandaar doorgestuurd naar het internet (exit node 0.0.0.0/0), naar de ICAP-server (192.168.50.12/32) of naar het interne subnet (192.168.50.0/24). Netbird beslist op basis van groepslidmaatschap welke routes per peer zichtbaar zijn: dat is de feitelijke ZTNA-segmentatie.


Architecturale doelstelling

De Netbird-laag biedt in deze SASE-architectuur vier functies:

Functie Doel
ZTNA-segmentatie Routes naar specifieke resources (ICAP, LAN) worden alleen verdeeld naar peers in de juiste groep
Identity-binding OIDC-login via Entra ID verbindt elke peer aan een echte gebruiker en zijn groepen
Encryptie & transport WireGuard-tunnel als veilig pad van Rocky-client naar de PoP (OPNsense)
Exit node Internetverkeer van clients wordt gedwongen door OPNsense (Squid + ICAP + Suricata); geen local breakout (binnen de bekende beperkingen, zie sectie 12)

De controller (VPS) draait uitsluitend als management plane. De feitelijke dataforwarding loopt direct van peer naar peer via WireGuard; in deze setup is OPNsense de enige bestemmingspeer voor exit- en LAN-verkeer.


VM-specificaties en netwerklayout

Hosts

Component Platform OS Rol IP (LAN / publiek) IP (overlay)
Netbird Server Externe VPS (Docker) Ubuntu 22.04 LTS Management plane (server, proxy, dashboard, traefik) 204.168.216.41 n.v.t.
OPNsense Proxmox VM1 OPNsense 26.1 Netbird peer + Exit Node 192.168.50.1 100.116.74.175
Rocky Linux client Proxmox testclient Rocky Linux Netbird peer (testgebruiker) DHCP via LAN 100.116.198.151
ICAP Server Proxmox VM Ubuntu 22.04 LTS School ICAP Guard, doel van LAN-route 192.168.50.12 n.v.t.

Poorten en endpoints

Endpoint Adres Doel
Netbird Dashboard https://netbird.secure1e.org Web UI, peer/route/group beheer
Netbird Management API https://netbird.secure1e.org/api Programmatische toegang (sync scripts)
WireGuard UDP 51820 (VPS publiek) Tunnel transport
STUN UDP 3478 (VPS publiek) NAT-traversal
Entra ID OIDC issuer https://login.microsoftonline.com/58ae5f32-3650-417e-b293-64e617c623e1/v2.0 Authenticatie peers
Entra App Registration Client-ID 2b77ff6f-553e-4ed0-9cd2-e0cfe84e0f14 OIDC client van Netbird
OPNsense Netbird overlay 100.116.74.175 Bestemming voor exit + LAN routes

1. Netbird Server installeren op de VPS

De installatie volgt de officiële Netbird self-hosted quickstart. De stack bestaat uit vier containers (traefik, dashboard, netbird-server, proxy) die via Docker Compose worden uitgerold. De netbird-server container combineert management, signal, relay en STUN; traefik regelt automatische TLS via Let's Encrypt.

1.1. Docker en docker-compose installeren

ssh root@204.168.216.41

apt update && apt install -y ca-certificates curl gnupg lsb-release jq
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  > /etc/apt/sources.list.d/docker.list

apt update && apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

1.2. Directorystructuur

mkdir -p /netbird
cd /netbird

1.3. docker-compose.yml

services:
  # Traefik reverse proxy (automatic TLS via Let's Encrypt)
  traefik:
    image: traefik:v3.6
    container_name: netbird-traefik
    restart: unless-stopped
    networks:
      netbird:
        ipv4_address: 172.30.0.10
    command:
      # Logging
      - "--log.level=INFO"
      - "--accesslog=true"
      # Docker provider
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=netbird"
      # Entrypoints
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.allowACMEByPass=true"
      # Disable timeouts for long-lived gRPC streams
      - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=0"
      - "--entrypoints.websecure.transport.respondingTimeouts.writeTimeout=0"
      - "--entrypoints.websecure.transport.respondingTimeouts.idleTimeout=0"
      # HTTP to HTTPS redirect
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      # Let's Encrypt ACME
      - "--certificatesresolvers.letsencrypt.acme.email=rieam.ahmed@student.ap.be"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      # gRPC transport settings
      - "--serverstransport.forwardingtimeouts.responseheadertimeout=0s"
      - "--serverstransport.forwardingtimeouts.idleconntimeout=0s"
      - "--providers.file.filename=/etc/traefik/dynamic.yaml"
    ports:
      - '443:443'
      - '80:80'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - netbird_traefik_letsencrypt:/letsencrypt
      - ./traefik-dynamic.yaml:/etc/traefik/dynamic.yaml:ro
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "2"

  # UI dashboard
  dashboard:
    image: netbirdio/dashboard:latest
    container_name: netbird-dashboard
    restart: unless-stopped
    networks: [netbird]
    env_file:
      - ./dashboard.env
    labels:
      - traefik.enable=true
      - traefik.http.routers.netbird-dashboard.rule=Host(netbird.secure1e.org)
      - traefik.http.routers.netbird-dashboard.entrypoints=websecure
      - traefik.http.routers.netbird-dashboard.tls=true
      - traefik.http.routers.netbird-dashboard.tls.certresolver=letsencrypt
      - traefik.http.routers.netbird-dashboard.service=dashboard
      - traefik.http.routers.netbird-dashboard.priority=1
      - traefik.http.services.dashboard.loadbalancer.server.port=80
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "2"

  # Combined server (Management + Signal + Relay + STUN)
  netbird-server:
    image: netbirdio/netbird-server:latest
    container_name: netbird-server
    restart: unless-stopped
    networks: [netbird]
    ports:
      - '3478:3478/udp'
    volumes:
      - netbird_data:/var/lib/netbird
      - ./config.yaml:/etc/netbird/config.yaml
    command: ["--config", "/etc/netbird/config.yaml"]
    labels:
      - traefik.enable=true
      # gRPC router (needs h2c backend for HTTP/2 cleartext)
      - traefik.http.routers.netbird-grpc.rule=Host(netbird.secure1e.org) && (PathPrefix(/signalexchange.SignalExchange/) || PathPrefix(/management.ManagementService/))
      - traefik.http.routers.netbird-grpc.entrypoints=websecure
      - traefik.http.routers.netbird-grpc.tls=true
      - traefik.http.routers.netbird-grpc.tls.certresolver=letsencrypt
      - traefik.http.routers.netbird-grpc.service=netbird-server-h2c
      - traefik.http.routers.netbird-grpc.priority=100
      # Backend router (relay, WebSocket, API, OAuth2)
      - traefik.http.routers.netbird-backend.rule=Host(netbird.secure1e.org) && (PathPrefix(/relay) || PathPrefix(/ws-proxy/) || PathPrefix(/api) || PathPrefix(/oauth2))
      - traefik.http.routers.netbird-backend.entrypoints=websecure
      - traefik.http.routers.netbird-backend.tls=true
      - traefik.http.routers.netbird-backend.tls.certresolver=letsencrypt
      - traefik.http.routers.netbird-backend.service=netbird-server
      - traefik.http.routers.netbird-backend.priority=100
      # Services
      - traefik.http.services.netbird-server.loadbalancer.server.port=80
      - traefik.http.services.netbird-server-h2c.loadbalancer.server.port=80
      - traefik.http.services.netbird-server-h2c.loadbalancer.server.scheme=h2c
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "2"

  # NetBird Proxy, exposes internal resources to the internet
  proxy:
    image: netbirdio/reverse-proxy:latest
    container_name: netbird-proxy
    ports:
    - 51820:51820/udp
    restart: unless-stopped
    networks: [netbird]
    depends_on:
      netbird-server:
        condition: service_started
    env_file:
      - ./proxy.env
    volumes:
      - netbird_proxy_certs:/certs
    labels:
      # TCP passthrough for any unmatched domain (proxy handles its own TLS)
      - traefik.enable=true
      - traefik.tcp.routers.proxy-passthrough.entrypoints=websecure
      - traefik.tcp.routers.proxy-passthrough.rule=HostSNI(*)
      - traefik.tcp.routers.proxy-passthrough.tls.passthrough=true
      - traefik.tcp.routers.proxy-passthrough.service=proxy-tls
      - traefik.tcp.routers.proxy-passthrough.priority=1
      - traefik.tcp.services.proxy-tls.loadbalancer.server.port=8443
      - traefik.tcp.services.proxy-tls.loadbalancer.serverstransport=pp-v2@file
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "2"

volumes:
  netbird_data:
  netbird_traefik_letsencrypt:
  netbird_proxy_certs:

networks:
  netbird:
    driver: bridge
    ipam:
      config:
        - subnet: 172.30.0.0/24
          gateway: 172.30.0.1

Netbird Docker stack, running containers

1.4. config.yaml

Deze configuratie is bewust eenvoudig. Het netbird-server-process bedient zijn eigen embedded OIDC-provider op /oauth2. Microsoft Entra ID wordt niet in dit YAML-bestand geconfigureerd; dat gebeurt pas later via het dashboard (zie sectie 4) nadat er een lokale superadmin is aangemaakt. De authSecret en encryptionKey worden gegenereerd door het officiële getting-started.sh-script en moeten geheim blijven.

# Combined NetBird Server Configuration (Simplified)
# Generated by getting-started.sh

server:
  listenAddress: ":80"
  exposedAddress: "https://netbird.secure1e.org:443"
  stunPorts:
    - 3478
  metricsPort: 9090
  healthcheckAddress: ":9000"
  logLevel: "info"
  logFile: "console"

  authSecret: "<REDACTED - bewaard in password manager>"
  dataDir: "/var/lib/netbird"

  auth:
    issuer: "https://netbird.secure1e.org/oauth2"
    signKeyRefreshEnabled: true
    dashboardRedirectURIs:
      - "https://netbird.secure1e.org/nb-auth"
      - "https://netbird.secure1e.org/nb-silent-auth"
    cliRedirectURIs:
      - "http://localhost:53000/"

  reverseProxy:
    trustedHTTPProxies:
      - "172.30.0.10/32"

  store:
    engine: "sqlite"
    encryptionKey: "<REDACTED - bewaard in password manager>"

Opmerking: de combinatie authSecret + encryptionKey versleutelt zowel de OIDC-tokens als de SQLite-store. Verlies van beide waardes betekent dat alle bestaande peers opnieuw moeten worden geregistreerd. Bewaar ze veilig (bij voorkeur in een password manager) en commit ze niet in git.

1.5. dashboard.env

De dashboard-container praat met de embedded IdP van Netbird zelf (/oauth2), niet rechtstreeks met Entra. De Entra-credentials komen pas in het dashboard terecht via de Identity Provider-instellingen (zie sectie 4).

# Endpoints
NETBIRD_MGMT_API_ENDPOINT=https://netbird.secure1e.org
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://netbird.secure1e.org
# OIDC, using embedded IdP
AUTH_AUDIENCE=netbird-dashboard
AUTH_CLIENT_ID=netbird-dashboard
AUTH_CLIENT_SECRET=
AUTH_AUTHORITY=https://netbird.secure1e.org/oauth2
USE_AUTH0=false
AUTH_SUPPORTED_SCOPES=openid profile email groups
AUTH_REDIRECT_URI=/nb-auth
AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
# SSL
NGINX_SSL_PORT=443
# Letsencrypt
LETSENCRYPT_DOMAIN=none

1.6. proxy.env

De netbird-proxy container handelt de WireGuard control plane af (poort 51820/UDP). Hij gebruikt PROXY protocol om client-IPs te behouden door de Traefik TCP passthrough heen.

# NetBird Proxy Configuration
NB_PROXY_DEBUG_LOGS=false
# Use internal Docker network to connect to management (avoids hairpin NAT issues)
NB_PROXY_MANAGEMENT_ADDRESS=http://netbird-server:80
# Allow insecure gRPC connection to management (required for internal Docker network)
NB_PROXY_ALLOW_INSECURE=true
# Public URL where this proxy is reachable (used for cluster registration)
NB_PROXY_DOMAIN=netbird.secure1e.org
NB_PROXY_ADDRESS=:8443
NB_PROXY_TOKEN=<REDACTED>
NB_PROXY_CERTIFICATE_DIRECTORY=/certs
NB_PROXY_ACME_CERTIFICATES=true
NB_PROXY_ACME_CHALLENGE_TYPE=tls-alpn-01
NB_PROXY_FORWARDED_PROTO=https
# Enable PROXY protocol to preserve client IPs through L4 proxies (Traefik TCP passthrough)
NB_PROXY_PROXY_PROTOCOL=true
# Trust Traefik's IP for PROXY protocol headers
NB_PROXY_TRUSTED_PROXIES=172.30.0.10

Opmerking: traefik-dynamic.yaml (referent vanuit het traefik service in docker-compose.yml) bevat de PROXY protocol v2 transport-config voor het TCP passthrough kanaal. Een minimale variant:

yaml tcp: serversTransports: pp-v2: tls: insecureSkipVerify: true proxyProtocol: version: 2

1.7. Stack starten

docker compose up -d

2. Eerste superadmin aanmaken (lokaal)

De Entra-integratie kan pas geconfigureerd worden nadat er een lokale superadmin bestaat. Bij de allereerste login op https://netbird.secure1e.org toont Netbird daarom een setup-pagina van de embedded IdP waar een initiële admin-account wordt aangemaakt.

2.1. Browse naar het dashboard

Open https://netbird.secure1e.org. Bij de eerste opstart wordt automatisch doorgestuurd naar /oauth2/setup of een vergelijkbaar onboarding-pad van de embedded OIDC server.

2.2. Superadmin-account aanmaken

Vul de gevraagde velden in:

Veld Waarde (voorbeeld)
Naam [Je Naam]
Email Naam.Achternaam@student.ap.be
Wachtwoord (sterk wachtwoord, bewaard in password manager)

Na het opslaan wordt automatisch ingelogd in het dashboard. Deze account heeft de rol owner en kan alle instellingen wijzigen, inclusief de Identity Provider-koppeling met Entra.

Opmerking: zolang Entra nog niet geconfigureerd is, gebruikt iedereen die op het dashboard wil de embedded IdP. Pas na sectie 4 kunnen gebruikers met hun Entra-credentials inloggen.


3. Microsoft Entra ID App Registration

3.1. App registratie aanmaken

In het Entra-portal: Entra ID → App registrations → New registration.

Veld Waarde
Name Netbird-SASE-PoC
Supported account types Single tenant, 58ae5f32-3650-417e-b293-64e617c623e1
Redirect URI (SPA) https://netbird.secure1e.org/auth
Redirect URI (Web) https://netbird.secure1e.org/oauth2/callback

Na aanmaken: noteer de Application (client) ID 2b77ff6f-553e-4ed0-9cd2-e0cfe84e0f14.

Entra App Registration overzicht

3.2. API permissions

Onder API permissions → Add a permission → Microsoft Graph → Application permissions:

Permissie Type Reden
User.Read.All Application Sync-script leest user-objecten
Group.Read.All Application Sync-script leest groepslidmaatschappen
Directory.Read.All Application Volledige directory readonly

Klik daarna op Grant admin consent for . Zonder admin consent werken Application-permissies niet.

3.3. Token configuration (groepsclaims)

Onder Token configuration → Add groups claim:

  • Group types: Security groups
  • ID + Access + SAML: Group ID

Dit zorgt dat de groups claim in het ID-token aanwezig is.

3.4. Client secret

Onder Certificates & secrets → New client secret: bewaartermijn 24 maanden. De waarde wordt één keer getoond. Kopieer ze direct naar een veilige plek; ze wordt zo in sectie 4 toegevoegd aan het Netbird dashboard én later in sectie 6 aan /root/.sync-env.

3.5. Testgebruikers en groepen aanmaken

In Entra ID → Groups → New group worden security groepen aangemaakt. Direct na aanmaken hebben deze nog hun GUID als zichtbare naam in Netbird, totdat sync-groups.sh (sectie 6) ze omzet naar leesbare namen.

Entra-groepsnaam Doel Gemapt naar
Admin-1e Volledige toegang tot interne resources Admin-1e
IT-HELPDESK-1e Toegang tot ICAP-server en intern subnet IT-HELPDESK-1e
students-1e Alleen exit-node (internet via SWG), geen interne resources students-1e

Testgebruikers (waaronder Mariam El Hajouti in students-1e) worden aan de juiste groep toegevoegd.


4. Entra koppelen aan Netbird (Identity Provider)

Na het aanmaken van de superadmin (sectie 2) en de Entra App Registration (sectie 3) kan Entra worden gekoppeld als externe Identity Provider in Netbird.

4.1. Openen van de IdP-instellingen

In het dashboard (ingelogd als superadmin):

Settings → Identity Providers → Add Provider

4.2. Provider-velden invullen

Veld Waarde
Provider type Microsoft Entra ID (of Generic OIDC)
Issuer https://login.microsoftonline.com/58ae5f32-3650-417e-b293-64e617c623e1/v2.0
Client ID 2b77ff6f-553e-4ed0-9cd2-e0cfe84e0f14
Client Secret (waarde uit sectie 3.4)
Tenant ID 58ae5f32-3650-417e-b293-64e617c623e1
User ID claim oid
Username claim preferred_username
Groups claim groups

Klik op Save.

Opmerking: User ID claim: oid. Entra ID levert de stabiele object-ID via de oid claim, niet via sub. Een verkeerde claim breekt de koppeling tussen Netbird-user en Entra-user en zorgt voor duplicate accounts bij elke login.

4.3. Verifiëren

Log uit, en log opnieuw in via https://netbird.secure1e.org. De login-pagina toont nu een knop "Sign in with Microsoft". De OIDC-flow redirect naar login.microsoftonline.com en daarna terug naar het dashboard. Bij een succesvolle login verschijnt de Entra-gebruiker in Team → Users met email en groepen.

Entra IdP gekoppeld in Netbird Settings


5. Dashboard configureren

5.1. Peers en groepen

In het dashboard zijn drie hoofdsecties relevant voor ZTNA:

  • Peers: lijst van verbonden clients (OPNsense, Rocky Linux, ...)
  • Groups: automatisch gesynchroniseerd via Entra (initieel GUID-groepen) en omgezet naar leesbare namen via sync-groups.sh (sectie 6)
  • Network Routes: routes per peer, gedistribueerd op basis van groepslidmaatschap

Netbird peers-overzicht met OPNsense en Rocky

5.2. Network Routes

Onder Network → Network Routes worden drie routes geconfigureerd. OPNsense is in alle gevallen de routing peer.

Route Network Routing Peer Distribution Groups Masquerade
Exit Node 0.0.0.0/0 opnsense All AAN
ICAP Server 192.168.50.12/32 opnsense IT-HELPDESK-1e, Admin-1e AAN
Intern LAN 192.168.50.0/24 opnsense IT-HELPDESK-1e, Admin-1e AAN

Motivatie distribution groups: alleen peers in de toegestane groep krijgen de route in het Netbird-overzicht en in hun WireGuard AllowedIPs. Een Student-peer ziet 192.168.50.12 of 192.168.50.0/24 dus niet in sudo netbird networks list. Belangrijk: dit alleen is niet voldoende om interne toegang te blokkeren, omdat OPNsense in onze setup zowel exit node als gateway is, zie hiervoor 01-Per-applicatie-toegang.

Opmerking: de route 192.168.50.0/24 stond oorspronkelijk op Distribution Group All, waardoor ook Student-peers de interne route ontvingen. Dit is gecorrigeerd naar IT-HELPDESK-1e + Admin-1e. Controleer na wijzigingen altijd via sudo netbird networks list op de client of de routes correct gedistribueerd worden.

Network Routes, Exit Node, ICAP en LAN

5.3. Access Control Policies

Onder Access Control → Policies is in de huidige configuratie één policy actief:

Naam Source Destination Protocol Action
Default All OPNsense.internal All Accept

Update Access Control Policy, All naar OPNsense.internal

Opmerking: een aanvullende students-default-deny policy (Source: students-1e, Destination: IT-HELPDESK-1e/Admin-1e, Action: Drop) is geprobeerd als defense-in-depth maatregel, maar gaf in onze testen onbedoelde bijwerkingen (waaronder blokkering van exit-node verkeer). De primaire segmentatie wordt daarom afgedwongen via route-distributie (sectie 5.2) én OPNsense firewallregels (zie 01-Per-applicatie-toegang ZT-T03).


6. Entra-groepen sync (sync-groups.sh)

Netbird maakt voor elke Entra security group automatisch een groep aan, maar met de Object-GUID als naam (aaaaaaaa-bbbb-...). Voor leesbaarheid en gemak in het dashboard draait er op de VPS een sync-script dat:

  1. Een Azure AD token ophaalt via client credentials
  2. Alle Netbird-groepen, -peers en -users opvraagt
  3. GUID-groepen matcht aan Entra displayName via Microsoft Graph
  4. Leesbare groepen aanmaakt (of bestaande hergebruikt)
  5. auto_groups van users verplaatst van de GUID naar de leesbare groep
  6. De leeg geworden GUID-groep verwijdert

Het script staat op de VPS in /root/netbird/sync-groups.sh en wordt elke 2 minuten door cron uitgevoerd.

6.1. Environment file /root/.sync-env

# Microsoft Entra ID (app registration)
TENANT_ID="58ae5f32-3650-417e-b293-64e617c623e1"
CLIENT_ID="2b77ff6f-553e-4ed0-9cd2-e0cfe84e0f14"
CLIENT_SECRET="<APP_SECRET_UIT_ENTRA>"

# Netbird API
NB_API="https://netbird.secure1e.org/api"
NB_TOKEN="<PERSONAL_ACCESS_TOKEN_UIT_NETBIRD_DASHBOARD>"

Opmerking: De NB_TOKEN is een Personal Access Token, aangemaakt via Team → Users → \<user> → Access Tokens → Create Access Token in het Netbird dashboard. De waarde wordt slechts één keer getoond.

sudo chmod 600 /root/.sync-env
sudo chown root:root /root/.sync-env

6.2. Script /root/netbird/sync-groups.sh

Het script combineert bash (voor Azure token en API-calls) met een embedded Python-blok (voor de GUID-matching en groepenbeheer). Python wordt gebruikt omdat de logica voor het matchen, aanmaken, verplaatsen en opruimen van groepen complexer is dan wat comfortabel in pure bash past. Er zijn geen pip-dependencies, alleen de Python 3 standaardbibliotheek (urllib.request, json, re, ssl).

#!/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
source /root/.sync-env

echo "[1] Azure token ophalen..."
curl -sk -X POST \
  "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET\
&scope=https://graph.microsoft.com/.default\
&grant_type=client_credentials" \
  -o /tmp/az_token.json
AZ_TOKEN=$(jq -r '.access_token' /tmp/az_token.json)
if [ "$AZ_TOKEN" = "null" ] || [ -z "$AZ_TOKEN" ]; then
  echo "FOUT: Kon geen Azure token ophalen"
  exit 1
fi
echo "Token OK"

echo "[2] NetBird data ophalen..."
curl -sk -H "Authorization: Token $NB_TOKEN" "$NB_API/groups" \
  -o /tmp/nb_groups.json
curl -sk -H "Authorization: Token $NB_TOKEN" "$NB_API/peers" \
  -o /tmp/nb_peers.json
curl -sk -H "Authorization: Token $NB_TOKEN" "$NB_API/users" \
  -o /tmp/nb_users.json

python3 - "$AZ_TOKEN" "$NB_TOKEN" "$NB_API" << 'PYEOF'
import json, sys, re, urllib.request, ssl

az_token, nb_token, nb_api = sys.argv[1], sys.argv[2], sys.argv[3]

with open('/tmp/nb_groups.json') as f: groups = json.load(f)
with open('/tmp/nb_peers.json') as f:  peers = json.load(f)
with open('/tmp/nb_users.json') as f:  users = json.load(f)

peer_to_user = {p['id']: p['user_id'] for p in peers if p.get('user_id')}
user_map = {u['id']: u for u in users}
guid_re = re.compile(
    r'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}'
    r'-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

def api_call(url, data=None, method=None):
    headers = {"Authorization": f"Token {nb_token}",
               "Content-Type": "application/json"}
    req = urllib.request.Request(
        url, data=data.encode() if data else None,
        headers=headers, method=method)
    return urllib.request.urlopen(req, context=ctx)

friendly_groups, guid_groups = {}, []
for g in groups:
    if guid_re.match(g['name']):
        guid_groups.append(g)
    else:
        friendly_groups[g['name']] = g

if not guid_groups:
    print("    Geen GUID-groepen gevonden, alles is schoon.")

for g in guid_groups:
    nb_name, nb_id = g['name'], g['id']
    guid_peers = [p['id'] for p in (g.get('peers') or [])]
    print(f"[3] GUID gevonden: {nb_name[:12]}... Naam ophalen uit Azure...")

    # Haal displayName op via Microsoft Graph
    req = urllib.request.Request(
        f"https://graph.microsoft.com/v1.0/groups/{nb_name}",
        headers={"Authorization": f"Bearer {az_token}"})
    try:
        resp = urllib.request.urlopen(req, context=ctx)
        az_name = json.loads(resp.read()).get('displayName', '')
    except Exception as e:
        print(f"    x Fout bij Azure: {e}"); continue
    if not az_name: continue

    # Maak leesbare groep aan of update bestaande
    if az_name in friendly_groups:
        friendly_id = friendly_groups[az_name]['id']
        existing = [p['id'] for p in (friendly_groups[az_name].get('peers') or [])]
        combined = list(set(existing + guid_peers))
        if sorted(existing) != sorted(combined):
            api_call(f"{nb_api}/groups/{friendly_id}",
                     json.dumps({"name": az_name, "peers": combined}), "PUT")
            print(f"    + Groep '{az_name}' peers geupdatet!")
        else:
            print(f"    + Groep '{az_name}' peers al up-to-date.")
    else:
        resp = api_call(f"{nb_api}/groups",
                        json.dumps({"name": az_name, "peers": guid_peers}), "POST")
        new_group = json.loads(resp.read())
        friendly_id = new_group.get('id')
        friendly_groups[az_name] = new_group
        print(f"    + Nieuwe groep '{az_name}' aangemaakt!")

    # Verplaats user auto_groups van GUID naar leesbare groep
    for peer_id in guid_peers:
        uid = peer_to_user.get(peer_id)
        if not uid or uid not in user_map: continue
        user = user_map[uid]
        ag = list(user.get('auto_groups') or [])
        changed = False
        if nb_id in ag: ag.remove(nb_id); changed = True
        if friendly_id not in ag: ag.append(friendly_id); changed = True
        if changed:
            api_call(f"{nb_api}/users/{uid}",
                     json.dumps({"auto_groups": ag,
                                 "role": user.get('role','user')}), "PUT")
            print(f"    + User '{user.get('name','')}' auto_groups bijgewerkt!")

    # Verwijder de lege GUID-groep
    api_call(f"{nb_api}/groups/{nb_id}",
             json.dumps({"name": nb_name, "peers": []}), "PUT")
    try:
        req_del = urllib.request.Request(
            f"{nb_api}/groups/{nb_id}",
            headers={"Authorization": f"Token {nb_token}"}, method="DELETE")
        urllib.request.urlopen(req_del, context=ctx)
        print(f"    + GUID-groep verwijderd!")
    except Exception as e:
        print(f"    ~ GUID leeggemaakt maar niet verwijderd: {e}")
PYEOF

rm -f /tmp/az_token.json /tmp/nb_groups.json /tmp/nb_peers.json /tmp/nb_users.json
echo "Klaar!"
sudo chmod +x /root/netbird/sync-groups.sh

6.3. Cron


sudo crontab -e

*/2 * * * * /root/netbird/sync-groups.sh >> /var/log/sync-groups.log 2>&1

Dependencies: jq (voor het parsen van het Azure token in bash) en python3 (standaardbibliotheek, geen pip-packages) zijn vereist; curl is reeds aanwezig in een standaard Ubuntu-installatie. Installeer jq met apt install jq -y.

Sync-script log, GUID-groepen omgezet


7. OPNsense Netbird-plugin

7.1. Plugin installeren

Navigeer naar System → Firmware → Plugins en installeer os-netbird. Na installatie verschijnt het menu VPN → NetBird.

Netbird plugin geinstalleerd in OPNsense

7.2. Settings

Onder VPN → NetBird → Settings:

Instelling Waarde
Enabled ✓
Management URL https://netbird.secure1e.org
Admin URL https://netbird.secure1e.org
WireGuard Port 51820
Interface Name wt0
Client Firewall enabled
SSH Server disabled
DNS enabled
Allow Rosenpass UIT

OPNsense Netbird-plugin settings

7.3. OPNsense peer aanmelden

In het Netbird-dashboard: Setup Keys → Create Setup Key (type: Reusable, max usage 1, expiration 30 days).

Op OPNsense in de plugin: Connect with setup key → plak de key → Apply.

Na een succesvolle verbinding verschijnt wt0 in Interfaces → Overview met IP 100.116.74.175.

wt0: flags=8043<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1280
        inet 100.116.74.175 netmask 0xfffe0000

Interface wt0 op OPNsense

7.4. Routing peer assignen

Terug in het dashboard: open de OPNsense-peer en assign hem aan de drie routes:

  • Exit Node 0.0.0.0/0
  • 192.168.50.12/32
  • 192.168.50.0/24

8. Client-installatie (Rocky Linux)

8.1. Netbird client installeren

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

Het installer-script detecteert de distro, voegt een repository toe en installeert netbird plus netbird-ui.

8.2. Verbinden met de self-hosted server

sudo netbird up --management-url https://netbird.secure1e.org


Het commando opent een browservenster met de Entra-login. Na succesvolle authenticatie krijgt de peer een overlay-IP toegewezen.

```bash
netbird status

OS: linux/amd64
Daemon version: 0.71.4
CLI version: 0.71.4
Profile: default
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 1/1 Available
FQDN: localhost.netbird.selfhosted
NetBird IP: 100.116.129.43/16
Interface type: Kernel
Quantum resistance: false
Lazy connection: false
SSH Server: Disabled
Networks: -
Peers count: 1/1 Connected
![Rocky Linux netbird status](../../../assets/screenshots/04-ztna/03-T03-A---netbird-status---detail-Networks-blok.png)

<!-- 📸 SCREENSHOT NODIG: Output van netbird status op Rocky met Connected + interface IP.
     BRON: omgeving
     ACTIE: Rocky terminal → netbird status → screenshot -->

### 8.3. Routes verifiëren

```bash
sudo netbird networks list

Voor een IT-helpdesk-user:

0.0.0.0/0 Exit Node
192.168.50.12 ICAP Server
192.168.50.0/24 OPNsense-net

Voor een student (Mariam):

0.0.0.0/0 Exit Node

9. CA-certificaat voor SSL-bump installeren

Voor de gecombineerde SWG-flow (Squid SSL-bump + ICAP) moet het OPNsense-CA-certificaat (SECURITYPROJECT_CA, zie Squid-Configuratie) op de Netbird-client geinstalleerd worden, anders krijgt Firefox certificate warnings voor elke HTTPS-pagina.

# Kopieer het CA-certificaat vanaf OPNsense:
scp root@192.168.50.1:/var/etc/squid/ssl/ca.pem /tmp/securityproject_ca.crt

# Importeer in Firefox: Settings → Privacy & Security → Certificates → View Certificates → Import
# Vink aan: Trust this CA to identify websites.

10. Browser-proxy instellen (huidige werkwijze)

Belangrijk: in de huidige setup wordt de Squid-proxy manueel ingesteld in Firefox op de Rocky-client. De transparante proxy-redirect voor Netbird tunnel-verkeer werkt niet. Een uitgebreide analyse van de root cause staat in sectie 12.1. De Netbird-tunnel en route-afhandeling functioneren op eerste zicht correct, maar intern loopt er iets fout dat niet achterhaald kon worden binnen de PoC-scope.

Firefox → Settings → Network Settings → Manual Proxy Configuration

HTTP Proxy:  192.168.50.1   Port: 3128

Hierdoor gaat HTTP/HTTPS-verkeer eerst door wt0 (overlay) naar OPNsense LAN-IP 192.168.50.1:3128, dan via Squid en ICAP, en pas dan naar het internet.


11. Architecturale keuze: waarom OPNsense als exit node en niet de VPS

De keuze om OPNsense in plaats van de Netbird-VPS als exit node te gebruiken is bewust gemaakt. Tijdens de testfase heeft deze keuze ook conflicten zichtbaar gemaakt (zie 11.2 en 01-Per-applicatie-toegang) die mee hebben gewogen in de validatie van de architectuur.

11.1. De VPS is management plane, geen data plane

Op de VPS draait uitsluitend de Netbird controller (server, dashboard, proxy, traefik) als Docker containers. Er draait geen netbird client/peer op de VPS; de containers zelf zijn geen peers van het overlay. Om de VPS als exit node te gebruiken zou je naast de management-stack ook een Netbird-peer moeten installeren, waarbij de management-server tegelijk peer is van zichzelf. Dat is een fragiele configuratie: een herstart van de containers kan de eigen tunnel-state corrupteren, en je verliest de duidelijke scheiding tussen control en data plane.

11.2. Conflict: één host als gateway én exit node

In onze huidige opzet is OPNsense zowel Netbird exit node (0.0.0.0/0 routing peer) als de fysieke gateway naar het interne LAN-subnet 192.168.50.0/24. Dat dubbele rol heeft tijdens de testfase voor één concreet conflict gezorgd, dat hieronder wordt beschreven en in detail wordt aangetoond in ZT-T03 en ZT-T04 van de per-applicatie toegang test.

Wat we verwachtten:

Door 192.168.50.12/32 en 192.168.50.0/24 alleen te distribueren naar IT-HELPDESK-1e en Admin-1e, zouden Student-peers geen route naar interne resources krijgen, en zouden ping/TCP-verbindingen daarmee falen op de client.

Wat we observeerden:

sudo netbird networks list bevestigde dat Student-peers inderdaad niet de interne routes ontvingen. Toch slaagden ping 192.168.50.12 en nc -vz 192.168.50.12 13440 vanaf een Student-peer. De reden: de Student-peer heeft wel de exit-node route (0.0.0.0/0) naar OPNsense. Pakketten met bestemming 192.168.50.12 matchen die default-route, gaan via de Netbird-tunnel naar OPNsense, en omdat OPNsense de gateway is van 192.168.50.0/24 worden ze daar gewoon doorgerouteerd naar de interne host.

Route-distributie alleen volstaat dus niet om interne resources af te schermen wanneer dezelfde peer ook de exit node is voor het clientverkeer.

Hoe we het hebben opgelost:

Aanvullend op de route-distributie zijn er expliciete firewallregels toegevoegd op OPNsense die verkeer afkomstig van het Netbird overlay-subnet 100.116.0.0/16 blokkeren naar 192.168.50.12 en 192.168.50.0/24 wanneer dat verkeer afkomstig is van peers in de students-1e groep (te identificeren via Netbird's users.json mapping op de ICAP-server of via een aparte IP-range per groep in een toekomstige iteratie). IT-Helpdesk- en Admin-peers worden niet geraakt door deze regel.

Conclusie: dat een exit-node tegelijk ook gateway is voor het beschermde LAN is een eigenschap van de keuze om OPNsense centraal te maken. Het probleem is niet onoplosbaar; het vraagt enkel dat de toegangscontrole op twee plaatsen wordt afgedwongen: bij Netbird (route-distributie) en bij OPNsense (firewallregel). Een opzet met een aparte exit-node-VM zou dit conflict niet oplossen maar verplaatsen, want dezelfde gateway-relatie blijft bestaan.

11.3. Verkeerpad in onze setup

In onze setup loopt het volledige flow over één enkele tunnel naar OPNsense, waar de inspectiestack lokaal draait en het verkeer rechtstreeks via de WAN-interface naar het internet vertrekt:

Rocky client → tunnel (wt0) → OPNsense (Squid + ICAP + Suricata) → WAN → Internet

Eén tunnel, één machine voor inspectie en exit. Het hypothetische alternatief "VPS als exit-node" zou betekenen dat al het clientverkeer eerst naar de VPS gaat, vandaar terug door een tweede tunnel naar OPNsense voor inspectie, en daarna door OPNsense rechtstreeks naar het internet. Dat zijn twee tunnels in plaats van één, zonder enige inhoudelijke meerwaarde, want de inspectiestack en de internet-uplink draaien sowieso op OPNsense.

11.4. Vergelijkingstabel

Criterium Andere oplossing (lokale VM met Netbird client als exit, OPNsense als gateway) Onze setup (externe VPS, OPNsense als peer + exit) VPS als exit-node (afgewezen)
Verkeerpad client naar internet 1 tunnel + 1 LAN-hop 1 tunnel 2 tunnels
Encryptie-overhead 1× 1× 2×
Latency Laag Laag Hoger
Bandbreedte VPS-verbruik n.v.t. Alleen control plane Volledig dataverkeer
Complexiteit Laag Middel Hoog (peer op controller)
Beveiligingsinspectie Lokaal (LAN-hop) Lokaal (in de PoP) Vereist extra tunnel terug naar OPNsense
Single point of failure Lokale server OPNsense (zelfde als SWG) VPS (verlies = totaal verlies)
Locatie controller Lokaal LAN Extern (publiek IP) Extern (publiek IP)

11.5. Conclusie

Onze architectuur (OPNsense als gecombineerde Netbird-peer, exit node en SWG-proxy) elimineert de extra tunnel-hop volledig en houdt de inspectiestack dicht bij de internet-uplink. Het conflict tussen exit-node-rol en gateway-rol (sectie 11.2) is reëel, maar oplosbaar met OPNsense firewallregels en is daarom geaccepteerd binnen de PoC-scope.


12. Bekende beperkingen

Beperking Impact Status
Transparante proxy voor Netbird-tunnelverkeer Zie uitgebreide analyse hieronder (sectie 12.1) SWG-probleem, niet ZTNA. Workaround: handmatige proxy in Firefox (sectie 10)
Route-distributie alleen volstaat niet voor interne segmentatie Een Student-peer kan via de default-route (0.0.0.0/0) en OPNsense als gateway alsnog interne hosts bereiken, zie sectie 11.2 Opgelost met aanvullende OPNsense firewallregels (zie 01-Per-applicatie-toegang)
Local breakout op fysieke interface niet volledig geblokkeerd Een Netbird-client kan via een tweede netwerkinterface om de tunnel heen surfen (zie TR-T03) Beperking PoC-scope. Mitigatie: strikte Netbird ACL of OS-niveau firewallregel die alles behalve wt0 blokkeert
ICAP-server stabiliteit ICAP-service crashte enkele keren tijdens lange testsessies Niet ZTNA-gerelateerd; gevolgd in apart issue van ICAP Guard project
Relay-only verbindingen ICE/STUN directe P2P-verbinding faalt; alle peers communiceren via de relay server op rels://netbird.secure1e.org:443. Vermoedelijke oorzaak: UDP 51820 geblokkeerd op het schoolnetwerk of Proxmox-host. Impact: hogere latency, maar functioneel geen verschil voor route-distributie en tunnelwerking. Beperking PoC-omgeving, niet Netbird-gerelateerd

12.1. Transparante proxy: analyse en conclusie

Tijdens de validatie van de transparante proxyfunctionaliteit werd uitgebreid getest of verkeer van Netbird-clients automatisch (zonder manuele proxy-instellingen in Firefox) door Squid kon worden geïnspecteerd. Hieronder de bevindingen.

Wat werkt:

  • Verkeer afkomstig van Netbird-clients (100.116.0.0/16) wordt correct gerouteerd naar de OPNsense PoP-node via de WireGuard-tunnel (wt0).
  • NAT-redirection (Destination NAT / Port Forward) naar de Squid-proxy werd bevestigd via tcpdump: verkeer van 100.116.198.151 richting poort 80/443 werd geredirect naar 192.168.50.1:3128.
  • Socket-inspectie (sockstat) toonde actieve verbindingen van Netbird-clients naar de proxy-listener op poort 3128.
  • Squid was actief en geconfigureerd in transparent/intercept mode.

Wat niet werkt:

  • Ondanks de correcte NAT-redirection en actieve proxy-listener, verscheen het geredirecte verkeer niet in de Squid access logs.
  • De transparante inspectieketen (Squid SSL-bump, ICAP, internet) kon niet volledig gevalideerd worden wegens problemen in de verdere proxyverwerking en logging.
  • Meerdere combinaties van PF-redirect interfaces (LAN, NetBird, OPT1, WAN), source-netwerken en redirect-targets (127.0.0.1 vs 192.168.50.1) zijn getest zonder succes.

Conclusie:

Op basis van de uitgevoerde testen werd geen bewijs gevonden dat Netbird zelf de oorzaak vormt van het probleem. De NetBird-tunnel en route-afhandeling functioneren correct: verkeer bereikt OPNsense en wordt door PF naar de juiste poort geredirect. De vastgestelde beperking situeert zich vermoedelijk binnen Squid of de OPNsense-omgeving en niet binnen de Netbird-overlay of route-advertisement functionaliteit.

De huidige workaround is een handmatige proxy-instelling in Firefox (zie sectie 10). Met deze workaround functioneert de volledige inspectieketen (Squid, SSL-bump, ICAP, ClamAV, internet) correct.


13. Validatie & testen

De werking van de ZTNA-stack wordt aangetoond in de testdocumenten onder 03-ZTNA/Testen/:

Testdocument Bewijs
01-Per-applicatie-toegang Peers krijgen alleen routes naar resources waarvoor hun groep gemachtigd is + aanvullende OPNsense firewallregels voor effectieve segmentatie
02-Identity-en-context-awareness Entra-login + groepssync drijven de policykeuze
03-Tunnel-per-applicatie Routes zijn zichtbaar in sudo netbird networks list en sudo netbird status -d
04-Toegang-tot-on-prem-resources OPNsense management, ICAP dashboard en SSH via tunnel
05-Test-en-validatie Samenvattende testmatrix

Troubleshooting

Symptoom Mogelijke oorzaak Oplossing
OIDC-login werkt niet, redirect naar Entra faalt Verkeerde redirect URI in Entra App, of Identity Provider niet gekoppeld in Netbird Settings Voeg https://netbird.secure1e.org/oauth2/callback toe onder Authentication, Web in Entra; controleer Settings → Identity Providers in Netbird
Bij eerste login geen Entra-knop zichtbaar IdP nog niet gekoppeld of superadmin nog niet aangemaakt Eerst sectie 2 uitvoeren (superadmin), dan sectie 4 (Entra koppelen)
Login werkt maar groepen leeg in dashboard groups claim ontbreekt in token Token Configuration, Add groups claim, Security groups, Group ID
Groepen blijven GUIDs in plaats van leesbare namen sync-groups.sh draait niet, of CLIENT_SECRET verlopen crontab -l op VPS, tail /var/log/sync-groups.log, secret roteren
Peer komt online maar krijgt geen IP Setup key verlopen of niet reusable Nieuwe setup key maken, peer opnieuw verbinden
Peer is online maar 192.168.50.x is niet bereikbaar Distribution group ontbreekt of policy = Drop Dashboard → Network Routes → distribution groups én Access Control → Policies controleren
Student-peer kan toch interne hosts pingen OPNsense firewallregel ontbreekt of staat verkeerd Controleer Firewall → Rules → NetBird voor block-regel van students-1e → 192.168.50.0/24 (zie sectie 11.2)
netbird up hangt op "Waiting for browser-based authentication" Browser opent niet op headless client netbird up --management-url ... --setup-key met setup key gebruiken
Containers herstarten constant op VPS Geen disk space of acme.json corrupt df -h, docker volume inspect netbird_traefik_letsencrypt
wt0 verschijnt niet op OPNsense Plugin niet enabled, of UDP 51820 niet open VPN → NetBird → Settings → Enabled, controleer WAN-NAT en firewall
Firefox toont certificaat-waarschuwingen op alle HTTPS CA SECURITYPROJECT_CA niet geïmporteerd Sectie 9, CA opnieuw importeren in Firefox

Bronnen