Captive Portal Identification (CPI), defined by DHCP Option 114, is a standardized mechanism allowing a network to inform devices that a captive portal is present and provide them with the exact URL for authentication.
This feature enhances device recognition, reduces user friction, and ensures compatibility with modern operating systems like iOS that support automatic captive portal detection.
In Cloudi-Fi’s implementation, CPI works to streamline authentication workflows and support device persistence—even when traditional browser cookies are unavailable.
Importantly, this functionality is not limited to iOS; it is available on any device that supports Option 114.
iOS and Captive Portal Behavior
When an iOS device connects to a Wi-Fi network, it checks for unrestricted internet access. If the OS (operating system) detects redirection to a captive portal:
- It opens a Captive Portal Mini Browser (CPMB) — a lightweight browser window dedicated to authentication.
- The CPMB provides a seamless experience, but does not store persistent cookies. All cookies are deleted as soon as the window is closed.
This cookie limitation can be a challenge in environments , where cookie-based authentication tokens are used to identify returning users.
Cookie-Based Authentication
Once a user successfully authenticates through the captive portal, an authentication token is stored in a browser cookie. This token helps:
- Identify the user in subsequent sessions.
- Avoid repeated logins.
- Enforce consistent security policies.
However, because iOS CPMB does not retain cookies, the token is lost between sessions, and the user is forced to re-authenticate.
How CPI Helps with Device Recognition
To overcome this limitation, Cloudi-Fi leverages MAC address-based recognition using the CPI (Option 114) mechanism.
With no active authentication session in Cloudi-Fi
Here's how it works:
1. During DHCP, the client receives:
- An IP address.
- The Option 114 field containing a specific URL specific to that device and company:
https://guest-api-v1.cloudi-fi.net/cpi/ch/<companyHash>/location/<parentLocationId>/pool/<poolUuid>/mac/<deviceMac>/ip/<ipAddress>
2. Device request this URL and queries it to retrieve its "Wallguard" status — determining whether a captive portal is needed. Using the subnet ID, the API will identify the corresponding location. The Cloudi-Fi API responds with JSON data including:
- Whether the device is behind a captive portal ("captive": true)
- The exact location captive portal URL (https://login.cloudi-fi.net/start/ch/******/lh/******/sp/sp******)
- A venue information URL
- Optional session metadata
Note
- By embedding the MAC address in the URL, Cloudi-Fi can uniquely recognize the device, even when cookie information is not available.
- If the location cannot be determined, the system defaults to a redirect to http://3wi.fi/, initiating the captive portal.
With an active authentication session in Cloudi-Fi
Here's how it works:
1. During DHCP, the client receives:
- An IP address.
- The Option 114 field containing a specific URL specific to that device and company:
https://guest-api-v1.cloudi-fi.net/cpi/ch/<companyHash>/mac/<deviceMac>/subnet_id/<subnet_id>
2. Device request this URL and queries it to retrieve its "Wallguard" status — determining whether a captive portal is needed.
Using the subnet ID, the API will identify the corresponding location. The Cloudi-Fi API responds with JSON data including:
- Whether the device is behind a captive portal ("captive": false)
- A venue information URL
- Optional session metadata
Note
- By embedding the MAC address in the URL, Cloudi-Fi can uniquely recognize the device, even when cookie information is not available.
Key Benefits
| Feature | Benefit |
| Device-level recognition | MAC address allows for reliable session tracking even without cookies. |
| iOS compatibility | Works within iOS’s CPMB limitations by avoiding dependency on cookie persistence. |
| Fewer re-authentications | Users returning to the network can be recognized and handled accordingly. |
Replacing or Complementing the Transient Feature
Previously, to manage session continuity without persistent identifiers, Cloudi-Fi offered a "Transient" mode. While effective, it had certain limitations in complex environments like Zscaler ZIA or on restrictive platforms like iOS.
With CPI and MAC recognition:
- You now have a more robust, standards-based alternative.
- It allows for cross-session device recognition without requiring persistent cookies or storage access.
- Especially effective for guest devices, BYOD, or mobile-first environments.
Summary
Captive Portal Identification (DHCP Option 114) enables Cloudi-Fi to:
- Proactively notify devices about captive portals.
- Identify iOS devices reliably using their MAC addresses
This results in a smarter, smoother user experience—even in constrained environments—and enables more secure, consistent policy enforcement across sessions.