Native UI · HTTPS requirements

The manager's Native UI tab embeds the FreePBX admin interface in an iframe. For that iframe to render, the PBX must serve HTTPS with a certificate the operator's browser already trusts. This document explains why, what the failure modes look like, and how to fix them using FreePBX's built-in Certificate Manager.

Why HTTPS is required

The manager runs on https://<manager-host>/. Every paired PBX has a stored base_url like https://<pbx-host>/. Modern browsers apply three rules that all point the same direction:

1. Mixed-content block — an HTTPS page cannot iframe an HTTP resource. If the PBX's base_url is http://, the browser silently refuses to load the iframe.
2. Cross-origin cookies require SameSite=None; Secure — the SSO session cookie the manager hands the PBX has to travel cross-origin. Secure means "HTTPS only." Without it, browsers drop the cookie and the user lands back on the PBX login page.
3. Certificate trust chain — for a cross-origin iframe, the browser must trust the certificate. Self-signed and expired certificates block the iframe with no error surfaced. Manually accepting a certificate warning in a top-level tab does not unlock it for iframes.

If any of these fail, the Native UI tab shows a fallback card explaining the block and pointing back here.

The fix — FreePBX's built-in Certificate Manager

FreePBX ships a Certificate Manager module that handles issuance, import, and rotation for both the web UI and TLS/SRTP endpoints. No third-party tooling needed.

On the PBX admin UI (not the manager):

1. Admin → Certificate Management
2. Pick the flow that matches your situation:
3. Let's Encrypt — the PBX must be reachable from the public internet on port 80 or 443 for the ACME challenge. Certificate renews automatically. Best default for internet-facing PBXes.
4. Upload / import — paste an existing chain (PEM + key + intermediate) from your corporate PKI, or a wildcard cert your organization already issues.
5. Self-signed — offered by the module but won't fix the iframe (browsers still refuse untrusted certs cross-origin). Only use this if you accept that Native UI in-iframe will not work; new-tab launch is still available.
6. After the certificate is created / imported, set it as the default certificate for the web UI in Certificate Management, then run fwconsole reload on the PBX (or click Apply Config in the FreePBX header).

Back on the manager: click Reload in the Native UI tab header, or hit Retry iframe on the fallback card. The iframe should render inline within a few seconds.

What if I can't fix HTTPS right now?

Every place in the manager that offers "Open native UI" (Native UI tab, PBX detail action buttons, dashboard tiles) also offers an Open in new tab option. New-tab launch works with self-signed and expired certs, because the browser lets the user click past the warning once per origin.

Prime-the-exception trick for self-signed certs

Iframes normally can't use a "accepted risk" cert override, but in practice most browsers persist the exception widely enough that priming it via a top-level tab unlocks the iframe on retry:

1. On the Native UI fallback card, click Open in new tab ↗.
2. In the new tab, click Advanced → Accept the Risk and Continue (Firefox) or Proceed to <pbx> (unsafe) (Chrome/Edge). The PBX admin loads.
3. Return to the Native UI tab, click Retry iframe. The frame usually loads.

Browser behavior: - Firefox — persists across tabs and iframes for the session; works reliably. - Chrome / Edge — persists within the same profile session; usually works if you retry in the same window. - Safari — narrower persistence; may still block the iframe. Use the new-tab workflow instead.

Data / audit / job dispatch through the manager is unaffected regardless of TLS state — those go over SSH and don't touch the PBX's browser-facing HTTPS.

Long-term shortcut

• On the Native UI tab, use the Open in new tab ↗ button in the header (or on the fallback card).
• On the PBX Status tab, the Open native UI → action button opens in a new tab by default.

Diagnosing "blank iframe" step-by-step

If the Native UI shows the fallback card:

1. Open the PBX in a fresh tab at the exact URL shown as base_url on the PBX Status tab. Does the browser show any certificate warning? If yes → cert issue, fix per above.
2. From the manager's browser, check DevTools → Network → the iframe request. Look for net::ERR_CERT_*, ERR_CONNECTION_REFUSED, or a redirect chain that lands on /login.
3. Verify base_url scheme — Status → Access → Edit. If it starts with http:// change it to https:// (assuming HTTPS is available on the PBX). Save. Retry.
4. Framing toggle — Admin → SSO Pairing on the PBX itself. If "Allow framing from the manager" is off, the PBX sends X-Frame-Options: DENY and the iframe is blocked at the header level, unrelated to HTTPS. Enable it, save, retry.

What the manager does not do

By design, the manager does not provision certificates on paired PBXes. The FreePBX Certificate Manager already handles this and is the correct place to own the cert lifecycle. Duplicating that logic would create competing state, conflict with corporate PKI workflows, and leave asymmetric cruft at unpair time.

If a future release changes this, it will be an explicit opt-in per-pair, not a default.