Captive Portals

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

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.

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.

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 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

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 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%&subcriber_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.

The configuration options in the automatic login section defines how the rXg captive portal behaves when a account with automatic login enabled joins the network and does not have an existing session. Enabling background mode and/or the portal mode allows accounts with automatic login enabled to connect without having to enter credentials at the captive portal.

If background mode is set to MAC , then the rXg will continually poll the ARP table and/or DHCP leases (as defined by the MAC to IP mapping setting in the device options). The rXg will then automatically create sessions for accounts with automatic login enabled, thus obviating the need for the account to login via the captive portal. If a login session is created by the rXg via the background mode then the end-user will never experience forced browser redirection. Enabling background mode is sufficient for handling most cases of automatic login. However, if the rXg becomes heavily loaded, then the polling nature of background mode automatic login may result in some end-users browsers experiencing forced browser redirect. Thus automatic login is also implemented in the captive portal and enabled via the portal mode option. Disabling the background mode may be necessary to operate in extremely high load environments. Disabling background mode may also be necessary when deploying the rXg in conjunction with certain wireless infrastructures that spoof MAC addresses.

If portal mode is set to anything other than disabled , then the rXg will attempt to create a session and/or login to the portal for accounts with automatic login enabled when a device with a matching MAC address hits the portal. The MAC (create session only) option creates a login session for the account but does not log the account into portal. Thus the end-user web browser is denied access to the profile information stored in the account. This option is most appropriate for high transient environments such as hotspots, hotzones, hotels, conference centers, etc. The MAC (create session, login to portal) creates a login session for the account and also logs them into the portal. This option is most appropriate for fixed wireless broadband environments where the end-user population is mostly static. The MAC AND cookie option is similar to the MAC (create session, login to portal) in that a session is created for the account and the web browser is granted access to the portal. However, in addition to checking for the MAC address, the browser is checked to make sure that a cookie matching one stored by the rXg during previous portal activity is present. This is the most secure method of enabling automatic login but it requires that the end-user bring up the same web browser that they used the last time they interacted with the rXg captive portal. The MAC OR cookie option is similar to MAC AND cookie , except the user's MAC address can have changed as long as there is still a matching cookie in the user's browser. This is useful for situations where a user switches between a wired and wireless connection, thereby changing MAC address. The MAC mode checks only the MAC address. The cookie mode checks only the browser cookie.

The WISPr settings are arbitrary strings that pass meta-data to WISPr client software. Consult the documentation that is provided by wireless service aggregrators 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.

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 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/?logged_in=%logged_in%&subcriber_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.

The session restrictions settings control the length of the end-user session as well as the automatic logout mechanism. The settings here may be overridden by various other configuration settings of the rXg. For example, if external RADIUS authentication is being utilized, the RADIUS Class attribute may be consulted to configure the session length. Another example is if the account has automatic login enabled. In that case, the portal will not be displayed again until the user no longer has any usage minutes.

Set the amount of time that an end-user is allowed to be logged on before they need to login again using the restriction field. If unlimited login time is desired, check the unrestricted box.

Check the no idle timeout box to disable the automatic logout upon idle feature of the captive portal web application. Account usage minutes will continue to be depleted regardless of traffic when the automatic logout feature is disabled. Alternatively, set a idle timeout to enable the automatic logout feature.

The grace time field enables the captive portal web application to allow end-users to be logged in for a short amount of time to complete the selection and purchase of a usage plan.

The redirect URL field enables the operator to redirect the end-user to a configurable URL after successful login. Check the original box to redirect the user to the URL she requested before being redirected by the captive portal. Leave both fields blank to display the post login success page of the landing portal.

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 Splash 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.

WiFi Profiles

The Name field is arbitrary and can be set to anything.

The SSID field is used to set the SSID that will be contained in the profile that the client device will connect to after downloading the profile.

The Default checkbox, if checked specifies that this WiFi Profile will apply to all landing portals.

The Server Certificate field allows the operator to specify the SSL certificate that will be included with the profile.

The Landing Portals field allows the operator to specify which landing portal(s) will present the WiFi Profile when the client device successfully connects.

WiFi Profiles allow the operator of the rXg to configure the profiles that will be downloaded to the client device when it succesfully connects to the network. The profile contains the information to connect to the network and installs the certifcate on the device.