iframe fails silently on untrusted/expired TLS cert — surface a help link instead

[dj4oC]

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

[dj4oC]

Applies to Keycloak etc as well