Add browser client docs (#435)

* Add browser client docs * Address review
2026-04-19 08:56:35 +00:00 · 2025-10-01 15:53:57 +02:00
parent d24375c2e6
commit 81ed300b8c
9 changed files with 295 additions and 0 deletions
--- a/src/pages/how-to/browser-client.mdx
+++ 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
+
+<Note>
+    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.
+</Note>
+
+## 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
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/peer-list-view.png" alt="peer-list-view" className="imagewrapper-big"/>
+</p>
+
+### SSH Connection
+
+When connecting via SSH:
+
+1. Click the **Launch Console** button for your target peer
+2. A credentials modal will appear
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/ssh-credentials-modal.png" alt="ssh-credentials-modal" className="imagewrapper-big"/>
+</p>
+
+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
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/ssh-terminal-connected.png" alt="ssh-terminal-connected" className="imagewrapper-big"/>
+</p>
+
+<Note>
+    **NetBird SSH Required**: The target peer must have NetBird's SSH server enabled. Learn how to [enable SSH access](/how-to/cli#ssh).
+</Note>
+
+### 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:
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/rdp-credentials-modal.png" alt="rdp-credentials-modal" className="imagewrapper-big"/>
+</p>
+
+   - **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
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/rdp-certificate-modal.png" alt="rdp-certificate-modal" className="imagewrapper-big"/>
+</p>
+
+<Note>
+    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.
+</Note>
+
+5. Click **Accept and Continue** to proceed with the connection
+6. The remote desktop will load in the window
+
+<p>
+    <img src="/docs-static/img/how-to-guides/browser-client/rdp-connected-session.png" alt="rdp-connected-session" className="imagewrapper-big"/>
+</p>
+
+## 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.