Skip to content

Client setup for the captive portal

When EnforceGate vX runs as an explicit proxy, every client machine needs a small one-time configuration to reach the captive portal cleanly:

  1. Bypass the proxy for the portal host (so the browser talks to the portal directly instead of asking the proxy to tunnel it).
  2. Trust the appliance's bump CA (so the portal's TLS certificate validates).

Both steps are delivered centrally to the fleet — you don't ask users to edit browser settings by hand. This page walks through the three common delivery paths (PAC / WPAD, GPO / MDM, manual per-client) and where to find the values you need.

The symptom this page fixes

A client is redirected to the captive portal and the browser shows:

Secure Connection Failed — SSL_ERROR_RX_RECORD_TOO_LONG (Chrome / Edge: ERR_SSL_PROTOCOL_ERROR)

The portal never renders. Everything on the appliance is healthy.

Why it happens. With an explicit proxy, the client's browser sends every request to the EnforceGate proxy — including the portal redirect. When the engine answers a blocked request with 302 → https://<portal-host>, the browser doesn't go straight to the portal; it asks the proxy to tunnel CONNECT <portal-host>:443. That round-trip doesn't cleanly reach the portal's TLS listener, so the browser's https handshake lands on a plain-HTTP response and aborts with SSL_ERROR_RX_RECORD_TOO_LONG.

Fix. The portal host must bypass the proxy. This is not an EnforceGate quirk — Zscaler, Palo Alto Prisma, FortiGate and every other explicit-proxy gateway require the same portal / CA bypass.

Why going direct is the correct path, not a workaround

Beyond fixing the RX error, the portal needs to see the real client IP to attribute the acknowledgement to the right operator — going through the proxy would give the portal the proxy's IP, breaking per-client ack_scope. Going direct is the correct operational path.

Step 1: bypass the proxy for the portal host

Bypass two hosts on every client:

Host Purpose
<portal-host> — the appliance's ENFORCEGATE_CAPTIVE_HOSTNAME the captive portal itself — the redirect target
http://<portal-host>/ca the one-time bump-CA download / trust page

Pick whichever delivery path matches how your site already distributes proxy configuration:

Return DIRECT for the portal host and PROXY for everything else:

proxy.pac
function FindProxyForURL(url, host) {
    // Captive portal + CA download must bypass the proxy.
    if (shExpMatch(host, "portal.example.com")) return "DIRECT";
    // Everything else goes through the EnforceGate proxy.
    return "PROXY 10.0.0.1:3128";
}

Host the file and point clients at it via WPAD auto-discovery, DHCP option 252, or a GPO / MDM "Automatic configuration script" URL. One file → every client fixed, and client IPs are preserved end-to-end.

The standalone bundle ships a pre-filled proxy.pac.example — swap in your portal host and proxy IP.

If clients are configured by policy rather than PAC, add <portal-host> to the proxy exceptions / "bypass proxy server for" / no-proxy list:

  • Windows (GPO / Intune) — Proxy settings → Use the proxy server except for addresses that start with… → add the portal host.
  • macOS (Jamf / MDM) — Network → Proxies → Bypass proxy settings for these Hosts & Domains → add the portal host.
  • Firefox (enterprise policy) — network.proxy.no_proxies_on → add the host.
  • Linux / CLI tools — no_proxy=<portal-host> in the environment.

Browser proxy settings → Exceptions / Bypass → add <portal-host>. Not for fleet rollout — every machine is configured by hand. Use this only for lab validation or a single-machine setup.

Step 2: trust the appliance's bump CA

The portal is served with a certificate signed by the appliance's bump CA. Once the proxy bypass is in place, clients that haven't installed the CA will see a certificate warning on the portal — this is expected and distinct from the SSL_ERROR_RX_RECORD_TOO_LONG above.

Install the CA once, fleet-wide, from:

  • http://<portal-host>/ca — HTML install page with per-OS instructions.
  • http://<portal-host>/ca.crt — raw PEM for scripted push via GPO / MDM.

This is the identical CA required for HTTPS inspection in bump mode — most deployments already distribute it as part of their SSL-inspection rollout. See SSL inspection for the mode reference and the legal acknowledgement gate.

Where to find the values

Value Where
Portal host ENFORCEGATE_CAPTIVE_HOSTNAME in the appliance's bundles/standalone/.env, or eghost links, or the installer's Ready screen
Proxy address The appliance LAN IP, port 3128
CA download http://<portal-host>/ca (HTML install page) or http://<portal-host>/ca.crt (raw PEM)

Prefer a real DNS name for the portal host

Set ENFORCEGATE_CAPTIVE_HOSTNAME to a real DNS name or the appliance's LAN IP rather than a .local mDNS suffix. Many clients (macOS, Linux nss-mdns) resolve .local names only via multicast and may not honour them from unicast DNS — which the PAC file and GPO exception lists both rely on.

Verifying the setup

Once the bypass is in place and the CA is trusted:

  1. Visit any blocked destination from a client (for example, http://example.com if you have a matching deny rule).
  2. The browser should redirect to https://<portal-host>/blocked?… and render the portal's block page without certificate warnings.
  3. Clicking Proceed anyway on a warn or aup rule should be attributed to the correct client — show log captive on the engine reports the visitor's IP, not the proxy's.

If the browser still shows SSL_ERROR_RX_RECORD_TOO_LONG after applying the bypass, verify the PAC file / GPO exception is actually taking effect on the client:

  • Chrome / Edge — chrome://net-internals/#proxy shows the resolved PAC verdict per URL.
  • Firefox — about:networking#proxy reports the effective proxy for a given host.