pfSense Captive Portal Setup - Complete Configuration Guide

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 , 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 , 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:

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 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 - 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 is configured correctly for the portal subnet
• Inspect the state table in Diagnostics > States for client entries