diff --git a/public/docs-static/img/how-to-guides/browser-client/peer-list-view.png b/public/docs-static/img/how-to-guides/browser-client/peer-list-view.png new file mode 100644 index 00000000..9e488b9e Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/peer-list-view.png differ diff --git a/public/docs-static/img/how-to-guides/browser-client/rdp-certificate-modal.png b/public/docs-static/img/how-to-guides/browser-client/rdp-certificate-modal.png new file mode 100644 index 00000000..c61f11e7 Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/rdp-certificate-modal.png differ diff --git a/public/docs-static/img/how-to-guides/browser-client/rdp-connected-session.png b/public/docs-static/img/how-to-guides/browser-client/rdp-connected-session.png new file mode 100644 index 00000000..894c0f60 Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/rdp-connected-session.png differ diff --git a/public/docs-static/img/how-to-guides/browser-client/rdp-credentials-modal.png b/public/docs-static/img/how-to-guides/browser-client/rdp-credentials-modal.png new file mode 100644 index 00000000..6d675d4c Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/rdp-credentials-modal.png differ diff --git a/public/docs-static/img/how-to-guides/browser-client/ssh-credentials-modal.png b/public/docs-static/img/how-to-guides/browser-client/ssh-credentials-modal.png new file mode 100644 index 00000000..4d89a059 Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/ssh-credentials-modal.png differ diff --git a/public/docs-static/img/how-to-guides/browser-client/ssh-terminal-connected.png b/public/docs-static/img/how-to-guides/browser-client/ssh-terminal-connected.png new file mode 100644 index 00000000..d85b2e75 Binary files /dev/null and b/public/docs-static/img/how-to-guides/browser-client/ssh-terminal-connected.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index bc2c3a15..9a53c85c 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -20,6 +20,7 @@ export const docsNavigation = [ { title: 'How NetBird Works', href: '/about-netbird/how-netbird-works'}, { title: 'NetBird vs. Traditional VPN', href: '/about-netbird/netbird-vs-traditional-vpn' }, { title: 'Why WireGuard with NetBird', href: '/about-netbird/why-wireguard-with-netbird' }, + { title: 'Browser Client Architecture', href: '/about-netbird/browser-client-architecture' }, { title: 'FAQ', href: '/about-netbird/faq' }, /*{ title: 'Whats new in version xx', href: '/welcome/how-netbird-works' }, { title: 'Release notes', href: '/about-netbird/netbird-vs-traditional-vpn' },*/ @@ -56,6 +57,7 @@ export const docsNavigation = [ { title: 'Add Peers', href: '/how-to/add-machines-to-your-network' }, { title: 'Approve Peers', href: '/how-to/approve-peers' }, { title: 'Setup Keys', href: '/how-to/register-machines-using-setup-keys' }, + { title: 'Browser Client', href: '/how-to/browser-client' }, { title: 'Lazy Connections', href: '/how-to/lazy-connection'}, { title: 'Access Infrastructure', diff --git a/src/pages/about-netbird/browser-client-architecture.mdx b/src/pages/about-netbird/browser-client-architecture.mdx new file mode 100644 index 00000000..d7786d81 --- /dev/null +++ b/src/pages/about-netbird/browser-client-architecture.mdx @@ -0,0 +1,116 @@ +import {Note} from "@/components/mdx"; + +# Browser Client Technical Architecture + +The NetBird Browser Client enables secure remote connections directly from web browsers without requiring client software installation. This document provides a technical overview of the Browser Client's architecture, implementation, and security model. + +## Architecture Overview + +The Browser Client architecture implements a complete NetBird peer in the browser environment. +**All connections are made directly from the user's browser to target peers** - the management server never connects to or proxies connections to target machines. It only handles peer registration, configuration, and key distribution. + +### Core Components + +The Browser Client runs two WASM modules: the NetBird client (which handles SSH, WireGuard tunneling, and networking) and IronRDP (for RDP protocol handling). + +#### 1. WebAssembly NetBird Client + +The heart of the Browser Client is a NetBird peer compiled to WebAssembly (WASM): + +- **Language**: Go using Go's native WASM support +- **Runtime**: Executes in the browser's WASM sandbox +- **WireGuard**: Uses the standard wireguard-go + +The WASM client shares the same codebase as native NetBird clients but is adapted for the browser environment. All traffic routes through NetBird relay servers using WebSocket while maintaining end-to-end WireGuard encryption. + +#### 2. IronRDP WASM Module + +The RDP functionality is provided by [IronRDP](https://github.com/Devolutions/IronRDP), a performant RDP client compiled to WebAssembly: + +- **Language**: Rust compiled to WASM +- **License**: Copyright (c) 2022 Devolutions Inc., licensed under the Apache 2.0 or MIT license +- **Runtime**: Executes in the browser's WASM sandbox +- **Protocol**: Handles RDP protocol encoding/decoding +- **Proxy Component**: Uses the RDCleanPath proxy client component + +IronRDP communicates with target RDP servers through a custom Go-based RDCleanPath bridge that runs within the NetBird WASM client, routing traffic through NetBird tunnels. + +#### 3. Protocol Bridges + +##### SSH Bridge + +SSH connections are handled by the NetBird WASM client with a browser-based terminal UI: + +- **SSH Client**: Implemented by the NetBird client +- **Terminal UI**: [xterm.js](https://github.com/xtermjs/xterm.js) provides the terminal interface +- **Connection**: The SSH client connects to NetBird's embedded SSH server (port 44338) on target peers + +##### RDP Bridge + +RDP connections use the IronRDP WASM module with a custom RDCleanPath bridge: + +- **Client-side**: The RDCleanPath proxy component from IronRDP runs in the IronRDP WASM module +- **Server-side**: A custom Go implementation of the RDCleanPath server runs within the NetBird WASM client +- **Function**: Bridges RDP traffic from the RDCleanPath proxy through NetBird tunnels to the target RDP server +- **Security**: Handles certificate validation and caching + +## Connection Flow + +### 1. Temporary Access Registration + +The Browser Client uses NetBird's temporary access mechanism: + +1. **Generate WireGuard key pair**: +- Browser JavaScript generates a WireGuard key pair +- The public key is used for peer registration +- The private key is passed to the WASM client for authentication with the management server +2. **Request temporary access** via the `/peers/{peerId}/temporary-access` endpoint: +- **Requires admin privileges**: Uses the logged-in dashboard user's credentials to create resources +- Creates a short-lived peer with auto-expiry +- Establishes temporary ACL rules (`tcp/22`, `tcp/3389`, `tcp/44338`) +- Associates the peer with the requesting user +- Pre-registers the peer instead of letting the WASM client register (enables immediate ACL application and proper cleanup) +3. **Authentication**: +- The browser client uses the pre-generated WireGuard key pair for authentication with the management server +- This bypasses the usual JWT/OIDC or setup key flow used during peer registration +- Normal clients: JWT/OIDC or setup key for initial registration → then the WireGuard key for auth and encryption +- Browser client: Pre-registered with a WireGuard key → the WireGuard key is used directly for auth and encryption + +### 2. Data Flow + +Once connected, data flows through multiple layers: + +``` +User Input → Browser Events → [WASM: Protocol Client (SSH/IronRDP) → NetBird Tunnel] → +WebSocket → Relay Server → Target Peer → Target Service +``` + +The return path follows the reverse flow for responses. + +#### Packet Encapsulation + +Traffic is encapsulated through multiple protocol layers: + +1. **Application Layer**: SSH/RDP protocol packets +2. **TCP Layer**: Application packets wrapped in TCP segments +3. **WireGuard Layer**: TCP segments encapsulated in encrypted WireGuard frames +4. **Relay Protocol**: WireGuard frames wrapped in relay protocol frames +5. **WebSocket Layer**: Relay frames transmitted over WebSocket connection +6. **TLS Layer**: WebSocket connection secured with TLS +7. **Standard Network Stack**: TCP/IP and lower OSI layers handle final transmission + +This multi-layer approach ensures end-to-end encryption (WireGuard) while enabling browser compatibility (WebSocket/TLS) and relay-based transport. + +## Network Architecture + +### WebSocket to gRPC Proxy + +The Browser Client communicates with NetBird services through WebSocket proxies: + +- **Management Server**: WebSocket to gRPC proxy at the `/ws-proxy` endpoint +- Wraps gRPC stream bytes in a WebSocket connection +- Enables the browser to communicate with the gRPC-based management API +- **Signal Server**: WebSocket proxy at the `/ws-proxy` endpoint for the signaling protocol +- **Relay Servers**: WebSocket connections for WireGuard tunnel transport + +These proxies run alongside the respective NetBird services and translate between browser-compatible WebSocket and internal gRPC protocols. diff --git a/src/pages/how-to/browser-client.mdx b/src/pages/how-to/browser-client.mdx new file mode 100644 index 00000000..802d73c1 --- /dev/null +++ b/src/pages/how-to/browser-client.mdx @@ -0,0 +1,177 @@ +# Browser Client - Web-based Remote Access + +NetBird's Browser Client enables secure remote access to SSH and RDP resources directly from your web browser, without requiring any client software installation. This feature runs a NetBird peer as WebAssembly (WASM) in your browser, establishing secure connections through your existing NetBird network. + +## Overview + +The Browser Client provides instant, secure remote access through your browser: +- **No installation required** - Works directly in your browser without any software downloads +- **SSH and RDP support** - Access Linux and Windows machines with complete protocol implementations +- **Secure by design** - All connections are encrypted end-to-end with WireGuard® +- **True peer-to-peer** - Runs a complete NetBird peer as WebAssembly in your browser +- **Works anywhere** - Access your resources from any device with a modern web browser + + + The Browser Client is a real NetBird peer running entirely in your browser. The management server does not connect to target machines - all connections are made directly from your browser to the target peer through the NetBird network. + + +## Prerequisites + +Before using the Browser Client, ensure: + +1. **Admin privileges** - You must be logged into the NetBird dashboard with an admin account (required for temporary ACL creation) +2. **Protocol requirements**: + - **For SSH**: The NetBird SSH server must be enabled on the target peer + - **For RDP**: The RDP server must be enabled on the target machine +3. **Modern browser** - You're using an up-to-date version of Chrome, Firefox, Edge, or Safari with WebAssembly support + +## Accessing Machines via the Browser Client + +### Quick Access from the Peers List + +The easiest way to connect is directly from the Peers dashboard: + +1. Navigate to the **Peers** section in your NetBird dashboard +2. Find the peer you want to access +3. In the **Remote Access** section, click the **Launch Console** or **Remote Desktop** button + +

+ peer-list-view +

+ +### SSH Connection + +When connecting via SSH: + +1. Click the **Launch Console** button for your target peer +2. A credentials modal will appear + +

+ ssh-credentials-modal +

+ +3. Adjust the SSH username in the credentials modal if required +4. Click **Connect** +5. A terminal window will open in your browser with your SSH session + +

+ ssh-terminal-connected +

+ + + **NetBird SSH Required**: The target peer must have NetBird's SSH server enabled. Learn how to [enable SSH access](/how-to/cli#ssh). + + +### RDP Connection + +For Remote Desktop access: + +1. Click the **Remote Desktop** button for your target machine +2. A new window will open with a credentials modal - enter your RDP server credentials: + +

+ rdp-credentials-modal +

+ + - **Username**: Your username (can include domain: `DOMAIN\username`) + - **Password**: Your password for the RDP server + +3. Click **Connect** +4. In the same window, a certificate warning dialog will appear - review the certificate details + +

+ rdp-certificate-modal +

+ + + Certificate warnings appear for all RDP connections because the Browser Client cannot access the browser's native certificate store for validation. Accepted certificates are remembered using browser storage. + + +5. Click **Accept and Continue** to proceed with the connection +6. The remote desktop will load in the window + +

+ rdp-connected-session +

+ +## Connection Management + +### Active Sessions + +While connected through the Browser Client: + +- **Session persistence**: Sessions remain active as long as the browser tab is open +- **Multiple connections**: Open multiple tabs for concurrent sessions to different peers +- **Clipboard support**: Copy and paste text between host and RDP in both directions + +### Session Security + +The Browser Client maintains NetBird's security standards: + +- **End-to-end encryption**: All traffic is encrypted using WireGuard® +- **Temporary access**: Uses NetBird's temporary access mechanism that: + - Creates short-lived peers with WireGuard keys generated in the browser + - Establishes temporary ACL rules (TCP/22, TCP/3389) + - Automatically removes the peer and ACLs when the session ends +- **No data persistence**: Keys and credentials exist only in browser memory + +## Troubleshooting + +### Common Connection Issues + +**"Failed to initialize WASM"** +- Clear your browser cache and cookies +- Ensure JavaScript is enabled +- Check if your browser supports WebAssembly +- Try using a different browser + +**"Connection timeout"** +- Check that the SSH/RDP services are running on the target + +**"Authentication failed"** +- For RDP, try including the domain in the username (e.g., `DOMAIN\username`) + +## Known Limitations + +**RDP Compatibility** +- Windows 11 and Windows Server 2025 are currently not supported for RDP connections +- Use Windows 10 or earlier Windows Server versions for RDP access + +**Browser Client Constraints** +- **Relay-only connections**: No direct P2P connections (may increase latency) +- **Advanced features**: Some SSH/RDP features are not available (SFTP, sound, file shares, etc.) +- **Concurrent connections**: Browser resource limits may affect multiple simultaneous sessions +- **RDP resolution changes**: Require reconnection (not seamless) + +## Technical Implementation + +For technical details on the Browser Client architecture, see the [Browser Client Technical Architecture](/about-netbird/browser-client-architecture) documentation. + +### SSH Requirements + +For SSH access through the Browser Client: + +- **NetBird SSH must be enabled** on the target peer +- The browser generates WireGuard keys and pre-registers the peer via the temporary access endpoint +- Authentication uses the pre-generated WireGuard key pair (bypassing the usual OIDC or setup key flow) +- The WASM NetBird client handles SSH connections internally + +### RDP Technology Stack + +The RDP implementation is 100% client-side using: + +- **[IronRDP](https://github.com/Devolutions/IronRDP)**: High-performance Rust RDP client (Apache 2.0/MIT licensed) +- **RDCleanPath proxy**: IronRDP's rdp proxy reimplemented to make use of NetBird +- Both components are compiled to WebAssembly and run entirely in the browser + +## Security Considerations + +When using the Browser Client: + +1. **Always connect from trusted devices** - The browser environment should be secure +2. **Use incognito/private mode** on shared computers to ensure no session data persists +3. **Log out properly** - Close the browser tab to ensure the session ends +4. **Keep your browser updated** to receive the latest security patches +5. **Be cautious with browser extensions** that might interfere with or monitor your sessions + +The Browser Client provides a convenient, secure way to access your network resources without installing software, perfect for quick access from any device or when working from temporary workstations.