Skip to main content
English (UK)

Why your captive portal is not loading on iPhone: Fix Apple CNA errors

Troubleshoot and fix captive portal popup failures on iPhone and iOS. Learn how Apple CNA, iCloud Private Relay, and MAC randomisation break WiFi logins, and how to fix them.

By Tom HackettPublished
📖 10 min read1,516 words2 worked examples3 practice questions6 key definitions

Video overview

Listen to this guide

View podcast transcript
[Intro Music: Upbeat, modern electronic synth-pop with clean piano highlights, establishing a professional, tech-forward tone] **Host (Senior Consultant)**: Hello and welcome to the Purple Technical Briefing. I'm your host, and today we are diving deep into one of the most common—and frankly, most frustrating—issues facing network administrators, IT managers, and venue operations directors today. We've all been there. You've spent weeks planning, configuring, and deploying a state-of-the-art guest Wi-Fi network for your hotel, shopping mall, or stadium. You've got the latest access points, a robust controller, and a beautiful splash page ready to capture guest data and drive engagement. But then, the helpdesk tickets start rolling in. And they all say the exact same thing: "I've connected to the guest WiFi on my iPhone, but the login page won't load." To the guest, your Wi-Fi is simply broken. But to us, as network engineers and architects, we know there is a complex technical battle happening under the hood of iOS. Today, we're going to unpack exactly why your captive portal isn't loading on iPhones, how Apple's background detection logic works, and the step-by-step mitigation paths you can implement on your network this quarter. [Brief transitional musical swell] **Host**: Let's start with the technical deep-dive. Why does an iPhone connect to guest Wi-Fi but fail to show the login screen? To understand this, we have to look at Apple's **Captive Network Assistant**, or **CNA**. When an iPhone associates with an open SSID and receives an IP address via DHCP, it doesn't just wait for the user to open a browser. Instead, a background system daemon immediately fires off a plain HTTP GET request to a very specific URL: `http://captive.apple.com/hotspot-detect.html`. This background probe uses a unique system User-Agent called `CaptiveNetworkSupport`. The CNA daemon is looking for a very specific response. If Apple's servers return an HTTP status code **200 OK** with a body that says exactly the word "Success", iOS concludes that the network has unrestricted internet access. It quietly establishes Wi-Fi as the primary routing interface, and the user goes about their day. However, if your network gateway intercepts that HTTP request and returns anything else—like an HTTP 302 or 307 redirect, or a customised HTML page—iOS immediately recognises that it is behind a captive portal. It instantly launches the native **Websheet app**. This is that familiar slide-up modal sheet that displays your guest login page. Now, here is the first major engineering pitfall: **The Walled Garden**. Many network engineers make the mistake of whitelisting Apple's success domains, like `captive.apple.com`, in their pre-authentication Access Control Lists. They think, "Well, it's an Apple domain, I should let it through." But if you whitelist it, the background probe successfully reaches Apple's servers, receives the "Success" response, and iOS assumes there is no captive portal. The Websheet never triggers! Meanwhile, the user is blocked from accessing any other websites. So, rule number one: **Never whitelist captive.apple.com in your walled garden.** [Brief transitional sound effect] **Host**: But what about modern iOS privacy features? Even with a perfect walled garden, features like **iCloud Private Relay** and **Private MAC Addresses** are changing the game. Let's talk about iCloud Private Relay, introduced in iOS 15. This feature encrypts and routes Safari's DNS and HTTP traffic through a dual-hop proxy architecture. When a user with Private Relay active connects to your guest Wi-Fi, the background HTTP probe is encapsulated inside an encrypted tunnel. Because your network gateway cannot inspect or intercept this encrypted packet, it cannot inject the redirect. The probe fails silently, and the iPhone simply displays a "No Internet Connection" warning. No portal, no login, just friction. Fortunately, there is a programmatic network-level mitigation for this. Apple has designed Private Relay to respect network-level blocks. If your local DNS server returns an **NXDOMAIN** response for Apple's Private Relay domains—specifically `mask.icloud.com` and `mask-h2.icloud.com`—iOS recognises that the network is incompatible with Private Relay. It will immediately display a system prompt asking the user if they want to "Use Without Private Relay" for this network. The moment they tap that, the encrypted tunnel is bypassed, the HTTP probe is intercepted, and your captive portal loads perfectly. Next up is **Private MAC Addresses** and the new **Rotating MAC Addresses** in iOS 18. By default, iPhones randomise their MAC address for each SSID. In iOS 18, this address rotates periodically even while connected to the same network. If your wireless controller tracks authenticated guest sessions solely by MAC address, a sudden rotation will cause the gateway to treat the iPhone as a brand-new, unauthenticated device. The guest is abruptly disconnected and forced to log in again. To mitigate this, enterprise venues must move away from simple MAC-based tracking. Platforms like **Purple** solve this by dropping a secure, persistent cookie in the browser session, or better yet, by transitioning venues to **Passpoint**, also known as Hotspot 2.0. Passpoint uses secure 802.1X profiles to automatically and securely authenticate returning guests without ever showing a captive portal sheet. It's secure, it's seamless, and it completely bypasses the limitations of the CNA. [Brief transitional musical swell] **Host**: Now, let's address custom DNS profiles and local VPNs. Many technical users install custom DNS profiles like NextDNS or AdGuard that enforce encrypted DNS-over-HTTPS. Because these profiles bypass your local DHCP-assigned DNS servers, your gateway cannot spoof the DNS lookup for `captive.apple.com`. Similarly, "Always-On" VPN profiles will attempt to establish an encrypted tunnel the second an IP is assigned. If the VPN succeeds, it bypasses your redirect; if it is blocked, it deadlocks the connection. For these users, the ultimate manual fallback is the **neverssl.com** trick. If a guest is connected to your Wi-Fi but the portal won't load, tell them to open Safari and type `neverssl.com` into the address bar. Because this domain is strictly unencrypted HTTP, the gateway is guaranteed to intercept the port 80 traffic and force the redirect to load, bypassing any custom DNS or VPN interference. [Sound effect: Quick transition chime] **Host**: Let's run through a rapid-fire Q&A of the most common questions we get from venue support teams. *Question one: Why does my iPhone show 'No Internet Connection' in orange under the Wi-Fi name?* **Answer**: This means the iPhone completed the Wi-Fi association and got an IP address, but the background CNA probe failed to get a response from Apple's success servers and was not successfully redirected, often due to iCloud Private Relay or an active VPN. *Question two: Can we just disable the CNA mini-browser entirely on our network?* **Answer**: Yes, most enterprise Wireless LAN Controllers have a setting called 'CNA Bypass' or 'Captive Portal Bypass'. When enabled, the controller spoofs the Apple success probe, telling the iPhone it has full internet. This prevents the Websheet from popping up, but it relies on the user manually opening Safari to trigger the redirect, which can sometimes create even more user confusion. *Question three: What is the post-authentication probe issue?* **Answer**: After the guest logs in, the CNA Websheet runs a secondary probe to verify internet access. If your gateway redirects them to a landing page but continues to block Apple's success domains, the top-right button remains stuck on 'Cancel'. Clicking 'Cancel' disconnects them from the Wi-Fi. You must ensure Apple's success domains are fully accessible post-authentication. [Brief transitional musical swell] **Host**: To wrap up, let's look at the real-world business impact. Optimising your captive portal isn't just about technical elegance; it's about the bottom line. We recently worked with a luxury 5-star resort group that was experiencing a 35% failure rate in guest Wi-Fi connections, leading to over 450 front-desk complaints every single week. By restructuring their walled garden, blocking Private Relay domains at the DNS level to force local routing, and deploying **Purple's Guest WiFi** solution, they saw front-desk Wi-Fi tickets drop by **92%** in just 30 days. Their guest satisfaction scores soared, and they captured thousands of verified guest profiles. If you want to ensure your guest Wi-Fi network interacts flawlessly with Apple's Captive Network Assistant while maximising data capture and minimising support costs, head over to **purple.ai**. Our platform is engineered to handle all of these iOS-specific nuances out of the box. Thank you for listening to this Purple Technical Briefing. Implement these walled garden and DNS strategies this week, and watch your support tickets disappear. Until next time, keep your connections secure and your guest onboarding seamless. [Outro Music: Upbeat electronic synth-pop fades out slowly]

Part of our core series: Captive Portal Guide →

Interactive Network Tool

Apple iOS Captive Portal and CNA Diagnostic Advisor

Diagnose captive portal popup failures, white screens, SSL warnings, and iCloud Private Relay issues across iOS 14 to iOS 18 with controller-specific remediation scripts.

Critical

Apple CNA Probe Request Intercepted or Dropped Before HTTP 302

The Apple Captive Network Assistant (CNA) daemon failed to detect network captivity because probe HTTP GET requests to captive.apple.com/hotspot-detect.html were silently dropped or returned an unhandled status.

Detailed Protocol Breakdown (IOS_18)

Upon associating with an unauthenticated SSID, iOS issues an HTTP GET request to http://captive.apple.com/hotspot-detect.html expecting the string "<HTML><HEAD><TITLE>Success</TITLE></HEAD><BODY>Success</BODY></HTML>". If the network drops TCP port 80 or hijacks DNS without returning an immediate HTTP 302 redirect, iOS assumes internet connectivity is offline and suppresses the slide-over CNA sheet.

Required Apple CNA Probe Walled Garden Whitelist:

captive.apple.comwww.airport.usappleiphonecell.com*.apple.com*.purple.ai*.purplewifi.net

Eliminate Captive Portal Login Failures with Passpoint & Purple Cloud

Provide instant, seamless onboarding for iOS and Android guest WiFi without CNA popup errors or manual browser logins.

Executive Summary

Captive portal login failure on iOS devices (iPhone and iPad) is one of the leading causes of guest WiFi connection complaints in hospitality, retail, healthcare, and enterprise environments. When an iOS device associates with an open or web-authenticated wireless network, Apple's Captive Network Assistant (CNA) daemon initiates a series of background HTTP probes. If these probes are blocked, misrouted, or improperly intercepted, the captive portal splash page fails to load, leaving the user with no internet access and no obvious way to log in.

This technical guide details the underlying mechanics of Apple CNA detection, analyzes key iOS privacy features - including iCloud Private Relay, Private WiFi Addresses (MAC randomisation), and Encrypted DNS - and provides step-by-step mitigation strategies for network engineers and venue operators.

Struggling with Guest WiFi Drop-off on iOS?

Purple's cloud-managed Guest WiFi platform handles Apple CNA probes, iCloud Private Relay, and MAC randomisation automatically - delivering seamless captive portal onboarding across all iOS and Android devices.

Explore Purple Guest WiFi →

Technical Deep-Dive

Apple's Detection Logic and Probing Mechanism

When an iPhone connects to a wireless access point, the iOS networking stack immediately dispatches a daemon called captivenetworkd. This daemon issues plain HTTP GET requests to predefined Apple verification URLs, including:

  • http://captive.apple.com/hotspot-detect.html
  • http://www.apple.com/library/test/success.html
  • http://gsp1.apple.com/pep/gcc
+-------------------+       HTTP GET captive.apple.com       +----------------------+
|   iPhone (iOS)    | -------------------------------------> |  Network Controller  |
+-------------------+                                        +----------------------+
          |                                                             |
          | <--- HTTP 302 Redirect (https://portal.purple.ai) ---------+
          |
          v
[ Launch CNA Websheet ] ---> [ Render Purple Captive Portal ]

The daemon evaluates the HTTP response status and body:

  1. Success Response (HTTP 200 with <HTML><HEAD><TITLE>Success</TITLE></HEAD><BODY>Success</BODY></HTML>): The operating system concludes that the network provides unrestricted internet access. No splash page is displayed.
  2. Redirect Response (HTTP 302 / 307): The network gateway intercepts the Port 80 HTTP request and redirects the client to the captive portal URL. iOS recognizes the redirection and launches the CNA Websheet (a specialized modal browser window).
  3. Connection Timeout or Reset: If the gateway drops Port 80 packets or fails to answer DNS queries, the probe times out. iOS displays a "No Internet Connection" warning under the SSID name in Settings, but fails to display the login page.

Post-Authentication Probing (The "Done" Button Challenge)

After a user submits their credentials or accepts the terms of service on the splash page, the wireless LAN controller (WLC) updates the client ACL state to "authenticated". The CNA daemon immediately issues a follow-up HTTP probe to captive.apple.com.

If the second probe returns HTTP 200 "Success", the top-right button on the CNA Websheet changes from "Cancel" to "Done". If the network fails to allow out-of-band HTTP access immediately after authentication, the button remains stuck on "Cancel", and tapping it may disconnect the device from the WiFi network entirely.

iOS-Specific Interference Factors

1. iCloud Private Relay

Introduced in iOS 15, iCloud Private Relay is an Apple service designed to protect web browsing privacy. When enabled, Safari and unencrypted HTTP traffic are encrypted and routed through two separate Internet relays:

[ iPhone ] === Encrypted QUIC/TLS ===> [ Apple Ingress Proxy ] ---> [ Egress Proxy ] ---> [ Web Target ]
  • The Problem: Private Relay encrypts DNS requests via Oblivious DNS-over-HTTPS (ODoH) and tunnels HTTP traffic via QUIC (UDP Port 443). Because local gateway routers cannot inspect or intercept encrypted QUIC traffic, they cannot inject the standard HTTP 302 redirect.
  • Impact: The initial HTTP probe to captive.apple.com is tunneled away from the local gateway, resulting in connection timeouts and missing splash pages.

2. Private MAC Addresses and Rotating Identifiers

Beginning with iOS 14 and expanded in iOS 18, Apple enables Private WiFi Address by default. Rather than using the device's permanent hardware MAC address, iOS generates a randomized MAC address for each SSID.

  • The Problem: On networks using MAC-based session authorization (where authenticated users are allowed 24 hours of access based on MAC address), MAC rotation causes the network gateway to view returning devices as new, unauthenticated clients.
  • Impact: Users are repeatedly presented with the captive portal splash page, leading to poor user experience and front-desk support tickets.

3. Encrypted DNS Profiles (DoH / DoT)

Users with custom iOS configuration profiles (such as NextDNS, Cloudflare 1.1.1.1, or corporate MDM DNS settings) transmit all DNS queries over encrypted HTTPS (DoH) or TLS (DoT) directly to external resolvers.

  • The Problem: The local network DNS server cannot intercept or spoof DNS requests for captive.apple.com or non-existent domains.
  • Impact: The initial DNS resolution bypasses the local controller entirely, preventing the portal redirect from triggering.

Got questions about your specific setup?

Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.

Implementation and Mitigation Guide

Walled Garden (Pre-Authentication ACL) Design

To ensure reliable captive portal rendering on iOS, network engineers must configure the pre-authentication Walled Garden Access Control List (ACL) with precision:

Rule Type Destination / Domain Purpose
Allow *.purple.ai, *.purpleshield.com Allows unauthenticated clients to reach Purple portal infrastructure and assets.
Intercept HTTP (TCP Port 80) to any destination Intercepts plain HTTP web traffic to trigger the 302 redirect.
Block / NXDOMAIN mask.icloud.com, mask-h2.icloud.com Returns NXDOMAIN to signal that Private Relay is unavailable on local network.
DO NOT Whitelist captive.apple.com, www.apple.com Must NOT be whitelisted. Whitelisting causes probes to succeed without launching the portal.

Step-by-Step WLC Configuration (Cisco Catalyst / Meraki Example)

  1. Configure DNS Interception: Set the DHCP server to assign the gateway IP address as the primary DNS server for unauthenticated clients.
  2. Configure Private Relay Signaling: Add a DNS rewrite rule on local DNS servers:
    mask.icloud.com      IN A 0.0.0.0 (or NXDOMAIN)
mask-h2.icloud.com   IN A 0.0.0.0 (or NXDOMAIN)
    When iOS receives NXDOMAIN for these hostnames, it presents the system prompt: "This network blocks iCloud Private Relay. Do you want to use this network without Private Relay?" Tapping Use Without Private Relay restores standard portal redirection.
  3. Configure Session Timeout: Set gateway session timeout based on IP/MAC pairs or drop persistent authorization cookies.

Best Practices and Industry Standards

Managing guest wireless onboarding at scale requires adherence to modern networking standards:

  • Transition to WPA3-Personal (OWE): Legacy guest portals run on open, unencrypted SSIDs. Enterprise venues should adopt Opportunistic Wireless Encryption (OWE) (IEEE 802.11aq) to deliver individualized encryption without passwords.
  • PCI DSS and GDPR Compliance: Guest portals must isolate guest traffic from PCI DSS payment networks. When capturing contact details, portals must present explicit, unbundled GDPR consent checkboxes - managed easily via a WiFi Analytics platform.
  • Deploy Passpoint (Hotspot 2.0): To eliminate captive portal friction entirely, venues can deploy Passpoint (Hotspot 2.0). Passpoint uses cellular-style authentication to connect iOS devices securely and automatically via a pre-installed profile, bypassing the CNA daemon entirely.

Troubleshooting and Risk Mitigation

End-User Self-Remediation Path

  1. Disable iCloud Private Relay for the Network: Open Settings > WiFi, tap the (i) icon next to the network name, and toggle off Limit IP Address Tracking.
  2. Disable Private WiFi Address: In the same network settings menu, toggle off Private WiFi Address if MAC-based access is required.
  3. Force Portal Redirection via Safari: Open Safari and enter the plain HTTP address: http://neverssl.com Because neverssl.com does not use HTTPS, the local router will reliably intercept the request and load the portal.

Network Engineer Diagnostic Path

                  [ iPhone connects to guest SSID ]
                                  |
                                  v
                        [ DHCP IP assigned? ]
                        /                   \
                     (No)                   (Yes)
                      /                       \
        [ Check DHCP Pool ]             [ Resolves captive.apple.com? ]
                                        /                             \
                                     (No)                             (Yes)
                                      /                                 \
                         [ Check DNS ACL ]                   [ Is Apple Whitelisted? ]
                                                             /                       \
                                                          (Yes)                      (No)
                                                           /                           \
                                              [ REMOVE from Walled Garden ]    [ Port 80 Redirects? ]
                                                                               /                   \
                                                                            (No)                   (Yes)
                                                                             /                       \
                                                                 [ Fix WLC Redirect ]    [ CNA Websheet Loads ]

ROI and Business Impact

Optimising the iOS guest WiFi onboarding experience has a direct, measurable impact on venue operations and business metrics.

Hospitality Case Study: Five-Star Resort Group

  • Challenge: A luxury hotel group with 12 properties suffered a guest WiFi connection failure rate of 35%, driving more than 450 front-desk complaints per week.
  • Implementation: The IT team restructured its walled garden, disabled MAC-based session tracking, and deployed Purple's Guest WiFi solution with optimised CNA handling.
  • Results: Front-desk WiFi-related complaints fell by 92% within 30 days. Customer satisfaction (CSAT) scores rose by 18 points, and the venue captured 40,000 newly verified email addresses in the first quarter.

Retail Case Study: National Shopping Centre Operator

  • Challenge: A retail operator with 45 shopping centres struggled to drive visitor engagement because iCloud Private Relay prevented the captive portal from loading on 40% of iOS devices.
  • Implementation: Implemented network-level Private Relay blocking (returning NXDOMAIN for Apple's relay domains to force local routing) and deployed WiFi Analytics .
  • Results: Portal completion rates jumped from 58% to 94%. The marketing team monetised the recovered portal inventory with localised retail media campaigns, generating an additional $120,000 in advertising revenue per quarter.

For networking teams deploying enterprise guest wireless, these resources provide deeper technical context:

Purple's Guest WiFi platform serves hospitality , retail , healthcare and transport venues worldwide, delivering CNA-optimised guest login experiences at scale.

Key Definitions

Apple Captive Network Assistant (CNA)

An iOS and macOS operating system daemon that probes for internet connectivity and automatically launches a restricted WebKit modal (WebSheet) when a captive portal is detected.

Controls whether the login splash page appears automatically on iPhones when connecting to guest WiFi.

Canary probe URL

A lightweight HTTP endpoint (such as http://captive.apple.com/hotspot-detect.html) requested by client operating systems to verify unrestricted internet reachability.

If the probe response is modified or redirected, the operating system triggers its captive portal handler.

RFC 8908 Captive Portal API

An IETF standard protocol that provides an API endpoint where devices can query network captivity status, venue terms, and remaining session time via JSON.

Replaces legacy HTTP hijacking with structured, cryptographically secure captive network detection.

DHCP Option 114 (Captive-Portal)

A DHCP option (RFC 8910) that passes the URI of the RFC 8908 Captive Portal API to the client device during initial Layer 3 address assignment.

Signals captivity to iOS 14+ immediately during IP acquisition, bypassing DNS tampering.

iCloud Private Relay

An Apple privacy service that routes Safari traffic and unencrypted DNS through a dual-hop encrypted proxy architecture.

Can mask pre-auth DNS queries unless the local network issues an explicit network impairment signal (NXDOMAIN).

Private WiFi address (MAC randomisation)

A privacy feature in iOS 14+ that generates a unique randomised MAC address per SSID to prevent cross-venue physical tracking.

Can desynchronise RADIUS accounting sessions if MAC addresses rotate mid-session or during re-authentication.

Worked Examples

A luxury hotel deploying Cisco Catalyst 9800 WLCs finds that guest iPhone users never receive the captive portal splash screen when connecting to the open Guest WiFi SSID. Android and Windows laptops load the portal immediately. How should the network team diagnose and fix the Apple CNA detection issue?

  1. Inspect Pre-Auth Redirect ACL: Verify that the Cisco 9800 redirect ACL denies (bypasses) UDP 53 DNS and permits TCP 80 HTTP to trigger redirection. 2. Check Apple Probe Whitelist: Ensure captive.apple.com is NOT whitelisted in the pre-auth walled garden before redirection; whitelisting it causes iOS to think internet is open and suppress the portal. 3. Verify HTTP 302 vs 307: Configure the WLC webauth parameter map to return an HTTP 302 Found redirect with the portal FQDN. 4. Disable HTTPS Interception: Ensure port 443 HTTPS traffic is dropped or rejected rather than hijacked with an untrusted certificate. 5. Deploy DHCP Option 114: Add option 114 ascii https://app.purplewifi.net/api/v1/capport to the guest DHCP pool for native iOS 14-18 detection.
Examiner's Commentary: Apple devices rely on a strict match for the Success token from captive.apple.com. If the probe domain is prematurely permitted through the walled garden, iOS falsely assumes open internet and will never trigger the WebSheet.

A stadium network administrator observes that iOS 17 and iOS 18 users experience an infinite login loop: the CNA sheet appears, the user accepts terms and clicks Connect, the modal closes, but 30 seconds later the modal re-opens asking for login again. What is the root cause and remediation?

  1. RADIUS Session Tracking: On iOS 17/18, Private Wi-Fi Addresses use rotating MAC addresses if configured, or the device may renegotiate DHCP upon modal exit. 2. RADIUS CoA Configuration: Verify that the controller processes RFC 3576 RADIUS Change of Authorization (CoA) Disconnect on UDP port 3799 so the pre-auth ACL is removed immediately upon authentication. 3. Session Timeout & Grace Period: Increase the MAC authentication bypass (MAB) cache timeout to 1440 minutes (24 hours) with a 15-minute lease grace window. 4. Walled Garden OAuth Assets: Verify all OAuth endpoints (Google, Apple, Microsoft) and fonts/stylesheets are in the walled garden so the session finishes loading completely before closing the WebSheet.
Examiner's Commentary: Infinite redirect loops typically stem from RADIUS CoA delays where the controller has not yet updated the client state from pre-auth to post-auth when iOS sends its post-login verification probe.

Practice Questions

Q1. Why does attempting to redirect HTTPS (port 443) traffic cause captive portal errors on iOS devices rather than opening the splash page?

Hint: Consider how TLS encryption, certificate verification, and HSTS protect web traffic.

View model answer

HTTPS establishes an end-to-end encrypted TLS tunnel between the client browser and the destination web server. When a wireless gateway attempts to intercept port 443 and serve a redirect, the SSL/TLS certificate provided by the gateway does not match the requested hostname (e.g. google.com or apple.com). iOS enforces HTTP Strict Transport Security (HSTS), causing Safari and WebKit to abort the connection with a severe security warning rather than following the redirect.

Q2. How should an enterprise guest network handle iCloud Private Relay to ensure smooth captive portal redirection on iOS devices?

Hint: Review Apple official network guidance regarding mask.icloud.com DNS responses.

View model answer

Network administrators should configure their local recursive DNS servers to return an NXDOMAIN response (or a DNS resolution failure) for the domain names mask.icloud.com and mask-h2.icloud.com. When iOS receives an NXDOMAIN response for these canary domains, it displays a system alert informing the user that the network does not support Private Relay and cleanly falls back to standard DNS and HTTP probe handling.

Q3. What is the advantage of deploying RFC 8908 Captive Portal API over traditional DNS and HTTP hijacking techniques?

Hint: Think about protocol clarity, Layer 3 signaling, and user experience.

View model answer

RFC 8908 provides a standardized JSON REST API communicated via DHCP Option 114 or IPv6 Router Advertisements. Instead of intercepting user web traffic, the client OS queries the API directly over HTTPS to learn if the network is captive, obtain the portal login URL, inspect remaining quota, and receive a venue-branded notification. This eliminates SSL certificate warnings, supports password managers, and preserves browser security integrity.

Frequently asked questions

Why is my captive portal not popping up on iPhone?

Captive portals fail to pop up on iPhones when the Apple Captive Network Assistant (CNA) cannot complete its probe to http://captive.apple.com/hotspot-detect.html. Common causes include: 1) Pre-authentication firewalls blocking UDP port 53 DNS; 2) The network prematurely whitelisting captive.apple.com in the walled garden; 3) Gateways attempting HTTPS interception instead of HTTP 302 redirection; or 4) iCloud Private Relay interfering with DNS resolution.

How do I force the WiFi login screen to appear on iOS?

To manually trigger the captive portal on iPhone: 1) Open Safari and navigate to a plaintext HTTP URL such as http://captive.apple.com, http://neverssl.com, or http://1.1.1.1; 2) Go to Settings > Wi-Fi, tap the info (i) icon next to the network, and ensure Auto-Join and Auto-Login are toggled ON; 3) Turn Wi-Fi off and back on to trigger the CNA probe daemon.

What domains must be in the walled garden for Apple devices?

To support Apple iOS and macOS captive portal detection and assets, whitelist: captive.apple.com, www.airport.us, appleiphonecell.com, *.apple.com, *.purple.ai, *.purplewifi.net, and any third-party OAuth provider domains (e.g. accounts.google.com) or CDN assets used on the splash page.

How does RFC 8908 solve iOS captive portal issues?

RFC 8908 (Captive Portal API) and RFC 8910 (DHCP Option 114) pass the captive portal URL directly to iOS during the DHCP IP lease negotiation. This allows iOS 14+ to recognize network captivity instantly at Layer 3 without relying on fragile HTTP redirection or DNS hijacking.

How does MAC address randomisation affect captive portal authentication?

iOS Private Wi-Fi Addresses use unique MAC addresses per SSID. If the device rotates its MAC address or if session caching is tied strictly to physical MAC addresses without RADIUS accounting grace periods, the user may be forced to re-authenticate repeatedly. Configuring a 24-hour lease grace period and deploying Passpoint (Hotspot 2.0) resolves this issue.

Sources

  1. Apple Developer Documentation - Captive Network Architecture and CNA
  2. Apple Support - Prepare Your Network for iCloud Private Relay
  3. IETF RFC 8908 - Captive Portal API Specification
  4. IETF RFC 8910 - Captive-Portal Identification in DHCP and Router Advertisements
  5. Wireless Broadband Alliance (WBA) - Captive Portal Standards and Best Practices
  6. Purple - Captive Portal Architecture & Troubleshooting Guide
  7. Purple - MAC Address Randomisation Impact Guide

Continue reading in this series

Ubiquiti UniFi guest portal not redirecting: causes and fixes

This guide isolates a UniFi guest portal redirect failure by following the guest state, redirect, pre-authorisation route and controller authorisation in sequence. It gives venue IT teams a sourced method to address guest-network versus Hotspot confusion, external portal hand-offs, current UniFi OS account requirements and DNS isolation testing.

Read the guide →

Cisco Meraki splash page not working: a troubleshooting flowchart

This practical day-two guide isolates where a Cisco Meraki splash flow has failed: client authorisation, HTTP redirect initiation, walled-garden reachability or RADIUS sign-on. It gives venue IT teams a controlled evidence path, so they can restore Guest WiFi without making broad changes to a live estate.

Read the guide →

Enterprise Guest WiFi Setup Guide: VLAN Segmentation, Security, and Captive Portals

This technical guide shows IT teams how to set up Guest WiFi as a controlled internet-access service, using VLAN segmentation, firewall policy and a captive portal. It also explains how Purple's registration forms and onboarding controls support a proportionate visitor experience without weakening the boundary around staff, payment and operational systems.

Read the guide →

Got questions about your specific setup?

Our team works with venue operators, IT managers, and network engineers across 80,000 venues. Book a 20-minute call and we will show you how others like you solved it.