iframe fails silently on untrusted/expired TLS cert — surface a help link instead
- Dominant language
- Go
- Stars
- 2.1k
- Forks
- 274
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 103
Description
## Is your feature request related to a problem? Please describe.
When oCIS embeds a WOPI-based editor (Collabora Online, ONLYOFFICE) in an iframe, and the browser cannot establish a trusted connection to that editor's origin (most commonly: a self-signed/local-dev certificate the browser has never been asked to accept for that specific origin, or a public deployment with an expired certificate), the iframe fails to load with **no error surfaced to the user at all** — it just appears blank/broken.
This is unusually hard to debug because:
- Browsers deliberately don't expose *why* a cross-origin iframe/WebSocket failed to load — a cert error, DNS failure, and "network down" are all indistinguishable to page JS, by design (to prevent fingerprinting of local network/TLS state).
- Server-to-server WOPI discovery (the oCIS `collaboration` service talking to Collabora/ONLYOFFICE) can be completely healthy the whole time, since server-side calls commonly run with relaxed/disabled cert verification for local setups. So nothing looks broken in the logs.
- The failure is purely client-side, so whoever's debugging it can spend a long time checking server logs, service registration, and WOPI discovery, and find nothing wrong — because nothing server-side *is* wrong.
### Concrete repro (using `deployments/examples/ocis_full`)
1. Bring the stack up fresh. Traefik regenerates its self-signed "default cert" on every restart, since `.test`-style domains can't complete an ACME HTTP challenge.
2. Log into the oCIS web app (its origin's cert warning was already accepted previously).
3. Open a document that opens in Collabora/ONLYOFFICE — the editor iframe silently fails to render.
4. The `collaboration` service's logs show **zero requests** — the browser never reached the WOPI handshake at all.
5. Root cause: browser cert-trust exceptions for self-signed certs are scoped per-origin. Accepting the warning for the oCIS domain does nothing for the editor's domain, and there is no way to click through a cert warning from inside an iframe — it just fails silently.
6. Workaround: open the editor's domain directly in a new tab once, accept the warning there, then the iframe works.
## Describe the solution you'd like
Before rendering the editor iframe, have the web frontend do a preflight `fetch()` (e.g. a lightweight request to the app's discovery/health URL). If it rejects:
- Don't try to guess the exact cause — the browser won't tell us, and we shouldn't pretend certainty we don't have.
- Show a banner/dialog in place of a silently blank iframe, with a link to a help page instead of just failing quietly.
- The help page should be **specific to the integrated product** (Collabora and ONLYOFFICE have different discovery endpoints and setup docs) and walk through the likely causes in rough order of likelihood:
- Self-signed/local cert never accepted by the browser for that specific origin → link to open the origin directly and accept it.
- If publicly deployed: cert expired or misconfigured → how to check (e.g. `openssl s_client -connect host:443`) and where to renew.
- Network/firewall reachability between the browser and the editor's public hostname.
This turns a silent, hard-to-diagnose failure into an actionable message, without the frontend ever having to claim certainty about which specific cause it is.
## Describe alternatives you've considered
- Logging more aggressively server-side: doesn't help, since the server-to-server path can be entirely healthy while the browser-side connection fails.
- Trying to sniff the specific failure reason from the browser: not reliably possible — this is an intentional browser security/privacy boundary, not a gap we can work around.
## Additional context
Found while debugging a local `ocis_full` example deployment where this exact silent failure occurred; happy to share more repro details if useful.
🤖 Generated with Claude Code
Contributor guide
Research direction
Start by reproducing the failure with deployments/examples/ocis_full and inspect the web frontend code that renders the WOPI editor iframe. Trace how Collabora and ONLYOFFICE discovery or health URLs are selected, then define the in-place banner or dialog and product-specific help links; done means a rejected preflight produces actionable guidance instead of a silent blank iframe.
Written by the indexing model from the issue text.
Assessment
- Domain
- frontend, web-dev
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100