Trusted headers docs update

content/en/docs/Integrations/Office/about.md

@@ -124,7 +124,7 @@ integrations:
 
 #### 2. Bare Metal Setup
 
-This is same as previous section except that you will need to use IP address and port of the host system of the respective services. By default, both FileBrowser and OnlyOffice use port `80`. If you have set up in the same system, change `server.port` to `81` and `server.internalUrl` to `"http://<YourLocalIP>:81"`.
+This is same as previous section except that you will need to use IP address and port of the host system of the respective services. By default, both FileBrowser and OnlyOffice use port `80`. If you have set up in the same system, change `http.port` to `81` and `http.internalUrl` to `"http://<YourLocalIP>:81"`.
 
 
 #### 3. Reverse Proxy Configuration

content/en/docs/Integrations/Office/configuration.md

@@ -109,22 +109,32 @@ server {
 <div class="pattern-card">
 
 ```yaml
-server:
-  externalUrl: "https://files.yourdomain.com"  # Accessible from browser
-  internalUrl: "http://192.168.1.100"         # Either use local network or docker network IP thats accessible from onlyoffice server.
+http:
+  externalUrl: "https://files.yourdomain.com"  # Public URL (browser / shares)
+  internalUrl: "http://filebrowser:80"         # Docker/LAN URL OnlyOffice uses to reach FileBrowser
+  baseURL: "/files"
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
 
 integrations:
   office:
-    url: "https://office.yourdomain.com"       # Accessible from browser
-    internalUrl: # optional this should be a local network address that FileBrowser can access.
+    url: "https://office.yourdomain.com"       # Browser → OnlyOffice
+    internalUrl: "http://onlyoffice:80"        # FileBrowser → OnlyOffice (optional)
     secret: "your-jwt-secret"
 ```
 
-**Why two URLs?**
+**Why multiple URLs?**
 
-- **Browser** → The browser always uses `integrations.office.url` to connect from your browser to only office server.
-- **OnlyOffice** → Uses either `server.externalUrl` or `server.internalUrl` for downloading/saving files to FileBrowser server.
-- **FileBrowser** → Uses either `integratons.office.internalUrl` or `integrations.office.url` to connect from the FileBrowser server to OnlyOffice server.
+| Direction | Config | Purpose |
+|-----------|--------|---------|
+| Browser → OnlyOffice | `integrations.office.url` | Editor UI loaded in the browser |
+| FileBrowser → OnlyOffice | `integrations.office.internalUrl` (or `url`) | Server-side API calls |
+| OnlyOffice → FileBrowser | `http.internalUrl` → `http.externalUrl` → request | Download/callback URLs embedded in editor config |
+
+- **`http.trustedHeaders`** affects user-facing request flows (cookies, OIDC, activity IP). It does **not** gate `http.internalUrl`.
+- **`http.externalUrl`** is used for shares and (when `internalUrl` is unset) OnlyOffice paths — **not** for OIDC redirects.
 
 </div>
 

content/en/docs/Integrations/Office/troubleshooting.md

@@ -244,14 +244,18 @@ networks:
 
 **FileBrowser Config:**
 ```yaml
-server:
+http:
   externalUrl: "https://files.yourdomain.com"
   internalUrl: "http://filebrowser:80"
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
 
 integrations:
   office:
     url: "https://office.yourdomain.com"
-    internalUrl: "https://onlyoffice" # (optional) this is the internal url that the filebrowser server can communicate with directly. otherwise url is used
+    internalUrl: "http://onlyoffice:80" # (optional)
     secret: "your-secret"
 ```
 
@@ -296,6 +300,14 @@ server {
 
 **FileBrowser Config:**
 ```yaml
+http:
+  internalUrl: "http://filebrowser:80"
+  externalUrl: "https://files.yourdomain.com"
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
+
 integrations:
   office:
     url: "https://office.yourdomain.com"
@@ -355,19 +367,23 @@ onlyoffice:
 
 ### External and Internal URLs
 
-See {{< doclink path="integrations/office/configuration#external-and-internal-urls" text="Configuration" />}}
+See {{< doclink path="integrations/office/configuration#external-and-internal-urls" text="Configuration" />}} for the full URL priority table (`http.internalUrl` → `http.externalUrl` → request).
+
+### 401 or connection refused behind reverse proxy
+
+When FileBrowser is on a subpath (for example `/files/`) behind HTTPS nginx:
 
-**Why two URLs?**
+1. Set `http.trustedHeaders` including `X-Forwarded-Proto` and `X-Forwarded-Host` on FileBrowser.
+2. Set `http.internalUrl` to a URL OnlyOffice can reach on the Docker/LAN network (for example `http://filebrowser:80`).
+3. Optionally set `http.externalUrl` if OnlyOffice cannot use the internal URL but shares the same public host as users.
 
-- **Browser** → The browser always uses `integrations.office.url` to connect from your browser to only office server.
-- **OnlyOffice** → Uses either `server.externalUrl` or `server.internalUrl` for downloading/saving files to FileBrowser server.
-- **FileBrowser** → Uses either `integratons.office.internalUrl` or `integrations.office.url` to connect from the filebrowser server to OnlyOffice server.
+Download/callback URLs embedded in the editor config use that priority — they do **not** read raw `X-Forwarded-*` unless falling back to the request path with `trustedHeaders` configured.
 
 ## Performance Issues
 
 ### Slow Document Loading
 
-Document loading can be quite slow because of the many components onlyoffice needs to talk to. The best way to improve document loading times it to set `server.internalUrl` so OnlyOffice can communicate directly with filebrowser (it's possible on same private network).
+Document loading can be quite slow because of the many components onlyoffice needs to talk to. The best way to improve document loading times is to set `http.internalUrl` so OnlyOffice can communicate directly with FileBrowser on the same private network.
 
 ## Download Fails
 

content/en/docs/configuration/Authentication/oidc.md

@@ -8,6 +8,10 @@ lastmod: "2026-04-20T18:55:31Z"
 
 Integrate with OpenID Connect providers for single sign-on.
 
+{{% alert context="info" %}}
+**OIDC callback URL:** FileBrowser does **not** use `http.externalUrl` for OIDC. Register your provider callback from the URL you actually use to log in (for example `https://files.example.com/files/api/auth/oidc/callback`). See [Callback URL](#callback-url) below.
+{{% /alert %}}
+
 ## Basic Setup
 
 ```yaml
@@ -77,6 +81,25 @@ If you use a custom `baseURL` in your `config.yaml`:
 https://your-domain.com/custom-base/api/auth/oidc/callback
 ```
 
+## Reverse proxy (v2.0.0+)
+
+When FileBrowser sits behind HTTPS nginx, Traefik, or Caddy, the incoming request often arrives as `http://` with the proxy's internal host. Configure forwarded headers so the request-derived callback uses the browser-facing scheme and host:
+
+```yaml
+http:
+  baseURL: "/files"
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
+```
+
+Your proxy must send at least `X-Forwarded-Proto: https` and `X-Forwarded-Host` matching the browser URL. Without them, the callback may register as `http://` or the wrong host and your OIDC provider will reject login.
+
+On startup, FileBrowser logs a **warning** when OIDC is enabled but `X-Forwarded-Proto` or `X-Forwarded-Host` is missing from `trustedHeaders`.
+
+See {{< doclink path="getting-started/reverse-proxy/" text="Running behind a reverse proxy" />}} and {{< doclink path="configuration/http/#trustedheaders" text="HTTP trustedHeaders" />}}.
+
 ## Auto-Redirect
 
 When OIDC is the only auth method, users are automatically redirected to the OIDC provider.

content/en/docs/configuration/Authentication/proxy.md

@@ -98,6 +98,12 @@ server {
 FileBrowser config:
 
 ```yaml
+http:
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
+
 auth:
   methods:
     proxy:
@@ -107,6 +113,10 @@ auth:
       enabled: false
 ```
 
+{{% alert context="info" %}}
+`auth.methods.proxy.header` names the **username** header. Client IP and scheme/host forwarding use the separate `http.trustedHeaders` list — see {{< doclink path="configuration/http/#trustedheaders" text="HTTP trustedHeaders" />}}.
+{{% /alert %}}
+
 </div>
 
 ## Next Steps

content/en/docs/configuration/http.md

@@ -125,29 +125,43 @@ When TLS is enabled, the server logs an `https://` URL. **Cannot be combined** w
 
 ### externalUrl
 
-Public base URL used when generating share links (optional). Include scheme and host; `baseURL` is appended automatically when needed.
+Public base URL used when generating links. Include scheme and host only — `baseURL` is appended automatically when needed.
 
 ```yaml
 http:
-  externalUrl: "https://files.example.com"
+  externalUrl: "https://files.example.com" # will automatically apply /files if missing
   baseURL: "/files"
 ```
 
-If unset, share links are built from the incoming request (`Host` header and scheme).
+| Used for | Not used for |
+|----------|--------------|
+| Share links and Open Graph metadata | OIDC `redirect_uri` (always derived from the incoming request) |
+| OnlyOffice download/callback URLs when `internalUrl` is unset | WebAuthn RP ID (uses `externalUrl` when set, else request host) |
+| | Session cookies or login redirects |
+
+If unset, share links and OnlyOffice public-path URLs fall back to the incoming request (`Host` header and scheme). Behind a reverse proxy, list `X-Forwarded-Proto` and `X-Forwarded-Host` in `http.trustedHeaders` so request-derived URLs use the client-facing scheme and host.
 
 </div>
 
 <div class="pattern-card">
 
 ### internalUrl
 
-Base URL integration services use to reach FileBrowser on the network (optional). Used by OnlyOffice and similar integrations when the public URL is not reachable from the integration container.
+Base URL integration services use to reach FileBrowser on the **private network** (optional). HTTP is allowed. This path does **not** use `trustedHeaders` — it is a fixed configured origin, not derived from proxied client requests.
 
 ```yaml
 http:
   internalUrl: "http://filebrowser:80"
+  baseURL: "/files"
 ```
 
+| Used for | Not used for |
+|----------|--------------|
+| OnlyOffice download/callback URLs (highest priority) | Share links shown in the browser |
+| | OIDC redirects |
+
+**URL priority for OnlyOffice → FileBrowser:** `internalUrl` → `externalUrl` → incoming request (with `trustedHeaders` when behind a proxy).
+
 Typically a Docker service name, internal DNS name, or LAN IP. See {{< doclink path="integrations/office/configuration/" text="OnlyOffice configuration" />}}.
 
 </div>
@@ -193,6 +207,10 @@ Supported headers:
 
 Scheme and host headers affect cookies, OIDC `redirect_uri`, share URLs, WebAuthn, and integrations. Client IP headers affect rate limiting, lockout, and activity logging.
 
+{{% alert context="warning" %}}
+**v2.0.0+:** Forwarded headers are **opt-in**. FileBrowser ignores `X-Forwarded-*` values unless the header name appears in `http.trustedHeaders`. Upgrades from v1.x behind a reverse proxy must add this list or client IP, OIDC callbacks, cookies, and subpath URLs may break.
+{{% /alert %}}
+
 {{% alert context="info" %}}
 **Proxy authentication username** headers (for example `X-Forwarded-User`) are **not** configured here. Set the header name under `auth.methods.proxy.header`. See {{< doclink path="configuration/authentication/proxy/" text="Proxy authentication" />}}.
 {{% /alert %}}

content/en/docs/getting-started/v2/migration.md

@@ -77,6 +77,24 @@ Paths are relative to the FileBrowser working directory (standalone) or your mou
 - If you already mount a **data directory** (recommended in {{< doclink path="getting-started/docker/" text="Docker setup" />}}), no volume changes are needed.
 - **Only update mounts** if you currently bind-mount a **single database file** — switch to a directory mount so the renamed BoltDB and new SQLite can coexist during migration.
 
+### Reverse proxy and trusted headers
+
+If FileBrowser runs behind a reverse proxy (especially on a subpath such as `/files/`), add `http.trustedHeaders` after migrating config keys from `server` to `http`:
+
+```yaml
+http:
+  baseURL: "/files"
+  trustedHeaders:
+    - X-Forwarded-For
+    - X-Real-IP
+    - X-Forwarded-Proto
+    - X-Forwarded-Host
+```
+
+v2.0.0+ **ignores** forwarded headers unless they are listed. Without this, activity logs may show the proxy IP, OIDC callbacks may use `http://`, and cookies may not bind to the public host.
+
+The {{< doclink path="getting-started/v2/config-migration/" text="config migration tool" />}} warns when OIDC is enabled but these headers are missing. See {{< doclink path="getting-started/reverse-proxy/" text="Reverse proxy guide" />}}.
+
 </div>
 
 <div class="pattern-card">

content/en/docs/user-guides/office-integration/traefik-setup.md

@@ -647,8 +647,8 @@ integrations:
 
 {{% alert context="warning" %}}
 **Critical Configuration:**
-- `server.externalUrl`: Must match your FileBrowser domain configured in `.env` file.
-- `server.internalUrl`: Uses Docker service name `onlyoffice` and its internal port (80).
+- `http.externalUrl`: Must match your FileBrowser domain configured in `.env` file.
+- `http.internalUrl`: Uses Docker service name reachable from OnlyOffice (for example `http://filebrowser:80`).
 - `integrations.office.url`: Must match your OnlyOffice domain configured on the `.env` file of OnlyOffice.
 - `integrations.office.secret`: Must match OnlyOffice `JWT_SECRET` exactly (also in the onlyoffice `.env`)
 {{% /alert %}}
@@ -798,7 +798,7 @@ server:
 integrations:
   office:
     url: "https://office.yourdomain.com"
-    internalUrl: "http://onlyoffice:80"
+    internalUrl: "http://onlyoffice:80" # (optional)
 ```
 
 ### Other issues