Captive Portals

The captive portal view presents the scaffolds that configure the behavior of the rXg forced browser redirect mechanism.

Figure: The Captive Portal view showing Policies, Splash Portals, Landing Portals, and Secret Questions scaffolds.

The initial forced browser redirect is configured via the splash portals scaffold. Once a device has acquired an IP address via DHCP or via static assignment, the rXg enforces policy based on the group membership. In a typical scenario, most devices will initially be members of an IP group that spans the entire subnet from which the IP address of the device is assigned. To enable the forced browser redirect, the IP group must be configured with a policy that is associated with a splash portal record.

Figure: Sequence diagram showing captive portal authentication flow. Top: local portal with TOS acceptance. Bottom: external portal with API callback to update group membership.

Once redirected to the captive portal specified in the splash portal record, the end-user must present credentials to access the WAN. The supplied credentials determine the new group that the device will be a member of. In a typical scenario, the end-user will supply a username / password pair or a token code that is associated with a account group. If external identification is used, the device will be associated with a RADIUS group or LDAP group.

Figure: Policy association diagram. Pre-authentication policy links IP group to Splash Portal. Post-authentication policy links User group to Landing Portal plus additional enforcement mechanisms.

To complete the captive portal configuration, the new group must be associated with a policy that is linked to a landing portal. In addition, the new group must be of a higher priority than the first group. In a typical scenario, the new group is associated with a policy that is linked to several other enforcement mechanisms (e.g., bandwidth queues, multiple uplink controls, web experience manipulation, etc.).

Splash Portals vs Landing Portals

The captive portal system uses two types of portal configurations that work together:

Typical flow: 1. Device connects to network assigned to IP group with Splash Portal policy 2. User redirected to Splash Portal enters credentials 3. Credentials validated device moves to Account/RADIUS/LDAP group with Landing Portal policy 4. User experiences Landing Portal settings (session limits, post-login redirect, etc.)

Figure: Splash Portals scaffold listing showing portal assignment, whitelist, shared credentials, usage plans, and policy associations.

Splash Portals

Splash portals define the pre-authentication settings that are used when forced browser redirect is in effect.

The name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The portal field determines the local captive portal that will be used for pre-authentication. The default RG Nets portal is always available as a choice from this list. Additional choices for the portal field are determined by the custom portals scaffold on the portals view of the system module.

Setting the remote checkbox and specifying a remote URL enables forced browser redirect to a captive portal web application that is stored on a remote host. Using a remote host for the pre-authentication pages is not recommended for typical deployment scenarios due to increased latency and complexity. In most clustering and multi-unit central management scenarios, a customized local pre-authentication portal contains hyperlinks to a centrally served portal for unified end-user credential management.

The following substitutions are available for the remote URL :

• %url% - the original URL (desired URL) that the end-user surfed to
• %rxg% - the name of the rXg that executed the redirection
• %ip% - the IP address of the end-user
• %mac% - the MAC address of the end-user
• %wan_ip% - the WAN NAT IP address of the end-user
• %wan_mac% - the MAC address of the interface for the Uplink the user is assigned to
• %wan_mac_last6% - The last 6 characters of the WAN MAC, excluding colons
• %hostname% - the DHCP client hostname of the end-user
• %group% - the name of the group that the end-user was a member of during redirection
• %policy% - the name of policy that the end-user experienced during redirection
• %landing_portal% - the name of the splash portal that the end-user was presented
• %portal_controller% - the name of the custom portal controller that the end-user was presented
• %logged_in% - true or false depending on whether or not the end-user is logged in
• %random_number% - a random eight digit integer
• %error% - an error string
• %notice% - a notice string
• %exception% - an exception string
• %action% the custom portal action that the end-user was redirected to
• %redirect_action% - the custom portal action/view that the end-user was redirected to after processing the request
• %vlan% - client VLAN tag, if any
• %ap_mac% - MAC address of the AP to which the client is currently connected

An example of a remote URL that utilizes substitution is: http://central.srvr/port_app/?orig_url=%url%&subscriber_ip=%ip%

The whitelist field enables the operator to choose one or more wan targets that list IP addresses and/or DNS entries of websites that are to be exempt from the forced browser redirection policy configured by this splash portal record. There are many common uses for the whitelist. When credit card payment gateways are used, the payment gateway servers may need to be whitelisted in order for payments to be processed. If pay-per-click advertising is placed on the pre-authentication portal, the advertising destinations must be in the whitelist to enable proper click through and tracking. Cluster configurations require the cluster controller to be in the whitelist to enable unified user management. In addition, many operators use the whitelist to enable unfettered access to a handful of websites of their choosing.

Automatic Login

The automatic login settings control how the rXg handles accounts that have the automatic login flag enabled. These settings allow recognized devices to connect without manually entering credentials at the captive portal.

There are two distinct mechanisms for automatic login: background mode and portal mode. Understanding the difference is critical for proper configuration.

Background Mode

Background mode continuously polls the ARP table and/or DHCP leases (as defined by the MAC to IP mapping setting in the device options) looking for devices with MAC addresses that match accounts with automatic login enabled. When a match is found, the rXg automatically creates a login session without the end-user ever experiencing forced browser redirection.

When to disable background mode: - When deploying behind NAT devices or firewalls that present a single MAC address for multiple users (e.g., FortiGate, other upstream routers) - In extremely high load environments where polling overhead is a concern - When deploying with wireless infrastructure that spoofs or randomizes MAC addresses

Portal Mode

Portal mode triggers only when a device actually visits the captive portal URL. If the device matches an account with automatic login enabled, the rXg can automatically create a session and/or log the user into the portal.

Choosing the right portal mode: - Use cookie mode when devices connect through NAT or firewall devices that mask the true MAC address - Use MAC modes when you have direct Layer 2 visibility to end-user devices - Use disabled when you want users to enter credentials on every visit

The WISPr settings are arbitrary strings that pass meta-data to WISPr client software. Consult the documentation that is provided by wireless service aggregators for the proper settings for these fields.

The TOS checkbox enables a terms of service requirement for the pre-authentication captive portal.

The policy field relates this record to a set of groups through a policy record.

The shared credential groups field determines which shared credential logins are to be accepted by this portal.

The usage plans field determines which usage plans are to be displayed and accepted by this portal.

Figure: Landing Portals scaffold listing showing portal assignment, session limits, blacklist, usage plans, and policy associations.

Landing Portals

Landing portals define the post-authentication settings that are used when forced browser redirect is in effect.

The name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The portal field determines the local captive portal that will be used for post-authentication. The default RG Nets portal is always available as a choice from this list. Additional choices for the portal field are determined by the custom portals scaffold on the portals view of the system module.

Setting the remote checkbox and specifying a remote URL enables post-login browser redirect to a captive portal web application that is stored on a remote host. The same URL substitutions available for Splash Portals (see above) are also available here.

An example of a remote URL that utilizes substitution is: http://central.srvr/port_app/?logged_in=%logged_in%&subscriber_ip=%ip%

The blacklist field enables the operator to choose one or more wan targets that list IP addresses and/or DNS entries of websites that are always to be redirected to the captive portal web application selected in this landing portal record. In a clustering scenario, it may be useful to redirect certain web accessible cluster resources back to the post authentication portal for load balancing. In an advertising scenario, it may be useful to redirect access for particular websites to the local captive portal web application so that focused local content is delivered over generic content.

Session Restrictions

The session restrictions settings control the length of the end-user session as well as the automatic logout mechanism.

Note: These settings may be overridden by other rXg configurations. For example: - RADIUS Class attribute may specify session length for external authentication - Accounts with automatic login enabled will not see the portal again until usage minutes are exhausted

The policy field relates this record to a set of groups through a policy record.

The usage plans field determines which usage plans are to be displayed and accepted by this portal.

Users Behind NAT or Upstream Devices

The rXg identifies end-users primarily by their MAC address, which is obtained from the ARP table or DHCP leases. This design assumes that each end-user device is directly Layer 2 connected to the rXg, allowing the rXg to see the actual MAC address of each device.

Direct LAN Connection (Recommended)

In the recommended deployment topology, end-user devices connect to access points or switches that are Layer 2 connected to the rXg. The rXg observes each device's unique MAC address and can accurately identify individual users for authentication and policy enforcement.

  +----------------------+
  | User A               |
  | MAC: aa:bb:cc:11:22:33 |----+
  +----------------------+    |
                              |      +------------+       +-----------+
  +----------------------+    +----->|            |  LAN  |           |
  | User B               |---------->|   Switch   |------>|    rXg    |-----> WAN
  | MAC: dd:ee:ff:44:55:66 |-------->|   or AP    |  L2   |           |
  +----------------------+    +----->|            |       +-----------+
                              |      +------------+             |
  +----------------------+    |                                 v
  | User C               |----+                      +-------------------------------+
  | MAC: 11:22:33:77:88:99 |                         | Captive Portal                |
  +----------------------+                           | Sees:                         |
                                                     |  aa:bb:cc:11:22:33 --> User A |
                                                     |  dd:ee:ff:44:55:66 --> User B |
                                                     |  11:22:33:77:88:99 --> User C |
                                                     +-------------------------------+

In this configuration, the captive portal correctly identifies each user by their unique MAC address. MAC-based automatic login functions as expected, and each user maintains an independent session.

Portal Traffic Through Northbound NAT Device (Problematic)

When the rXg connects to the internet through a northbound firewall using cgNAT or private WAN addresses, and the portal DNS (e.g., wi.fi) resolves to the firewall's public IP address, portal traffic exits the rXg, reaches the firewall, and hairpins back to the rXg. In most configurations, this traffic arrives with the firewall's MAC and IP address instead of the original user's. The IP address is rewritten by the firewall's NAT/SNAT, while the MAC address changes because the firewall is the Layer 2 next-hop when returning the traffic.

  +----------------------+
  | User A               |----+
  | MAC: aa:bb:cc:11:22:33 |  |
  +----------------------+    |
                              |      +------------+       +-------+      +------------+
  +----------------------+    +----->|            |  LAN  |       | WAN  |  Firewall  |
  | User B               |---------->|   Switch   |------>|  rXg  |----->|  (NAT)     |-> Internet
  | MAC: dd:ee:ff:44:55:66 |-------->|   or AP    |       |       |cgNAT |            |
  +----------------------+    +----->|            |       +-------+      +------------+
                              |      +------------+           ^         Public IP: 203.0.113.1
  +----------------------+    |                               |         (wi.fi resolves here)
  | User C               |----+                               |
  | MAC: 11:22:33:77:88:99 |                                  |
  +----------------------+                         +----------+----------+
                                                   | Portal request for  |
                                                   | wi.fi (203.0.113.1) |
                                                   | goes OUT to firewall|
                                                   | and comes BACK with |
                                                   | firewall's MAC/IP   |
                                                   +---------------------+

                                              Captive Portal Sees:
                                               fe:dc:ba:98:76:54 --> ?
                                               fe:dc:ba:98:76:54 --> ?
                                               fe:dc:ba:98:76:54 --> ?
                                              (All users appear as firewall's MAC)

In this configuration, the rXg cannot distinguish between individual users because they all appear to have the same MAC address. This commonly occurs when:

• Portal DNS resolves to a public IP address on a northbound firewall, causing traffic to hairpin back through the firewall
• The rXg WAN interfaces use cgNAT or private address space behind an upstream NAT device

Why Not Point Portal DNS to the rXg cgNAT Address?

Pointing the portal DNS to the rXg's cgNAT WAN address would avoid the hairpin NAT problem, as traffic would arrive directly at the rXg and the original client MAC address would be visible. However, this approach has significant drawbacks:

• SSL/TLS certificate issues: Publicly trusted certificates cannot be issued for private or cgNAT (RFC 6598 - 100.64.0.0/10) IP addresses. Users would see certificate warnings or errors in their browsers, which degrades the user experience and may prevent portal access on devices with strict certificate validation.

• Multiple uplinks: When the rXg has multiple cgNAT uplinks, determining which IP address the portal DNS should resolve to becomes problematic. Users connected via different uplinks would need to reach different addresses.

• External access: cgNAT addresses are not routable from the public internet. If users need to access portal features (such as account management) from outside the network, they would be unable to reach the portal.

For these reasons, when the portal must be accessible via a public IP address on a northbound NAT device, the recommended approach is to use cookie-based authentication as described below.

Symptoms of Shared MAC Address Issues

When multiple users share the same apparent MAC address, the following problems may occur:

• The first user logs in successfully, but subsequent users are automatically logged in as the first user due to MAC-based automatic login
• Subsequent users receive errors indicating the device is already registered to another account
• Only one user can maintain an active session at a time, with new logins terminating existing sessions
• All users are assigned to the same account group regardless of their individual credentials

Lock Devices Feature and Shared MAC Environments

The lock_devices setting on accounts and usage plans binds a device's MAC address to a specific account, preventing that MAC from being used with other accounts. This feature is designed to prevent users from avoiding disconnect fees or late payments by creating new accounts with the same device.

In standard deployments where each user has a unique MAC address visible to the rXg, lock_devices works as intended:

1. User A signs up with lock_devices enabled on their account or usage plan
2. Their MAC address (e.g., aa:bb:cc:11:22:33) is bound to their account
3. If User A sells their router to User B, User B cannot create a new account with that MAC - they must contact support to release the device

However, in shared MAC environments (such as hairpin NAT scenarios), lock_devices causes complete service disruption:

• When any user with lock_devices enabled authenticates, the shared MAC address (the firewall's MAC) becomes locked to that user's account
• All other users will be blocked from logging in because the MAC is already locked to someone else
• Users will see "device locked" errors at the portal and be unable to authenticate

Recommendation: When deploying in shared MAC environments, ensure that lock_devices is disabled on all accounts and usage plans. This setting can be configured at the account level or inherited from the usage plan.

Recommended Configuration for Shared MAC Environments

When deploying the rXg in environments where users may share a common MAC address, the portal automatic login and background automatic login settings must be configured to avoid MAC-based identification.

Solution 1: Cookie-Based Authentication

Set the portal mode in the splash portal to cookie instead of any MAC-based option. With this configuration:

• Users must enter credentials on their first visit to the captive portal
• The rXg stores a session cookie in the user's browser upon successful authentication
• Returning users are identified by this browser cookie rather than their MAC address
• Multiple users behind the same NAT device can each maintain separate sessions as long as they use different browsers or devices

Additionally, set background mode to disabled to prevent the background automatic login process from associating the shared MAC address with a single account.

Solution 2: Shared Credential Groups

For environments where individual user accounts are not required, shared credential groups provide an alternative approach. Configure a shared credential group with the following settings:

• Set the credential to a common password or leave blank for free access
• Set unlimited simultaneous sessions or configure max simultaneous sessions to accommodate the expected number of concurrent users
• Each user who authenticates with the shared credential receives a unique login session with a randomly generated login identifier

This approach is appropriate for guest networks, public hotspots, or venues where individual user tracking is not required.

Solution 3: Disable Automatic Login

Set both portal mode and background mode to disabled. This configuration requires users to enter their credentials each time they access the network. While less convenient for end-users, this approach ensures that MAC addresses are never used for automatic session creation and eliminates the possibility of users being incorrectly associated with another user's account.

Solution 4: LAN-Based Portal Address

If the hairpin NAT problem is the root cause of shared MAC addresses, pointing the portal DNS (e.g., wi.fi) to a LAN address on the rXg eliminates the issue entirely. When clients connect to the portal via a LAN address, traffic remains on the local network and the rXg observes each client's actual MAC address directly from the ARP table.

To implement this solution:

1. Configure the portal DNS record (e.g., wi.fi) to resolve to a LAN IP address on the rXg that all clients can reach
2. Ensure this LAN address is accessible from all VLANs or network segments where clients reside
3. MAC-based automatic login modes will function correctly since the rXg sees authentic client MAC addresses

Certificate Warning Considerations

This approach introduces SSL/TLS certificate complications that operators must carefully evaluate:

• Publicly trusted certificates cannot be issued for private IP addresses. Certificate authorities will not issue certificates for RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or RFC 6598 cgNAT (100.64.0.0/10) address space.

• Users will see certificate warnings when accessing the portal. Modern browsers display prominent security warnings for sites with untrusted certificates, which may alarm users or prevent access entirely on devices with strict certificate validation (such as some mobile devices or managed enterprise endpoints).

• Captive portal detection may fail on some devices. Operating systems that perform HTTPS-based captive portal detection may not properly trigger the sign-in prompt when certificate validation fails.

• Self-signed or internal CA certificates can mitigate warnings for managed device fleets, but require certificate distribution to all client devices - which is impractical for guest networks or BYOD environments.

This solution is most appropriate when:

• The network serves a controlled device population where certificates can be distributed
• Users are technically sophisticated and can accept certificate warnings
• The degraded user experience from certificate warnings is acceptable compared to the complexity of cookie-based authentication
• External portal access from outside the network is not required

Automatic Login Mode Reference

The following table summarizes when each automatic login mode is appropriate:

Portal Mods

Portal Mods allow the operator of the rXg to modify an existing portal, content can be modified by selecting the view and adding HTML content that will replace the view. Images can also be replaced as well. This allows the operator to easily change images and specify the login options for example.

The name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The Custom field allows the operator to select the custom portal the Portal Modification record applies to.

The Splash and Landing fields allow the operator to select which Splash and Landing portals the record will apply to. This allows the operator to use the same portal but have different changes to either the Splash or Landing side of the portal(s).

The Splash field allows the operator to specify the Splash portal(s) the Portal Modification will apply to.

The Landing field allows the operator to specify the Landing portal(s) the Portal Modification will apply to.

The View field selects the view in the portal that will be modified.

The HTML(ERB) field, contains the code that will modify the selected view.

The Image field, is used to upload an image to replace an existing image in the portal, or can be used to upload an image to be used in the HTML(ERB) field.

The Image to Replace field combined with the Image field allows the operator to replace and existing image on the portal with a custom image.

For examples of how to use Portal Mods see the Portal Customization::Portal Modifications section of the manual.

Figure: Portal Modifications scaffold showing columns for Name, Splash, Landing, Custom portal, View, Image, and HTML(ERB) content.

WiFi Profiles

WiFi Profiles allow the operator of the rXg to configure profiles that are downloaded to client devices when they successfully connect to the network. The profile contains the information needed to connect to the network and can install a certificate on the device if configured.

Figure: WiFi Profiles scaffold listing showing Name, SSID, Default, Auto Download, Server Certificate, and Landing Portals columns.

Figure: Create WiFi Profile form showing configuration fields including Auto Download option to automatically download profile after login success.