Captive Portal: Detection, API and Wi-Fi Login
A captive portal limits a device’s access to a network until it meets an operator’s requirements. Follow the standards-based discovery and status flow, and learn what a packet trace can actually prove.
Updated · Editorial approach and simulation limits
A captive portal is an access state, not a Wi-Fi password
Joining an access point, receiving an IP configuration and gaining unrestricted Internet access are separate events. A device can associate with Wi-Fi and receive an address while an enforcement device still limits which destinations it can reach. The portal is the user-facing part of that policy; it is not itself the wireless association protocol or the DHCP lease.
The Captive Portal Architecture in RFC 8952 describes distinct roles: the client device, a provisioning service that supplies the portal API URI, an API server that reports session state, a user portal, and an enforcement device that allows or blocks traffic. One product may implement several roles, but separating them makes a trace easier to reason about.
This distinction answers a common support question: a phone can show connected to Wi-Fi and still report no Internet. The link is up, but the access policy has not yet moved the device into an unrestricted state.
RFC 8910: how a device learns where to ask
The standards-based discovery path starts during network provisioning. RFC 8910 defines the Captive-Portal option for DHCPv4, DHCPv6 and IPv6 Router Advertisements. Its value is a URI for the Captive Portal API, not a URL that must be opened as the login page. The option code for DHCPv4 is 114.
That URI gives a client an explicit endpoint to query instead of requiring every device to infer captivity by sending a test request and noticing that its response changed. Networks can provide the URI through more than one provisioning method; operators are advised to keep those values consistent so IPv4-only, IPv6-only and dual-stack clients do not learn different portal endpoints.
The option is a discovery mechanism, not proof that the portal is reachable or that the user has authenticated. A client still has to contact the provisioned endpoint, validate its HTTPS identity, interpret the response and, if necessary, show the user a separate portal page.
RFC 8908: what the Captive Portal API reports
RFC 8908 defines the HTTP API used after discovery. A client sends an HTTPS GET request to the provisioned URI and asks for the application/captive+json media type. The response must include a captive boolean. A true value means the client has not met the network’s conditions for general access; false means the API reports that the client is no longer captive.
Optional fields can describe the user-facing portal URL and session limits such as remaining time or bytes. These values describe the session known to the API; they do not encode a general-purpose authentication protocol. The API and the user portal are separate endpoints with different jobs.
Because the API is fetched over TLS, the client can authenticate the API server using the hostname supplied by the network. RFC 8908 says the client must not continue the API interaction if it cannot validate that certificate. The API response is JSON, but a packet capture taken between the client and server normally cannot read that JSON unless the observer has authorized endpoint access or the TLS session keys.
A complete public Wi-Fi login, step by step
First, the device associates with the access point and obtains network configuration. That may include an IPv4 lease, IPv6 configuration, or both. During this stage it may also learn the Captive Portal API URI from DHCP or a Router Advertisement.
Next, the device queries the API over HTTPS. If the response says captive is true, the device can present the user-portal URL. The user may accept an acceptable-use policy, enter credentials, pay for access or complete another venue-specific step. Those business rules are not standardized by the API.
The portal service then causes the enforcement system to update the client’s access policy. The device can query the API again and receive captive false. The enforcement device and API should agree about the client identity and state; otherwise the interface may show a successful login while traffic remains blocked.
This sequence is a useful troubleshooting model, not a guarantee that every phone and venue uses CAPPORT. The architecture explicitly allows incremental deployment, so older detection probes and redirects remain in use.
Why older portals redirect traffic, and why HTTPS makes that awkward
Many deployed portals predate the discovery and API standards. They may test connectivity with an HTTP request to a known endpoint and redirect an unexpected response to a login page. This can work for cleartext HTTP, but redirecting an HTTPS request would require the network to interfere with a TLS connection whose certificate belongs to another host.
RFC 8952 explains that forging DNS or HTTP responses and acting as a man-in-the-middle are problems the newer architecture is designed to avoid. A secure API lets a device learn its state without changing an unrelated website’s response. Legacy interception can still be present for compatibility, so seeing a redirect does not tell you which discovery mechanism the device used.
A captive portal also does not decrypt all traffic after login. Once the access condition is met, ordinary HTTPS still protects application content between the client and its destination.
What to inspect in a packet trace
Start with provisioning. Look for DHCP or Router Advertisement messages and check whether a Captive-Portal URI was advertised. Confirm which interface and address family the client is using; a portal URI learned on IPv4 may not be the URI used for an IPv6-only path.
Then find the client’s connection to the advertised API host. Without TLS session keys, a network-side trace can usually show the destination, timing, handshake and encrypted record sizes, but it cannot establish the captive boolean or read a user-portal URL inside the encrypted response. At an authorized endpoint, application logs or a decrypted trace can expose those fields.
Finally, correlate the user’s portal action with a subsequent API response and the enforcement device’s policy update. A successful web form submission alone does not prove that the enforcement system changed the client’s state. Compare timestamps, client identifiers and address assignments while accounting for address changes or multiple interfaces.
Captive portal loops: separate discovery, API and enforcement failures
If the login page never appears, check whether the client received a portal URI, whether the API hostname resolves on the restricted network, whether the TLS certificate validates, and whether the API response is valid application/captive+json. A blocked certificate-status or time service can also prevent secure validation in some deployments.
If the login succeeds but the device remains captive, compare the API state before and after the user action and verify that the portal and enforcement device identify the same session. Expired leases, a changed address, inconsistent IPv4 and IPv6 provisioning, or a stale API cache can make the user interface and network policy disagree.
If only one device fails, avoid assuming that the operating system is at fault. Devices can differ in supported discovery mechanisms, network policy, interface selection and connectivity checks. Capture the actual DHCP/RA and API path for the affected device before comparing it with another client.
Privacy and operational boundaries
The API may use information that identifies a particular client or session so it can return the right state. RFC 8952 warns that stable identifiers can create tracking risks. Portal operators should limit collection and retention, protect identifiers in transit and avoid putting reusable credentials in URLs.
Protocol Explorer shows a scripted teaching sequence. Its timestamps and example addresses are illustrative; it does not join a Wi-Fi network, query a captive portal, or inspect a visitor’s traffic. Use the cited RFCs for requirements and an authorized capture or device log for a real incident.
Explore Captive Portal interactively
Open the matching lesson to follow the exchange packet by packet. This is a scripted learning model with illustrative timing, not a capture of your network. The overview is free; the full lesson is included with the one-time Pro pass.
Standards and primary sources
Use these specifications for authoritative protocol requirements. The lesson summarizes selected behaviors and does not replace the source documents.
Related protocol lessons
Browse all security and access protocols ·