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¶
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

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¶
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] |
| 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.

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
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.

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

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.

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 |

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:
- Een Azure AD token ophaalt via client credentials
- Alle Netbird-groepen, -peers en -users opvraagt
- GUID-groepen matcht aan Entra displayName via Microsoft Graph
- Leesbare groepen aanmaakt (of bestaande hergebruikt)
- auto_groups van users verplaatst van de GUID naar de leesbare groep
- 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.
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!"
6.3. Cron¶
sudo crontab -eDependencies: 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.

7. OPNsense Netbird-plugin¶
7.1. Plugin installeren¶
Navigeer naar System → Firmware → Plugins en installeer os-netbird. Na installatie verschijnt het menu VPN → NetBird.

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 |

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.

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¶
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

<!-- 📸 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:
Voor een student (Mariam):
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
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:
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 |
| 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¶
- Netbird documentatie: https://docs.netbird.io/
- Netbird self-hosted quickstart: https://docs.netbird.io/selfhosted/selfhosted-quickstart
- Microsoft Entra ID OIDC integratie: https://docs.netbird.io/selfhosted/identity-providers
- WireGuard protocol: https://www.wireguard.com/
- OPNsense Netbird plugin: <https://github.com/opnsense/plugins/tree/master/sec