Captive portal¶

The captive portal is the in-product landing page rendered to a visitor whenever the engine emits a verdict redirect — block, warn, or aup. It also hosts a self-service install page for the SSL-bump CA so unmanaged devices can join the proxy without an MDM / GPO trust-store push.

The portal is not a guest-Wi-Fi email-capture form. Visitors land here because the security gateway intercepted their request. There is deliberately no marketing-consent checkbox — the only data collected is what the gateway needs to authorise, log and audit the request.

The portal is a Python application. It runs as a separate enforcegate-captive-portal service in the bundled docker-compose.yml, fronted by a the TLS terminator tls-terminator service that publishes :80 (redirect to HTTPS) and :443 (TLS) on the host.

Deployment shape¶

   browser ───► tls-terminator  ───► captive-portal  ───► engine (Control API)
                  :80 redirect → :443        :8000 (compose          :11225 (compose
                  :443 TLS (bump-CA            network only)           network only)
                  signed leaf cert)

• The browser never speaks directly to the engine; the portal proxies /api/captive/ack server-side to the engine's :11225 Control API listener.
• The TLS terminator is bare with one upstream — captive-portal:8000. It does not know any of the portal's URL space.
• The leaf TLS certificate the terminator serves is the engine-issued portal cert, signed by the SSL-bump CA. Operators distribute one CA (the bump CA) to client trust stores and every TLS hop in the deployment chains to it.

Routes¶

The portal exposes a small, fixed set of routes. The path is the verdict — a given verdict always lands on one URL, with no path-level dispatch from query parameters.

Verdict pages¶

Rendered in English, French, German and Italian (the four Swiss locales). The visitor's preferred language is selected from Accept-Language with a manual override available in the topbar.

The /blocked page rendered against a deny verdict, showing the destination, the rule's description, and the matched rule name:

Every field visible on the page is engine-provided — the destination is the URL the visitor requested, the reason text is the description: from the matched .policy rule (Warez — pirated software and media in this shot), and the rule identifier (ut1-warez) is the rule name straight out of show policy list so operators can grep the audit log back to the specific policy. /warned and /aup share the same layout and add a CTA button below the detail card.

Internal ack endpoint¶

Self-service CA install¶

When SSL-bump inspection is active and the bump CA has been published into the shared volume, two additional routes appear:

Both routes 404 when bump mode is not active or the CA path is unreadable, so the feature stays invisible in non-intercepting deployments. Plain-HTTP exposure of /ca and /ca.crt is whitelisted in the bundle's TLS-terminator config (so unmanaged devices can fetch the CA before they have it installed); every other path on :80 redirects to HTTPS.

The page is the unmanaged-device fallback for the CA-distribution problem: managed devices receive the CA via GPO / Intune / Jamf, but BYOD laptops, guest devices and personal phones need a self-service path.

Health and version¶

Redirect security¶

Every URL the engine sends the browser to a verdict page with carries exactly three URL parameters:

• p — an encrypted payload.
• v — protocol version (currently "1").
• ts — Unix epoch seconds, for replay protection.

The encryption key is shared between the engine and the portal via [captive_portal].secret. Operator-visible properties:

• Visitors cannot read verdict context from the URL bar. The destination URL, matched rule name, reason, category and any other verdict-bound field travel inside the encrypted payload. Nothing decodable to the visitor leaks into history or the Referer header.
• The portal verifies and decrypts. A tampered p fails the integrity check and the portal returns 403.
• Replay window is bounded. Requests where ts is more than ENGINE_SIGNATURE_MAX_AGE_SECONDS (default 300 s) old are rejected.
• Connectors never see the secret. They are pure relays — they receive the pre-built URL from the engine and hand it to the browser as an HTTP 302.

The wire-level cryptographic construction is documented in the public protocol spec for portal integrators (not on this site).

Proceed-anyway round-trip¶

For verdicts with a CTA (warn and aup with ack_token present):

Browser            tls-terminator (:443)        Captive portal       Engine (:11225)
   │                    │                    │                     │
   │ GET /warned?p=…&v=1&ts=…                │                     │
   ├───────────────────►│ reverse-proxy ────►│ decrypt p     │
   │                    │                    │ → render warned    │
   │                    │                    │   page             │
   │◄───────────────────│◄───────────────────│                    │
   │                                                                │
   │ ▼ user clicks "Proceed anyway"                                 │
   │                                                                │
   │ GET /api/captive/ack?p=…&v=1&ts=…                              │
   ├───────────────────►│ reverse-proxy ────►│ server-side GET to │
   │                    │                    │ engine             │
   │                    │                    ├────────────────────►│ verify ack
   │                    │                    │                     │ record session
   │                    │                    │                     │ return 302 →
   │                    │                    │                     │   original URL
   │                    │                    │◄────────────────────│
   │                    │◄───────────────────│                     │
   │ 302 → origin URL   │                    │                     │
   │◄───────────────────│                    │                     │

Why this shape:

• Single upstream from the terminator's perspective. Path-aware reverse-proxying lives in the portal, not in the terminator. Operators who need to swap the TLS terminator out only need to point at captive-portal:8000.
• The browser never sees :11225. The shipped docker-compose.yml does not publish the engine's Control API to the host. The portal is the only path in.

Operator identity¶

Two distinct entities show up in the UI:

• Software publisher — the author of the captive portal code, templates and design. Always Exosys Sàrl. Rendered as the footer copyright (Copyright © <year> Exosys Sàrl. All rights reserved.). Not environment-overridable.
• Operator — the entity running this specific instance (the customer fronting EnforceGate with their hostname and TLS certificate). Surfaces in the privacy notice § 5 ("contacting …, the operator of this gateway") and as the display name on the CA install page.

The operator name is resolved at render time from three sources, in order:

1. ENFORCEGATE_ORG_NAME — supplied by the installer (the same value baked into the bump CA's Subject DN O=). Rendered as plain text on both surfaces, because the installer doesn't carry a companion URL.
2. BRAND_COMPANY — paired with BRAND_COMPANY_URL, so it renders as a linked anchor.
3. Literal fallback — "your network administrator" in the privacy notice; "EnforceGate" on the CA install page.

In short: customers customise the operator identity; the software copyright stays attributed to Exosys.

Operator AUP page¶

From 2026.36.0 onwards, the captive portal can render an operator-supplied Acceptable Use Policy on the /aup verdict page. When a request matches a rule with action: aup, the visitor lands on a page that shows your operator-authored policy text (Markdown), followed by an "I acknowledge and continue" CTA that records the acceptance against the configured PRIVACY_POLICY_VERSION. The default /aup content (a generic placeholder) is replaced by your text — every other route is unaffected.

Manage the operator AUP exclusively through the eghost portal aup verb family on the host:

eghost portal aup edit          # open the Markdown in $EDITOR (seeds a template on first edit)
eghost portal aup enable        # turn the rendering on without editing
eghost portal aup disable       # fall back to the built-in default /aup content
eghost portal aup show          # print the current Markdown to stdout
eghost portal aup status        # report enabled state, mtime, and portal health

The feature is off by default. eghost portal aup edit enables it on save and recreates the captive-portal container so the new policy is served on the next /aup verdict; the verb verifies the portal stays up after the recreate and auto-reverts the change if the container crashed.

Theming¶

The portal has two independent axes that combine freely:

A single palette ships in light and dark flavours; the visitor can flip between light and dark regardless of which palette the operator configured.

Unknown palette values fall back silently to indigo.

Configuration¶

The portal is configured exclusively via environment variables forwarded from the bundle's .env. The operator-relevant subset:

Storage¶

The portal uses SQLAlchemy and refuses to boot without DATABASE_URL set. The captive portal upstream targets PostgreSQL as its production backing store (recommended for any deployment that needs to persist AUP acceptance records or future authentication state). The shipped IR bundle's docker-compose.yml defaults to an ephemeral SQLite file on container tmpfs — which wipes on every restart — so the standalone deployment boots out of the box with no external database to manage.

To switch to persistent storage, set ENFORCEGATE_CAPTIVE_DATABASE_URL in .env. SQLite on a named volume:

ENFORCEGATE_CAPTIVE_DATABASE_URL=sqlite:////app/data/captive-portal.db

Or PostgreSQL (recommended for production):

ENFORCEGATE_CAPTIVE_DATABASE_URL=postgresql+pg8000://portal:portal@captive-portal-db:5432/captive_portal

…and add a captive-portal-db service to the compose stack. See persistence for the broader volume model.