diff --git a/content/en/docs/Integrations/Office/about.md b/content/en/docs/Integrations/Office/about.md index ade5c7b..31f0b5c 100644 --- a/content/en/docs/Integrations/Office/about.md +++ b/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://: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://:81"`. #### 3. Reverse Proxy Configuration diff --git a/content/en/docs/Integrations/Office/configuration.md b/content/en/docs/Integrations/Office/configuration.md index c27638f..a46580f 100644 --- a/content/en/docs/Integrations/Office/configuration.md +++ b/content/en/docs/Integrations/Office/configuration.md @@ -109,22 +109,32 @@ server {
```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.
diff --git a/content/en/docs/Integrations/Office/troubleshooting.md b/content/en/docs/Integrations/Office/troubleshooting.md index 1ccea88..1ecc245 100644 --- a/content/en/docs/Integrations/Office/troubleshooting.md +++ b/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 diff --git a/content/en/docs/configuration/Authentication/oidc.md b/content/en/docs/configuration/Authentication/oidc.md index 9089e80..1e23a4d 100644 --- a/content/en/docs/configuration/Authentication/oidc.md +++ b/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. diff --git a/content/en/docs/configuration/Authentication/proxy.md b/content/en/docs/configuration/Authentication/proxy.md index 9f16291..8d9d658 100644 --- a/content/en/docs/configuration/Authentication/proxy.md +++ b/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 %}} + ## Next Steps diff --git a/content/en/docs/configuration/http.md b/content/en/docs/configuration/http.md index 7081940..724e6b7 100644 --- a/content/en/docs/configuration/http.md +++ b/content/en/docs/configuration/http.md @@ -125,15 +125,21 @@ 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. @@ -141,13 +147,21 @@ If unset, share links are built from the incoming request (`Host` header and sch ### 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" />}}. @@ -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 %}} diff --git a/content/en/docs/getting-started/v2/migration.md b/content/en/docs/getting-started/v2/migration.md index d2c1e4a..c87ea3b 100644 --- a/content/en/docs/getting-started/v2/migration.md +++ b/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" />}}. +
diff --git a/content/en/docs/user-guides/office-integration/traefik-setup.md b/content/en/docs/user-guides/office-integration/traefik-setup.md index 8cb808f..a51d365 100644 --- a/content/en/docs/user-guides/office-integration/traefik-setup.md +++ b/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