How to set up a captive portal on pfSense

pfSense is an extremely powerful open-source-based router/firewall that can quite easily enhance your network’s security.

One of the features that comes bundled with pfSense is the captive portal. Captive portals can be a great way to secure a home guest network. But they’re mainly used to manage access to corporate guest networks, as well as hotel and restaurant networks.

In this guide we’re going to explain how to set up a captive portal in pfSense.

Note: Netgate, the company behind pfSense’s development, maintains two forks of the project:

pfSense CE
pfSense Plus

pfSense CE, which stands for Community Edition, is the fully open-source version of pfSense. pfSense Plus is open-source-based but with extra features added using proprietary code. While both are free for individual users, we’ll be using pfSense CE in this guide – which also assumes you have a working pfSense configuration with a WAN and a LAN interface setup.

What is a captive portal?

In a nutshell, a captive portal intercepts users’ connections to a given network and prompts them to authenticate themselves for access. The authentication mechanism on captive portals usually takes the form of a login page, where users can enter credentials (username and password or vouchers). Once authenticated, users are able to access the internet normally.

The captive portal login page is also often used to display terms and conditions that users must accept for network access.

A captive portal can also perform accounting, meaning it is aware of all the connections it has allowed or blocked and can also be used for connection management. So it can do things like, disconnect users after a set amount of time or after a bandwidth threshold has been reached, etc.

Captive portals provide an extra layer of security while providing visibility and control over network usage.

Let’s start configuring our own captive portal in pfSense.

Creating a captive portal user

The first thing we’re going to do is create a user with credentials to authenticate within the captive portal.

From the top menus, select System > User Manager.
The User Manager main page is displayed. Click Add.
This brings up the User configuration page.
Enter a username and password in the Username and Password fields. I’ll be using CPUser for this example.
Click Save.
You’re taken back to the User Manager main page. We need to edit our user to provide it with the permissions needed to access the Captive Portal. Click the pencil icon next to the user we just created.
Under Effective Privileges, click Add.
The User Privileges page is displayed. Select User – Services: Captive Portal login from the Assigned privileges list.
Click Save.
You’re taken back to the User configuration page. Click Save again.
You’re taken back to the User Manager main page, where your new user is displayed in the list.

How to set up the Captive Portal

We’re now going to start configuring the Captive Portal.

From the top menus, select Services > Captive Portal. The Captive Portal main page is displayed.
Click Add. The Captive Portal / Add Zone page is displayed.
Captive Portals in pfSense work by creating Zones. Zones define the network interfaces the Captive Portal will listen on. Each Zone can have its own settings and rules. Enter a name and a description for your Zone.
Click Save & Continue. The Captive Portal Configuration page is displayed.
Tick the Enable Captive Portal box. The full Captive Portal Configuration page is displayed. We’ll go over the page’s sections one by one.
The top section, called Captive Portal Configuration, contains many options for access, authentication, and accounting. And we will provide an overview of each one. But first, select the interface for this Zone. If you only have a WAN and LAN interface, select LAN. If you have more LAN type interfaces you want to add to this zone, go ahead and select them. Now let’s look at the settings on this page.

Maximum concurrent connections: Define the maximum number of connections allowed on the Captive Portal.
Idle timeout (Minutes): Define an idle time threshold after which clients are automatically disconnected.
Hard timeout (Minutes): Define a time threshold after which clients are automatically disconnected.
Traffic quotas (megabytes): Define the number of megabytes users can use up while connected. Once the threshold is reached, clients are automatically disconnected.
Pass-through credits per MAC address: By setting a number in this field, each MAC address that attempts to connect to the network will be allowed to bypass the Captive Portal and access the internet without authentication the number of times corresponding to the number you set. This permission can be reset (see below).
Waiting period to restore pass-through credits (Hours): The amount of time before the MAC address pass-through credits are reset.
Reset waiting period: If ticked, the waiting period is reset when a MAC address attempts to connect after its pass-through credits have been used up.
Logout pop-up window: Displays a logout pop-up window to connected users when enabled.
Pre-authentication redirect URL: Set a default redirect URL that will be used when the Captive Portal doesn’t know where to redirect authenticated users.
After authentication Redirection URL: Set a URL to which authenticated users will be automatically redirected. We’re going to set this to ‘https://www.comparitech.com’. So after a successful authentication, we’ll be redirected to the Comparitech website.
Blocked MAC address redirect URL: Any blocked MAC addresses will be redirected to this URL.
Preserve users database: Allow users to stay connected across Captive Portal reboots.
Concurrent user logins: Select how to allow concurrent user logins.
MAC filtering: Click to disable having the Captive Portal make sure a client’s MAC address remains the same throughout the duration of their connection.
Pass-through MAC Auto Entry: Enable a given MAC address to bypass authentication on the Captive Portal after having successfully authenticated once.
Per-user bandwidth restriction: Enable per-user bandwidth restrictions.
Use custom captive portal page: Tick to use your own custom captive portal page rather than the default page.

We won’t be touching these settings in this tutorial but feel free to enable the options you want.

The next section on this page is the Captive Portal Login Page section and it allows you to upload custom html, css, images, etc., for your custom Captive Portal login page.

And finally, we get to the Authentication section, which we need to configure.

Select Local Database from the Authentication Server list. This makes the Captive Portal use pfSense’s local database for user authentication. That’s where the user we created earlier resides. Below that, we also have the HTTPS Options section, which enables the Captive Portal to serve its login page over HTTPS. This requires setting up a valid HTTPS certificate for use with the Captive Portal and is beyond the scope of this tutorial.
Click Save.
You’re taken back to the Captive Portal main settings page and we can see our Zone is displayed in the list.

Testing username and password authentication

Our Captive Portal’s basic configuration is now complete. We’ll configure our Captive Portal to allow authentication using vouchers. But before we do that, let’s test our Captive Portal to make sure it works with username and password-based authentication, using our CPUser we created earlier.

When trying to access a webpage over a network configured to use the Captive Portal, we should end up on the default pfSense Captive Portal login page, which looks like this:

If you attempt to access a HTTP page (port 80), the Captive Portal login page should display immediately. However, these days, websites that use the HTTP protocol rather than HTTPS are few and far between. Had we configured HTTPS in the above step, this would also happen with HTTPS connections. So what will happen is that your browser will display a notice that you need to authenticate yourself to use the current network. In Firefox, it looks like this:

Clicking the Open network login page will take you to pfSense’s Captive Portal login page. Now let’s try and login with our credentials.

I’m granted access to the internet and redirected to comparitech.com, as specified in the settings.

Captive portal tabs overview

Now we’re going to configure authentication vouchers for the Captive Portal. But before we do that, let’s just provide an overview of the other tabs within the Captive Portal settings.

MACs

You can add MAC addresses and configure and assign them bandwidth limits and other settings from the Captive Portal’s MACs tab.

Clicking Add brings up the MAC Address Rules page for configuration.

Allowed IP Addresses

You can add IP addresses that will bypass Captive Portal authentication and assign them bandwidth limits and other settings from the Captive Portal’s Allowed IP Addresses tab.

Clicking Add displays the Edit Captive Portal IP Rule page for configuration.

Allowed Hostnames

You can add hostnames that will bypass Captive Portal authentication and assign them bandwidth limits and other settings from the Captive Portal’s Allowed Hostnames tab.

Clicking Add brings up the Captive Portal Hostname Settings page for configuration.

High Availability

The High Availability tab allows you to define a backup Captive Portal for redundancy.

File Manager

The File Manager tab allows you to upload and manage custom HTML, CSS, images, etc., for your custom Captive Portal login page. Uploaded elements are listed on the main page.

Clicking Add displays the File Manager Upload page.

Vouchers

Now we get to the Vouchers tab, where we will configure our Captive Portal to also accept vouchers for authentication. And we will generate our first roll of vouchers.

From the Vouchers tab main settings page, click the Enable creation, generation and activation of rolls with vouchers box. This displays the full list of settings on the page.
Click the Generate new keys button, to generate a public/private key pair used for the encryption and decryption of vouchers.
Leave the rest of the settings untouched and click Save.
This reloads the Vouchers settings page and displays an Add button under the Voucher Rolls section. Click Add. The Voucher Rolls settings page is displayed.
In the Roll # field, enter a number for this roll. As this is our first rool, we’ll use 1.
In the Minutes per ticket field, enter the number of minutes of internet access you want each voucher to allow. We’ll set this to 30 minutes in our example.
In the Count field, enter the number of vouchers you want to generate in this run. We’ll set this to 10 in our example.
Enter a description in the Comment field if you like.
Click Save. This takes us back to the Vouchers main settings page.
The roll we just created is now displayed in the Voucher Rolls section. To actually see our vouchers, we need to export them to CSV, using the Export to CSV icon to the right of our voucher roll.
The resulting CSV looks as follows. We can use the vouchers displayed on lines 8 to 17 to log into our Captive Portal. Let’s test this now.

Testing voucher authentication

Like before when we attempt to access a website, we may need to click the Open network login page button (or the equivalent in your browser) for the Captive Portal login page to display. Now that we’ve enabled voucher support in our Captive Portal, the login page includes a voucher field. Enter one of the generated vouchers and click Login.
We’re grated access and redirected to the Comparitech website.

Adding a widget to the dashboard

One last thing we can do is add a Captive Portal widget to our pfSense dashboard.

From the dashboard, click the + sign at the top right of the UI. This displays the list of available widgets.
Select Captive Portal Status from the list.
The Captive Portal Status widget is added to the bottom of our dashboard. It provides information on connected users at a glance.
Scrolling the widget to the right displays a trash can icon that you can use to forcibly disconnect a user.

Wrap Up

We configured a Captive Portal on pfsense that supports both username and password authentication and voucher authentication. Captive Portals provide some security enhancements to your guest networks and enable much more granular control over what your users can and can’t do on your networks. And while it can be useful to secure a home guest network, those who will benefit the most from a Captive Portal are businesses that provide internet access to their customers.

See also:

Setting up a captive portal on pfSense