Feature #15904
open
Add native support for Captive Portal API (RFC8908)
0%
Description
Add an option in Kea to automatically support RFC8910, DHCP Option 114 through a GUI option for all Captive Portals. This DHCP 114 option is now a default option in KEA, "v4-captive-portal". This would take the form of a simple checkbox (something like "send DHCP114 default string for Captive Portals") that would enable index.php to send the required JSON information for the Device to load the Captive Portal Logon, Logout page as applicable if this box was checked in Kea Setup GUI. There is also a Vendor URL option in RFC8910 that should default to the logout page for the "automatic" checkbox.
I assume Kea will be supporting the entry of string(s) for both logon and vendor url and this is an option to simplify support for the captive portal on smart phones. The JSON simply contains the login url and for the "Captive Portal Page" in iOS it is the logout page or a custom page if desired.
Currently all iOS and many smart devices can not log into the captive portal because they do not support html until after they have internet access. Internet access can only be obtained by launching the login page within the internal temporary browser which obtains the URL from the JSDON string values sent in DHCP option 114. They also do not permit an https:// url until internet access is provided. The only option for them to work with captive portal is through RFC8910 and it can be complex for many pfSense users to understand. This would simplify Captive Portal and make it work with all devices. Thus, it is a logical upgrade.
I have attached a file from the user support forum that implements this currently with ISC (and KEA thru Redmine #15321 for Plus 24.11) and is commonly used to solve this problem. It is derived from index.php which has changed for Plus 24.11 and this implementation would ensure compatibility with future releases of pfSense as index.php evolves over time.
Files
Updated by Dale Harron 4 months ago
- File index-2411-Dec10.php index-2411-Dec10.php added
- File RFC8910-Dec10.php RFC8910-Dec10.php added
Support for Kea requires handling the Reclamation and reassignment of IPs which has changed dramatically from that implemented in the ISC DHCP server. Captive Portal tracks authentication by checking IPs when in actual fact the Captive portal authorization is associated with the MAC address, not the IP. This is an issue with Kea as the IP of authenticated users can change "over a lunch break" and when the device returns, it's IP may have been reassigned. Thus, RFC8910 DHCP option 114 support ("v4-captive-portal") must check the MAC address against the Captive Portal database and index.php in Captive Portal must re-associate the current IP with the already authorized MAC to avoid confusion when the IP address is checked by the Captive Portal code within pfSense.
To demonstrate one possible approach, I have attached a copy of a bench test file for both RFC8910.php and index.php that demonstrates how this might be achieved. These files are intended for use on pfSense 24.11 Plus (Stable) with Kea enabled and utilizing the patch from Redmine #15321 (https://redmine.pfsense.org/issues/15321) to support Smart devices through RFC8910, DHCP 114.
Updated by Dale Harron 4 months ago
- File index-2411-Dec11.php index-2411-Dec11.php added
Updated by Dale Harron 4 months ago
- File index-2411-Dec11.php index-2411-Dec11.php added
I see in the index-Dec10.php file that there is a stupid commenting error, you have to remove the /*... */ from lines 153 and line 180 or it will give a crash report. I must have broken a “mixed comment symbols” rule.
Updated by Dale Harron 4 months ago
- File RFC8910-Dec11.php RFC8910-Dec11.php added
In order to fully support the assumption that it is the MAC address that authorizes the device through the captive portal, it was necessary to call index.php through the DHCP 114 JSON if the IPs didn't match, even if the MACs do match. This will result in the device being redirected to the logout screen in the temp browser on an iPhone for example if the IP has changed since their last connection.
A revised RFC8910.php file is attached that implements this as well.
Updated by Dale Harron 4 months ago
- File index-2411-Dec17.php index-2411-Dec17.php added
Improved comments and removed test code from index.php Dec 17, 2024
Updated by Marcos M about 2 months ago
- Subject changed from Built-in Captive Portal Support for RFC8910, DHCP option 114 in Kea. to Add native support for Captive Portal API (RFC8908)
- Category changed from DHCP (IPv4) to Captive Portal
Updated by Dale Harron about 2 months ago
The implementation of this is exceptionally simple:
Construct the same information strings as you would enter into the patch shown in Redmine 15321 (https://redmine.pfsense.org/issues/15321)
"opt2" -> is the interface that the captive portal is on.
"name": "v4-captive-portal", -> Kea uses this to define DHCP 114 (RFC8910) so this is a fixed value
"data: -> Simply take the URL used to access the captive portal login page and replace Index.php with rfc8910.php (which would be RFC8910-w-allowed-MAC-IP-fix.php attached to this Redmine, renamed to rfc8910.php)
eg:
],
"opt2": [ {
"name": "v4-captive-portal",
"data": “https://sub.domain.com:8003/rfc8910.php?zone=vlan1”
}
]
The device requesting option 114 will then load the "data" URL into the temp browser tab, which will execute the rfc8910.php code which in turn will return the RFC8910 JSON data back to the device as applicable. That data identifies if the device (based on it's IP) is already authenticated (F), unauthenticated (T), or nothing is returned if the IP or MAC has been passed through the captive portal.
If the JSON indicates "T", it will launch the appropriate captive portal login for that zone by loading the login URL specified in the JSON returned to it, bypassing the process of capturing an http:// URL and enabling a login on the device in a temporary browser that has already confirmed a secure connection to the captive portal. If correct credential are entered, internet access will be enabled on the portal and subsequently detected by the device.
If it indicates a "F", the device will assume it is on a captive portal but already has internet access (is authenticated) so it will simply confirm internet access and connect without further intervention. The same is true if IP or MAC are passed through the portal.
Note: rfc8910.php must be in the same directory as index.php, typically /usr/local/captiveportal
Updated by Dale Harron about 1 month ago
RE: the change of category from DHCP to captive portal.
As the captive portal is already associated with an interface; the eg: JSON for the Kea DHCP values associated with "v4-captive-portal" must be constructed by the captive portal and "inserted" into the Kea DHCP JSON for "v4-captive-portal" on that interface in advance as the information is presented to the client at the time of receiving the IP address, requesting DHCP 114 and provided with the RFC8910 JSON prior to becoming "captive". I assume this JSON will be displayed/visible in the new RFC8910 support from the patch provided in https://redmine.pfsense.org/issues/15321 and for 25.03 Stable as presented in the forum: https://forum.netgate.com/topic/196513/adding-custom-configuration-in-kea-dhcp-server-with-pfsense-25-03.
I suggest this is a DHCP category because the captive portal (RFC8910) support (checkbox) must be in the Kea interface GUI as the DHCP may not be configured yet when the captive portal is initially setup. This is demonstrated by the current implementations in use in both ISC and Kea. In both cases, setup of support for RFC8910 is completed in the DHCP server configuration.
Updated by Dale Harron 9 days ago
With the release of CE 2.8.0 Beta Apr 1 and 25.03 Plus Beta, both the index-2411-Dec17.php and RFC8910-Dec11.php remain compatible with those releases as index.php has no new modifications.