1.
Captive Portal
pfSense 2.3/2.4
May 2017 Hangout
Jim Pingle

2.
About this Hangout
● Project News
● What is Captive Portal?
● How does Captive Portal
work?
● What can/can’t Captive Portal
do?
● Zones
● Authentication Methods
● Vouchers
● Portal Settings
● Pass-through
● Walled Garden
● Redirects
● Custom Login Pages
● Portal Detection
● Status & Graphs
● RADIUS Accounting & Limits
● Troubleshooting

3.
Project News
● 2.3.4-RELEASE out now
– Security/Errata fixes, a couple new features
– Chrome 58 certificate fix
● 40 Gbit/s IPsec on commodity hardware talk at OSCON
– https://conferences.oreilly.com/oscon/oscon-tx/public/schedule/detail/56727
● More pictures of upcoming R-1 platform
– https://www.netgate.com/blog/lord-vader-your-firewall-is-ready.html
● pfSense 2.5 will require AES-NI
– Will not be a factor for some time yet, more than a year off if not longer, so plenty of time to prepare.
– Some other onboard crypto accelerators will be OK, such as those on our other platforms like SG-
1000
– Read the blog posts for more:
https://www.netgate.com/blog/pfsense-2-5-and-aes-ni.html
https://www.netgate.com/blog/more-on-aes-ni.html
● BandwidthD package is back!
● SG-2320/2340 will not be sold as firewalls with pfSense pre-loaded, due to an HDMI issue
with FreeBSD. Will be available as kits on Amazon. See link for details:
– https://www.netgate.com/blog/introducing-sg-2320-and-sg-2340-appliances.html

4.
What is Captive Portal?
●
Captive Portal prevents user traffic from exiting the local network
until the user authenticates using the portal login page
●
The portal captures HTTP requests and redirects unauthenticated
users to the Captive Portal login page
– HTTPS redirects are also possible in some cases, browsers have been
getting smarter about handling this case
● Captive Portals are often used to present users with a ToS or User
Agreement, business information, to monetize Internet access,
prevent unauthorized Internet usage, and other similar uses
●
Captive Portals are commonly found in businesses (BYOD/Guests),
especially in the hospitality and travel industries: Libraries, Cafes,
Hotels, Restaurants, Airports, and so on

5.
How does Captive Portal work?
● Operates primarily at Layer 2
● Checks the user’s MAC address and/or IP address, depending
on settings
● Allowances can be made via Bypass lists for
sources/destinations based on MAC or IP address
– Always-on devices like printers, local servers, remote resources,
walled garden style setups
● If the user is not on a Pass-through list and is not logged in, they
get redirected to the portal
● Once a user is authenticated, their traffic flows based on regular
firewall rules, as if the portal were not there

6.
What can/can’t Captive Portal do?
●
It can …
– Keep users penned inside the LAN until they authenticate
– optionally enact per-user bandwidth limits, similar to limiters
– Work with a bridge of multiple LAN ports, but must be on assigned bridge (e.g. bridge0 as an OPT interface)
●
It cannot …
– Provide encryption for user traffic
● It is authentication only! So things like WPA2 are still important for wireless
– Prevent users from reaching other devices in the same network
● That requires security at the switch/AP level!
– Act as a “reverse” portal for clients on the WAN attempting to reach servers on the LAN
– Work with IPv6
– Work if users are behind a NAT router locally behind the portal
● Users must have a unique MAC and/or IP address!
– Setup firewall rules based on username
– Authenticate against LDAP (yet)
– Work seamlessly with a proxy, especially in non-transparent mode

7.
Prerequisites
● Users must have functional DNS
– Either use pfSense for DNS or setup bypass for designated external servers
– Firewall rules must allow DNS traffic (TCP/UDP port 53)
● Firewall rules must allow user traffic outbound to the Internet, at least to 80/443, or they can’t
be redirected to the portal
● Users must be able to access the firewall itself on the captive portal port
– For the first zone, HTTP is 8002 & HTTPS is 8003
– Next is 8004/8005, and so on. Check Diagnostics > Sockets
– If using HTTP only, then allow to HTTP port (8002)
– If HTTPS redirects will be allowed, allow to both HTTP and HTTPS (8002-8003)
●
Other traffic to the firewall can be rejected if needed
● If you plan to use HTTPS portal logins:
– Setup a server/GUI certificate first, e.g. LE/ACME (See last month’s hangout) or cert from another issuer
– Setup a DNS host override so portal clients resolve the firewall hostname to the firewall IP address on
their network
● DNS Forwarder + “localise-queries” advanced opt can be helpful for multiple portals

8.
Zones
● Zones define separate, independent Captive
Portal instances
● Each zone may have a different configuration
● There must be at least one zone
● A zone may be used by one or more interfaces
● An interface may only belong to a single zone
● The zone and description name cannot be
changed after they are created

9.
Authentication Methods
● None/Open (“Click through”)
– Useful for showing users a ToS/Splash page without requiring a login
● Local Users
– Useful for small numbers of users (~10 or so)
– Optional Captive Portal user permission requirement
● Vouchers
– Great for time-limited anonymous but secure access
– Ideal for locations with many public/random unknown users
– Popular with hotels and restaurants, where creating or re-using common user accounts is
not viable
● RADIUS
– Useful for large numbers of users
– Can tie into existing authentication structure such as AD or external RADIUS server
– Extended attributes such as per-user bandwidth or time limits
– Can be used with 2FA if the RADIUS server supports 2FA

10.
Vouchers
● Secure access codes generated based on cryptographic keys
● All vouchers have set time limits, specified in minutes
● Voucher timers start counting the moment of the first login,
and do not stop counting
– No logout/pause
● Created in batches called “rolls” and all vouchers on the same
roll have the same time limit
● Used or expired vouchers cannot be reused
● Voucher rolls can be exported in .csv format to import into
another system such as a POS, or for printing

11.
Basic Portal Settings
● Create zone, edit zone
● Enable, select interface(s)
● Max Concurrent Connections: Controls how many people can access the portal
web service at a time, not a logged-in-user limit
● Idle timeout (Activity limit), hard timeout (Session limit – set less than DHCP lease)
●
Logout pop-up – Not very effective due to pop-up blocking in browsers
● Redirect URL – covered later
●
Concurrent User Logins – Prevents multiple logins from the same user
● MAC Filtering – useful when routing, not direct Layer 2
●
Per-User Bandwidth restriction – sets up a limiter for each user
● Authentication – pick whichever method is best for this env
●
HTTPS login – needs a cert from a CA trusted by the user's browser
● Custom pages – covered later

12.
Redirects
● Enter a complete URL, including the protocol prefix (e.g. http:// or https:// )
● Pre-authentication redirect
– Requires special code handling in the portal login page and on the landing page
● Sample code is in the book
– Requires any external content to be allowed via IP or host pass-through entries
– If blank, the captive portal page is presented directly
● Post-authentication redirect
– Good for a welcome/landing/business page after login, or redirecting to a preferred
search engine
– If blank, user will be redirected to whichever page they originally requested
● Blocked MAC address redirect
– If a MAC is set to be blocked on the MACs tab, the user will be redirected to this URL
– Useful for blocking infected systems or known offenders

13.
Pass-through
● MACs Tab
– Pass or block specific MAC addresses
– Apply bandwidth limits to a specific MAC address
– Useful for limiting a client no matter what IP address it uses
● Allowed IP Addresses Tab
– Pass all traffic to and/or from a specific IP address or subnet
●
“From” allows traffic from this source, “To” allows traffic destined for this host, “Both” allows both
– Apply bandwidth limits to a specific IP address or subnet
– Useful to allow local servers to get unrestricted access, remote DNS servers, other remote content
servers
● Allowed Hostnames tab
– Similar to the IP address tab, but works with hostnames instead
– Hosts are periodically resolved and updated
– Works best with static responses, or infrequently changing responses like DynDNS
– Does not work for hosts with randomized DNS responses (e.g. RRSET)
● Makes this impractical for use with large sites or sites using CDNs

14.
Walled Garden
●
A walled garden is a fancy term for keeping some external content
available without authentication
●
For example a company website or property page may be externally
hosted, but should be visible to users even before they authenticate
●
Setup using IP address or Hostname bypass
●
Can takes some effort to dial in proper bypass settings for sites that
have external content like ads, stats/tracking/metrics, hosted scripts
and so on
●
Maybe put links up on the portal landing page for users to follow, if
the allowed sites are public knowledge
●
This is also required for a Pre-Auth redirect to work

15.
Custom Login Pages
● Do not copy/paste code from “View Source” as this breaks macros!
● Sample code is on the zone configuration
– More samples on the forum, for example
https://forum.pfsense.org/index.php?topic=26141.0
– Also samples in the book, can download from HTML copy of the book
https://portal.pfsense.org/docs/book/captiveportal/zone-configuration-options.html#portal-pag
e-contents
● For existing customized pages, there are download links to get current page content
or reset to default
● Example page from this demo will be available for download
● The stock Captive Portal page code can be found in the source
– Ex: https://github.com/pfsense/pfsense/blob/master/src/etc/inc/captiveportal.inc#L41
● Upload images, CSS, etc using the File Manager tab
– Uploaded files are prefixed with “captiveportal-”, for example “captiveportal-logo.png”, which
must be accounted for in the HTML code
● If you upload a custom logout page without a redirect, and the user visits the portal
login URL while signed in, they will receive the logout page instead.

16.
Portal Detection
●
Browsers and operating systems are getting better at detecting the presence of
Captive Portal systems, even HTTPS redirects!
– Firefox: http://detectportal.firefox.com/success.txt
– Apple:
● http://captive.apple.com/hotspot-detect.html
● http://www.apple.com/library/test/success.html
– Chrome: If loading an HTTPS page times out or gets a cert error, it tries:
●
http://www.gstatic.com/generate_204
– Android, Chromium OS: Similar to chrome but different URLs
● http://connectivitycheck.gstatic.com/generate_204
●
http://clients3.google.com/generate_204
●
Clients need functional DNS and the above URLs have to fail or return unexpected
text
●
If all else fails, direct users to attempt to load an HTTP site
●
Do not add any kind of bypass for the above sites or similar sites, or else the portal
detection will fail and then users will have to manually load a site to work around that

17.
Status & Graphs
● Status > System Logs, Captive Portal Auth tab shows a
record of logins and error messages (if any)
● Status > Captive Portal shows online users, their IP and
MAC address, login time, and a disconnect button
● Status > Monitoring, set axis to Captive Portal and there are
two graph choices for each zone:
– Logged In: Counts the number of login events during a time period
– Concurrent: Count of users online at a specific time
● Voucher tabs allow for viewing online voucher users, roll
status, testing vouchers, and expiring vouchers

18.
RADIUS Accounting & Limits
● Not enough time to get into detail…
● Setup Captive Portal RADIUS auth and accounting against, for
example, FreeRADIUS
– Use “Stop/Start (FreeRADIUS)” for accounting updates
– Set it to reauthenticate every minute or the users can’t be kicked off
when they exceed limits
● FreeRADIUS actually tracks the usage and decides when to cut
off a user, not the portal!
● Make sure FreeRADIUS has an interface set for accounting
● On each user, setup either “Time Configuration” or “Traffic and
Bandwidth” for the limits to use

19.
Troubleshooting
● No redirect to portal page?
– Check if DNS is working. If DNS server is remote (e.g. 8.8.8.8), add to
Allowed IP addresses tab.
● Alternately, setup a NAT rule to intercept DNS, redirect TCP/UDP to 127.0.0.1:53 if the
original destination is “! LAN Address”
– Check firewall rules
● Make sure clients are allowed outbound access to port 80 (HTTP) and/or 443 (HTTPS)
● Make sure clients are allowed access to the portal daemon (e.g. 8002-8003)
– Client has HTTPS home page. Have them load an HTTP page if HTTPS
redirects are disabled or the client mishandles HTTPS redirects.
– Try hitting portal ip:port directly
● More advanced troubleshooting here:
– https://doc.pfsense.org/index.php/Captive_Portal_Troubleshooting

20.
Conclusion
● Questions?
● Ideas for hangout topics? Post on forum,
comment on the blog posts, Reddit, etc