Zone Configuration Options

This section describes each of the Captive Portal configuration options. These options are available once a Captive Portal zone has been created under Services > Captive Portal. These options all work independently of one another for each zone. For example, the allowed IP addresses specified in a zone only affect that one zone.

Interface:

Determines the interfaces that will be active for this Captive Portal zone. This cannot be a WAN interface. It can be a bridge interface so long as it is the actual bridge (e.g. bridge0) and the bridge interface has an IP address assigned.

Maximum concurrent connections:
 

Specifies the maximum number of concurrent connections to the portal web server per IP address. The default value is 4, which is sufficient for most environments. This limit exists to prevent a single host from exhausting all resources on the firewall, whether inadvertent or intentional. One example where this would otherwise be a problem is a host infected with a worm. The thousands of connections issued will cause the captive portal page to be generated repeatedly if the host is not authenticated already, which would otherwise generate so much load it would leave the firewall unresponsive.

Idle timeout:

A timeout, specified in minutes, after which idle users will be disconnected. Users may log back in immediately.

Hard timeout:

A timeout, specified in minutes, which will forcefully log off users after a specified period. Either a hard timeout, idle timeout or both should be entered to ensure sessions are removed if users do not log off, as most users likely will not. Users will be able to log back in immediately after the hard timeout if their credentials are still valid (for local accounts, not expired, and for RADIUS authentication, user can still successfully authenticate to RADIUS).

Note

If a timeout value is set, the timeout must be less than the DHCP lease time or captive portal sessions can remain active for IP addresses that have switched to different devices. Setting the timeout lower will ensure that the portal sessions end before the lease would be reallocated to a new client.

Pass-Through Credits:
 

These credits give devices a grace period before they must authenticate via the portal. For example, a device could connect 3 times within a day without seeing the portal page, but any more than that and they need to login. By setting the hard timeout to a value such as 1 hour, the client would effectively be limited to three hours of access before needing to authenticate. By default this is disabled, and all clients are presented with the portal login page and must login.

Note

For this to be effective, set a hard timeout and/or idle timeout.

Pass-through credits allowed per MAC address:
 

The number of times a specific MAC address may connect through the portal. Once used up, the client can only log in with valid credentials until the waiting period specified below has expired.

Waiting period to restore pass-through credits:
 

The number of hours after which clients will have their available pass-through credits restored to the original count after using the first one. This must be above 0 hours if pass-through credits are enabled.

Reset waiting period on attempted access:
 

If enabled, the waiting period is reset to the original duration if access is attempted when all pass-through credits have already been exhausted. This will prevent people who repeatedly attempt to access the portal from gaining open access too quickly.

Logout popup window:
 

When checked, a logout pop up window is shown to the user which allows clients to explicitly disconnect themselves before the idle or hard timeout occurs. Unfortunately, since most browsers have pop up blockers enabled, this window may not work for most clients unless the portal can be excluded from pop-up blocking in their browsers.

Pre-authentication redirect URL:
 

As the name implies, this option redirects users to the specified URL before they authenticate. Commonly, this is used to display a custom landing page describing the device location hosted on a server locally or elsewhere That landing page must contain a link which in turn redirects the users back to the portal page, e.g. http://x.x.x.x:8002/index.php?zone=somezone&redirurl=http%3A%2F%2Fsomesite.example.com.

See also

See Allowed Hostnames to allow hostnames through the portal without authentication, and Allowed IP Address for IP addresses.

The custom captive portal page must have extra code at the top in order to properly handle this redirect. In the example code below, the pre-authentication redirect target page must also put its own URL in the redirurl parameter of its link back to the portal in order for the login page to appear.

<?php
require_once("globals.inc");
$request_uri = urldecode(str_replace("/index.php?zone={$_REQUEST['zone']}&redirurl=", "", $_SERVER["REQUEST_URI"]));
$portal_redirurl = urldecode("$PORTAL_REDIRURL$");
if(!stristr($portal_redirurl, $request_uri)) {
      Header("Location: $PORTAL_REDIRURL$");
      exit;
}
?>
After authentication Redirection URL:
 

After authenticating or clicking through the portal, users will be redirected to this URL rather than the one they originally tried to access. If this field is left blank, the user will be redirected to the URL the user initially attempted to access.

Concurrent user logins:
 

When checked, only one login per user account is allowed. The most recent login is permitted and any previous logins under that username will be disconnected. This is not a total limit for the entire portal, but a per-account limit.

MAC filtering:

When set, MAC address filtering is disabled. This is necessary in cases where the MAC address cannot reliably be determined, such as when multiple subnets exist behind a separate router using the portal. In that type of situation, all users behind a router will show up to the portal with the router’s MAC address. If this option is set, no attempt will be made to ensure that the MAC address of clients stay the same while they’re logged into the portal.

Note

If this option is checked is enabled, RADIUS MAC authentication cannot be used.

Pass-through MAC Auto Entry:
 

In some use cases, users may only need to authenticate once per device, and then never see the portal login again unless they change devices. Setting up pass-through MAC entries can automatically achieve this goal.

Pass-through MAC automatic additions:
 

If this option is set, a MAC passthrough entry is automatically added after the user has successfully authenticated. Users of that MAC address will never have to authenticate again unless the entry is manually removed. To remove the passthrough MAC entry, log in and remove it manually from the Pass-through MAC tab.

Note

If this option is enabled, RADIUS MAC authentication cannot be used and the logout window will not be shown.

Pass-through MAC automatic addition with username:
 

If this option is set, the username used during authentication will be saved along with the pass- through MAC entry. To remove the passthrough MAC entry, log in and remove it manually from the Pass-through MAC tab.

Per-user bandwidth restrictions:
 

Captive Portal can also optionally rate-limit users to keep them from using too much bandwidth. The Default download and Default upload fields define the default values for user bandwidth, specified in Kilobits per second. These values can be overridden by RADIUS (Passing back configuration from RADIUS Servers) for different limits for specific users. If the fields are blank or set to 0, then users may have unlimited bandwidth.

Authentication

This section allows authentication to be configured. If authentication is required, either the local user manager or RADIUS authentication may be used.

No Authentication:
 

When selected, users need only click through the portal screen for access. The form must still be submitted, but it does not need to have any user entry fields, only a submit button.

Local User Manager / Vouchers:
 

This option allows users to authenticate with a username and password, but not with a RADIUS server. Captive Portal users in this mode are managed in the pfSense GUI. Local users are added in the User Manager User Management and Authentication.

Additionally, if Allow only users/groups with ‘Captive portal login’ privilege set is checked, then to access the portal, users must have the Captive Portal privilege on their account, or be a member of a group containing this privilege.

Vouchers are pre-generated access codes that can be provided to users to grant short-term access. Vouchers may be used in addition to, or instead of, local user authentication. For more information on using vouchers, see Vouchers later in this chapter.

RADIUS Authentication:
 

When selected, the RADIUS server options are displayed and Captive Portal users in this zone will be validated against the configured RADIUS server(s).

RADIUS Authentication Options

RADIUS is a means of authenticating users against a central server that contains account information. There are many implementations of RADIUS, such as FreeRADIUS, Radiator, and NPS on Windows servers. For those with a Microsoft Active Directory network infrastructure, RADIUS can be used to authenticate captive portal users from Active Directory using Microsoft NPS. This is described in RADIUS Authentication with Windows Server. RADIUS accounting can be enabled to send usage information for each user to the RADIUS server. Refer to documentation for the RADIUS server for more information.

To use RADIUS, select RADIUS Authentication under Authentication and then fill in the data about the RADIUS server.

RADIUS Protocol:
 

Control which protocol the RADIUS server can use for authentication. The available choices are:

PAP (Password Authentication Protocol):
 The least secure but most compatible option, PAP sends passwords in plain text.
CHAP_MD5 (Challenge-Handshake Authentication Protocol):
 More secure than PAP, CHAP uses MD5 and encrypts the password during transmission. While more secure than PAP on the wire, the server side must know the cleartext password in order to calculate the challenge.
MSCHAPv1 (Microsoft CHAP, Version 1):
 A Microsoft-designed variation of CHAP primarily used in older versions of Windows (NT 3.x through Windows 95). There are programs available that can easily capture the password hashes from the exchange.
MSCHAPv2 (Microsoft CHAP, Version 2):
 Adds more security features on top of CHAP/MS-CHAP v1.

The relative (in)security of these protocols may be of little consequence depending on the layout of the network and the location of the RADIUS server, but should still be considered.

Passing back configuration from RADIUS Servers

Some default Captive Portal settings can be overridden by reply attributes from RADIUS servers. The exact attributes can vary by vendor, and may not be supported by all RADIUS servers.

User bandwidth restrictions:
 Defines the bandwidth for the user, drawn from common options such as WISPr-Bandwidth-Max-Up/WISPr-Bandwidth-Max- Down, or ChilliSpot-Bandwidth-Max-Up/ChilliSpot-Bandwidth-Max-Down.
Session Timeout:
 Drawn from the RADIUS attribute Session-Timeout, it will disconnect the user after the time specified by the RADIUS server.
Idle Timeout:Drawn from the RADIUS attribute Idle-Timeout, it will disconnect the user after the time specified by the RADIUS server.
Accounting Interval Interim:
 Taken from Acct-Interim-Interval, it directs the portal to send interim accounting updates at the specified interval.
URL Redirection:
 Allows the after-authentication redirect URL to be defined by the RADIUS server through WISPr-Redirection-URL.

Primary Authentication Source

The Primary/Secondary RADIUS Servers are used for the main username and password fields on the login form, auth_user and auth_pass, such as:

<tr>
    <td align="right">Username:</td>
    <td><input name="auth_user" type="text" style="border: 1px dashed;"></td>
 </tr>
<tr>
    <td align="right">Password:</td>
    <td><input name="auth_pass" type="password" style="border: 1px dashed;"></td>
</tr>

If the primary RADIUS server is down, the secondary RADIUS server will be tried.

IP Address:The IP address or hostname of the RADIUS server
Port:The authentication port for the RADIUS server, typically 1812.
Shared Secret:The shared secret for this firewall on the RADIUS server.

Secondary Authentication Source

The secondary authentication source defines a completely separate RADIUS authentication setup from the primary. For example, the primary RADIUS source could be traditional usernames and passwords, while the secondary could be pre- paid card numbers or PINs. As with the primary authentication source, a primary server and secondary server may be defined.

The secondary authentication source uses the form fields auth_user2 and auth_pass2 in the captive portal HTML, such as:

<tr>
    <td align="right">Username:</td>
    <td><input name="auth_user2" type="text" style="border: 1px dashed;"></td>
</tr>
<tr>
    <td align="right">Password:</td>
    <td><input name="auth_pass2" type="password" style="border: 1px dashed;"></td>
</tr>

Accounting

RADIUS accounting will send session information back to the RADIUS server indicating when a user’s session starts, ends, and how much data they have transmitted.

Warning

Not all RADIUS servers support or are configured to accept accounting data, so make sure that the RADIUS server has been setup up properly before enabling this feature.

Accounting Port:
 

Configures the port upon which the RADIUS server accepts accounting packets, typically 1813.

Accounting Updates:
 

This configures what specific type of accounting is supported by the server.

No updates:Synonymous with disabling accounting, it will not send accounting updates to the server.
Stop/start:Will send START and STOP records for a user session only.
Stop/start (FreeRADIUS):
 Will send START and STOP records for a user session only, in a way that is compatible with FreeRADIUS.
Interim:Will send START and STOP records and also periodically send updates to the server while a user session is active. This is less likely to lose session data if the firewall restarts without notifying the RADIUS server of a STOP message, but will cause increased database usage on the RADIUS server.

RADIUS Options

These options fine-tune how RADIUS authentication behaves.

Reauthentication:
 

If enabled, Access-Request packets will be sent to the RADIUS server for each user that is logged in every minute. If an Access-Reject is received for a user, that user is disconnected from the captive portal immediately. This allows actively terminating user sessions from the RADIUS server. Note If concurrent login limits are defined in RADIUS this option may not work properly, as the additional request would fail as the reauthentication attempt would be considered a second concurrent login.

Note

If reauthentication is combined with RADIUS accounting, Interim accounting updates must be used to track usage during sessions, otherwise the RADIUS server will not know if a user exceeds limits until they logout.

RADIUS MAC authentication:
 

If this option is enabled, the captive portal will attempt to authenticate users by sending their MAC address as the username and the password entered into MAC authentication secret to the RADIUS server. This option cannot be used if MAC filtering is disabled.

RADIUS NAS IP attribute:
 

This field controls what is sent to the RADIUS server in the Calling-Station attribute. Choose the Interface/IP address to use from the drop-down list.

Session-Timeout:
 

When Use RADIUS Session-Timeout attributes is enabled, clients will be disconnected after the amount of time retrieved from the RADIUS Session-Timeout attribute

Type:

Sets the RADIUS vendor type for the client behavior. If RADIUS Type is set to Cisco, Access-Request packets will have the value of Calling-Station-Id set to the client IP address and the Called-Station-Id set to the client MAC address. Default behavior is Calling-Station-Id = client MAC address and Called-Station-Id = firewall WAN IP address.

Accounting Style:
 

When Invert Acct-Input-Octets and Acct-Output-Octets is enabled, data counts for RADIUS accounting packets will be taken from the client perspective, not the NAS. Acct-Input-Octets will represent download, and Acct-Output-Octets will represent upload.

NAS Identifier:

The hostname of the firewall is sent as the NAS Identifier by default. Specify a NAS Identifier here to override the default value

MAC address format:
 

This option changes the MAC address format used in RADIUS. Change this to alter the username format for RADIUS MAC authentication to one of the following styles:

Default:Colon-separated pairs of digits: 00:11:22:33:44:55
Single Dash:Digits in two groups, separated by a single dash halfway: 001122-334455
IETF:Hyphen-separated pairs of digits: 00-11-22-33-44-55
Cisco:Groups of four digits separated by a period: 0011.2233.4455
Unformatted:All digits together with no formatting or separators: 001122334455

HTTPS login

Check this box to use HTTPS for the portal page. If enabled, an SSL Certificate must also be selected.

HTTPS server name:
 Specify the FQDN (hostname + domain) to be used for HTTPS. This must match the Common Name (CN) on the certificate to prevent users from receiving certificate errors in their browsers.
SSL Certificate:
 Select the SSL certificate to be used by the portal for HTTPS logins. Certificates are managed in Certificate Management.
Disable HTTPS Forwards:
 When checked, attempts to connect to HTTPS sites on port 443 are not redirected to the portal. This prevents users from receiving invalid certificate errors. Users must attempt a connection to an HTTP site, and will then be forwarded to the portal.

HTML Page Contents

Using these controls, custom HTML pages can be uploaded to alter the look of the page presented to users when they are redirected to the portal.

Customizing these pages is optional. Any page contents left blank will use internal defaults.

Portal pages may contain PHP code, and may also include other resources such as images and CSS files. See File Manager for more information on including additional assets in a custom portal page.

Warning

Because custom portal pages can run PHP, ensure to properly secure the code in the page so it cannot be exploited by connecting users. Also, avoid granting privileges to this page to untrusted administrators.

In each individual section, the pages can be managed using the displayed controls:

  • To upload a new page, click Browse and select the file to upload. When the portal options are saved, the file will be copied.
  • To view an existing page, click fa-file-text-o View
  • To download a copy of an existing page, click fa-download Download
  • To erase the custom page, click fa-undo Restore Default Page

Portal page contents

This control is for the main portal page presented to users. Depending on the selected options for the portal, use one of the following examples as the basis for a custom page.

Portal page without authentication

This shows the HTML of a portal page that can be used without authentication.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Click Continue to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Continue">
	</form>
</body>
</html>
Portal page with authentication

Here is an example portal page requiring authentication.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Enter your username and password and click Login to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="auth_user" type="text">
		<input name="auth_pass" type="password">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Login">
	</form>
</body>
</html>
Portal page with Vouchers

Here is an example portal page for use with vouchers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Enter your voucher code and click Login to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="auth_voucher" type="text">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Login">
	</form>
</body>
</html>

Authentication error page contents

Using this control, optionally upload a custom HTML page to be displayed when authentication errors happen. An authentication error occurs when a user enters a bad username or password, or in the case of RADIUS authentication, potentially an unreachable RADIUS server.

By default, this error page is simply the login page again.

Logout page contents

The logout page is presented to the user after login and it triggers a popup window. The default code uses JavaScript to create the new window in the following way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<html>
<head><title>Redirecting...</title></head>
<body>
<span style="font-family: Tahoma, Verdana, Arial, Helvetica, sans-serif; font-size: 11px;">
<b>Redirecting to <a href="<?=$my_redirurl;?>"><?=$my_redirurl;?></a>...</b>
</span>
<script type="text/javascript">
//<![CDATA[
LogoutWin = window.open('', 'Logout', 'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=256,height=64');
if (LogoutWin) {
	LogoutWin.document.write('<html>');
	LogoutWin.document.write('<head><title>Logout</title></head>') ;
	LogoutWin.document.write('<body style="background-color:#435370">');
	LogoutWin.document.write('<div class="text-center" style="color: #ffffff; font-family: Tahoma, Verdana, Arial, Helvetica, sans-serif; font-size: 11px;">') ;
	LogoutWin.document.write('<b>Click the button below to disconnect</b><p />');
	LogoutWin.document.write('<form method="POST" action="<?=$logouturl;?>">');
	LogoutWin.document.write('<input name="logout_id" type="hidden" value="<?=$sessionid;?>" />');
	LogoutWin.document.write('<input name="zone" type="hidden" value="<?=$cpzone;?>" />');
	LogoutWin.document.write('<input name="logout" type="submit" value="Logout" />');
	LogoutWin.document.write('</form>');
	LogoutWin.document.write('</div></body>');
	LogoutWin.document.write('</html>');
	LogoutWin.document.close();
}

document.location.href="<?=$my_redirurl;?>";
//]]>
</script>
</body>
</html>

Most browsers have pop-up blockers that will most likely stop that logout window from appearing, so investigate other possible means of creating a JavaScript pop-up using similar code.