Eduard Gert
031a4bd70d
* [proxy] Fix npm audit findings in the web UI npm audit reported 10 vulnerabilities (7 high), all in build tooling: Vite/launch-editor, PostCSS, Babel, browserslist, js-yaml, nanoid, brace-expansion and source-map-js. All are resolved by the lockfile update; Vite is pinned exactly, so it is bumped from 7.3.2 to 7.3.7. * [client] Migrate the desktop UI to Tailwind CSS 4 and fix npm audit findings pnpm audit reported 36 vulnerabilities in the desktop UI. All but two (braces and postcss-selector-parser, both pulled in by Tailwind 3 with no patched version in range) are fixed by updating within the existing ranges; react-router moves to 7.18.4, which also fixes an open redirect and an XSS in its error handler. The remaining two go away by moving to Tailwind CSS 4, which the proxy web UI already uses: - The config moves into an @theme block in globals.css; the official upgrade tool applied the v4 utility renames across the components. - @tailwindcss/vite replaces the PostCSS plugin and autoprefixer. - tw-animate-css replaces tailwindcss-animate with the same classes. - The Prettier plugin reads the theme from the stylesheet. A screenshot comparison of every screen against the Tailwind 3 build found three regressions caused by v4's changed utility and variant ordering, fixed here so the UI renders as before: - Label combined inline-block and flex; v4 let inline-block win, which made every settings row taller. The dead inline-block is removed. - The active settings tab lost its highlight in dark mode because dark: now outranks group-data-[state=active]:. The active color is set for dark mode explicitly. - v4 rebuilt its default palette in OKLCH, shifting colors the theme does not override such as sky-400. The Tailwind 3 values for the neutral, zinc, sky, orange and amber families are pinned in @theme. The only remaining visible difference is 2px less height per row in the profiles list, because v4's preflight resets the browser's default table-cell padding.
Netbird Reverse Proxy
The NetBird Reverse Proxy is a separate service that can act as a public entrypoint to certain resources within a NetBird network. At a high level, the way that it operates is:
- Configured routes are communicated from the Management server to the proxy.
- For each route the proxy creates a NetBird connection to the NetBird Peer that hosts the resource.
- When traffic hits the proxy at the address and path configured for the proxied resource, the NetBird Proxy brings up a relevant authentication method for that resource.
- On successful authentication the proxy will forward traffic onwards to the NetBird Peer.
Proxy Authentication methods supported are:
- No authentication
- Oauth2/OIDC
- Emailed Magic Link
- Simple PIN
- HTTP Basic Auth Username and Password
Management Connection and Authentication
The Proxy communicates with the Management server over a gRPC connection. Proxies act as clients to the Management server, the following RPCs are used:
- Server-side streaming for proxied service updates.
- Client-side streaming for proxy logs.
To authenticate with the Management server, the proxy server uses Machine-to-Machine OAuth2. If you are using the embedded IdP //TODO: explain how to get credentials. Otherwise, create a new machine-to-machine profile in your IdP for proxy servers and set the relevant settings in the proxy's environment or flags (see below).
User Authentication
When a request hits the Proxy, it looks up the permitted authentication methods for the Host domain. If no authentication methods are registered for the Host domain, then no authentication will be applied (for fully public resources). If any authentication methods are registered for the Host domain, then the Proxy will first serve an authentication page allowing the user to select an authentication method (from the permitted methods) and enter the required information for that authentication method. If the user is successfully authenticated, their request will be forwarded through to the Proxy to be proxied to the relevant Peer. Successful authentication does not guarantee a successful forwarding of the request as there may be failures behind the Proxy, such as with Peer connectivity or the underlying resource.
Target access control
HTTP targets have an optional access_action setting, configured under
Edit Target → Optional Settings → Access in the dashboard:
| Value | Behavior |
|---|---|
inherit |
Use the service's authentication settings. This is the default. A service without authentication remains public. |
bypass |
Forward anonymously without prompting for service authentication. |
block |
Return HTTP 403, including for authenticated users. |
The longest matching Location prefix selects both the target and its access
action. Prefixes are literal and case-sensitive: /api also matches /apiv2,
while /api/ only matches requests beginning with /api/ and does not match
/api itself. Wildcards and regular expressions are not supported. A blocked
request or failed authentication never falls through to another target. Disabling
or deleting a target removes its rule, so a less-specific target may then match.
Service IP, country, and reputation restrictions still apply to bypassed paths. Bypass is unavailable for private services and Agent Network targets. Bypassed requests have no NetBird user identity; configured header-auth credentials, NetBird session cookies, and client-supplied NetBird identity headers are still removed before forwarding. Custom upstream headers remain target settings, so consider their effect when making a target public.
Services using target access overrides reject ambiguous request paths, including encoded separators and traversal segments, before forwarding. Path rewriting continues to use the selected Location prefix after access checks.
Upgrade all proxies before using target access actions. Older proxies ignore
these actions and continue applying the service's authentication settings.
API updates that omit an existing Location's
access_action preserve its setting; send "access_action": "inherit" explicitly
to restore service authentication. Requests omitting all access actions cannot
remove or rename a controlled Location; use an updated client and explicitly
include the intended actions when changing those targets.
TLS
Due to the authentication provided, the Proxy uses HTTPS for its endpoint, even if the underlying service is HTTP.
Certificate generation can either be via ACME (by default, using Let's Encrypt, but alternative ACME providers can be used) or through certificate files.
When not using ACME, the proxy server attempts to load a certificate and key from the files tls.crt and tls.key in a specified certificate directory.
When using ACME, the proxy server will store generated certificates in the specified certificate directory.
Auth UI
The authentication UI is a Vite + React application located in the web/ directory. It is embedded into the Go binary at build time.
To build the UI:
cd web
npm install
npm run build
For UI development with hot reload (served at http://localhost:3031):
npm run dev
The built assets in web/dist/ are embedded via //go:embed and served by the web.ServeHTTP handler.
Configuration
NetBird Proxy deployment configuration is via flags or environment variables, with flags taking precedence over the environment. The following deployment configuration is available:
| Flag | Env | Purpose | Default |
|---|---|---|---|
-debug |
NB_PROXY_DEBUG_LOGS |
Enable debug logging | false |
-mgmt |
NB_PROXY_MANAGEMENT_ADDRESS |
The address of the management server for the proxy to get configuration from. | "https://api.netbird.io:443" |
-addr |
NB_PROXY_ADDRESS |
The address that the reverse proxy will listen on. | ":443 |
-url |
NB_PROXY_URL |
The URL that the proxy will be reached at (where endpoints will be CNAMEd to). If unset, this will fall back to the proxy address. | "proxy.netbird.io" |
-cert-dir |
NB_PROXY_CERTIFICATE_DIRECTORY |
The location that certificates are stored in. | "./certs" |
-acme-certs |
NB_PROXY_ACME_CERTIFICATES |
Whether to use ACME to generate certificates. | false |
-acme-addr |
NB_PROXY_ACME_ADDRESS |
The HTTP address the proxy will listen on to respond to HTTP-01 ACME challenges | ":80" |
-acme-dir |
NB_PROXY_ACME_DIRECTORY |
The directory URL of the ACME server to be used | "https://acme-v02.api.letsencrypt.org/directory" |
-oidc-id |
NB_PROXY_OIDC_CLIENT_ID |
The OAuth2 Client ID for OIDC User Authentication | "netbird-proxy" |
-oidc-secret |
NB_PROXY_OIDC_CLIENT_SECRET |
The OAuth2 Client Secret for OIDC User Authentication | "" |
-oidc-endpoint |
NB_PROXY_OIDC_ENDPOINT |
The OAuth2 provider endpoint for OIDC User Authentication | "https://api.netbird.io/oauth2" |
-oidc-scopes |
NB_PROXY_OIDC_SCOPES |
The OAuth2 scopes for OIDC User Authentication, comma separated | "openid,profile,email" |