# pfSense Captive Portal Setup - Complete Configuration Guide > Step-by-step pfSense Captive Portal configuration - zones, RADIUS authentication, vouchers, MAC passthrough, HTTPS portal, and troubleshooting Source: https://opennix.org/en/docs/pfsense/captive-portal/pfsense-captive-portal-setup/ Captive Portal enforces user authentication before granting network access. This guide covers the full configuration process: creating zones, selecting authentication methods, customizing the portal page, configuring bandwidth restrictions, and resolving common issues. Before starting, ensure the interface designated for the portal is already configured with an assigned IP address. When using [VLANs](/docs/pfsense/vlans/pfsense-vlan-setup/), the VLAN interface must be created and assigned beforehand. ## Captive Portal Zones A zone defines the set of interfaces on which the authorization portal operates and groups all related settings: authentication method, portal page, timeouts, traffic restrictions, and allowed address lists. Each zone functions independently. ### Creating a Zone Navigate to **Services > Captive Portal** and click **Add**. Enter a zone name (Latin letters, digits, and underscores only) and an optional description, then click **Save & Continue**. The zone configuration page opens after saving. ### Binding Interfaces In the **Interface** field, select one or more interfaces for the portal. A single interface cannot belong to multiple zones simultaneously. When using [bridged interfaces](/docs/pfsense/bridging/pfsense-bridge-setup/), specify the bridge interface itself as the zone interface rather than its member interfaces. ## Authentication Methods pfSense provides several methods for authenticating portal users. ### Backend Authentication Selecting **Use authentication backend** verifies credentials against a configured authentication source: the pfSense local user database, an LDAP server, or a RADIUS server. Users enter a username and password on the portal page, and the system validates them through the selected backend. To configure a RADIUS server, navigate to **System > User Manager > Authentication Servers** and create a RADIUS entry specifying the server address, port, shared secret, and protocol (PAP, CHAP, or MS-CHAPv2). Then select the created server in the Captive Portal zone settings. ### Vouchers The voucher system generates single-use access codes with configurable validity periods. This is well-suited for hotel guest networks, conferences, and public access points where temporary access is needed without creating user accounts. To enable vouchers, navigate to the **Vouchers** tab in the zone settings. The system generates RSA keys to sign vouchers, preventing the creation of counterfeit codes. Configure the following parameters: - **Roll** - a batch of vouchers with a unique identifier - **Count** - number of vouchers in the batch - **Minutes per ticket** - validity period for each voucher Generated vouchers can be exported to CSV for printing or distribution. ### No Authentication (Click-Through) Selecting **None** requires users only to open the portal page and click a confirmation button. This mode is appropriate when only acceptance of terms of service is required without credential entry. ### RADIUS MAC Authentication This mode sends the client's MAC address as the username and the configured secret as the password to the RADIUS server. It enables automatic device authorization based on MAC addresses without user interaction. ## Session Management ### Timeouts - **Idle timeout** - inactivity period in minutes after which the client is disconnected. Inactivity is defined as the absence of network traffic from the client - **Hard timeout** - maximum session duration in minutes, after which the client is disconnected regardless of activity ### Traffic Quotas The **Traffic Quota** field sets the maximum data transfer volume (combined upload and download) in megabytes, after which the client is disconnected from the network. ### Concurrent Connections The **Concurrent user logins** parameter controls behavior when a user authenticates again: | Setting | Behavior | |---|---| | Multiple | Unlimited simultaneous sessions (default) | | Last Login | Allows only the most recent session, previous sessions are terminated | | First Login | Denies re-authentication until the current session ends | | Disabled | Multiple connections are prohibited | The maximum number of concurrent connections from a single IP address defaults to four to prevent resource exhaustion. ## Bandwidth Limiting The **Default download speed** and **Default upload speed** fields set per-client speed limits in kilobits per second. A value of 0 or an empty field means no restriction. When using a RADIUS server, individual limits can be set through reply attributes: - `pfSense-Bandwidth-Max-Down` - maximum download speed - `pfSense-Bandwidth-Max-Up` - maximum upload speed - `pfSense-Max-Total-Octets` - total traffic volume quota RADIUS attributes take precedence over zone settings, allowing different service tiers to be assigned at the authentication server level. ## MAC Passthrough MAC passthrough allows devices to pass through the portal without re-authentication based on a previously registered MAC address. ### Automatic Addition Enabling **Pass-through MAC Auto Entry** automatically adds the client's MAC address to the allowed list after successful authentication. The **Automatic addition with username** option saves the username alongside the MAC address for auditing purposes. ### Manual Management The **MACs** tab allows manual addition of MAC addresses with a specified action: **Pass** (bypass authorization) or **Block** (deny completely). Manual entries are useful for printers, IP phones, and other devices incapable of completing web-based authentication. ### MAC Filtering Limitations If a router (not a switch) sits between the client and the pfSense interface, the client's MAC address is replaced by the intermediate router's MAC address. In this scenario, MAC filtering should be disabled since all clients behind the router will share the same MAC address. ## Pass-Through Credits The credit mechanism allows a specified number of connections without authentication: - **Credits allowed per MAC** - number of free connections - **Waiting period** - credit restoration period in hours - **Reset on attempted access** - prevents credit restoration during repeated attempts ## HTTPS Portal By default, the portal operates over HTTP. To enable HTTPS: 1. Navigate to **System > Cert Manager** and create or import an SSL certificate 2. In the zone settings, enable the **Login - HTTPS** checkbox 3. Enter the **HTTPS server name** - the fully qualified domain name (FQDN) matching the certificate's Common Name 4. Select the SSL certificate in the **SSL Certificate** field The **Disable HTTPS Forwards** option prevents redirection of port 443 requests. Enabling this is recommended because redirecting HTTPS requests triggers certificate mismatch warnings in the client browser. ## Portal Page Customization ### Basic Customization Standard appearance options are available directly in the zone settings: - **Custom Logo** - organization logo displayed on the authentication page - **Custom Background** - background image for the portal page - **Terms and Conditions** - usage terms text that users must accept ### HTML Templates For full control over portal appearance, custom HTML pages can be uploaded: - **Portal page** - the main authentication page - **Error page** - the authentication error page - **Logout page** - the session termination confirmation page HTML templates support PHP code for dynamic content. Image files, CSS, and JavaScript are uploaded through the **File Manager** in the zone settings. ### Allowed IP Addresses and Hostnames The **Allowed IP Addresses** and **Allowed Hostnames** tabs specify addresses and domain names accessible to clients before authentication. This is necessary for access to external authentication resources, DNS servers, update servers, and other critical services. ## RADIUS Accounting Integration When using a RADIUS server, pfSense supports sending accounting messages: - **Accounting Start** - upon successful client authentication - **Accounting Stop** - upon session termination (timeout, disconnect, or quota exceeded) - **Interim Updates** - periodic session status updates Configure the accounting server in the zone's RADIUS parameters. The **NAS Identifier** field sets the device identifier sent in RADIUS requests, simplifying source identification in authentication server logs. The **Reauthentication** option sends an access verification request every minute. If the RADIUS server rejects the request, the client is disconnected. This is useful in scenarios where the RADIUS server administrator needs the ability to immediately revoke user access. ## Troubleshooting ### Portal Does Not Appear - Verify the zone is enabled (the **Enable** checkbox is set) - Confirm the zone interface matches the interface to which the client is connected - Ensure [firewall rules](/docs/pfsense/firewall/pfsense-firewall-rules/) on the interface allow DNS traffic (port 53) - Check that the client receives an IP address from the correct subnet - When using a bridge, verify the zone is bound to the bridge interface, not its member interfaces ### Redirect Issues - If the client is not redirected automatically, try opening any HTTP site (not HTTPS) - HTTPS sites cannot be intercepted and redirected due to TLS - this is a protocol limitation, not a pfSense issue - Verify the DNS server used by the client is reachable before authentication - Ensure the client uses the pfSense DNS server rather than a third-party resolver ### HTTPS Warnings Certificate warnings when redirecting HTTPS requests are expected behavior. The portal certificate cannot match the domain the client originally requested. Enable **Disable HTTPS Forwards** to prevent HTTPS traffic redirection. ### RADIUS Not Responding - Verify RADIUS server reachability using `ping` or `radtest` - Confirm the shared secret matches on both pfSense and the RADIUS server - Check [firewall rules](/docs/pfsense/firewall/pfsense-firewall-rules/) - ports 1812 (authentication) and 1813 (accounting) must be open - Review RADIUS server logs for rejected requests - Ensure the pfSense IP address is added to the allowed clients list on the RADIUS server ### Client Authenticated but No Internet Access - Check firewall rules on the zone interface - a pass rule must exist for authenticated clients - Verify [NAT](/docs/pfsense/nat/pfsense-port-forwarding/) is configured correctly for the portal subnet - Inspect the state table in **Diagnostics > States** for client entries