Cómo construir un Captive Portal: Una guía para desarrolladores

Una guía técnica definitiva para arquitectos de TI y gestores de red sobre la construcción y despliegue de Captive Portals. Esta guía cubre los protocolos subyacentes, los flujos de autenticación, las arquitecturas de código abierto y un marco para decidir cuándo construir frente a cuándo adquirir una plataforma gestionada empresarial.

📖 6 min de lectura📝 1,311 palabras🔧 2 ejemplos❓ 3 preguntas📚 8 términos clave

🎧 Escuchar esta guía

Ver transcripción

How to Build a Captive Portal: A Developer's Guide
A Purple WiFi Intelligence Podcast — Approximately 10 Minutes

[INTRODUCTION & CONTEXT — 1 minute]

Welcome back. I'm speaking today as a senior solutions architect, and if you're listening to this, you're probably staring down a requirement to deploy guest WiFi at scale — a hotel group, a retail estate, a stadium, or perhaps a public-sector network — and someone has asked you: can we build this ourselves, or do we buy a platform?

That's exactly the question we're going to answer today. We'll cover what a captive portal actually does under the hood, walk through the open-source options available to you right now, explain the authentication flows and API integration patterns you need to understand, and give you a clear framework for deciding when to build versus when to buy. By the end of this, you'll have enough to brief your team and make a defensible decision this quarter.

Let's get into it.

[TECHNICAL DEEP-DIVE — 5 minutes]

First, the fundamentals. A captive portal is a network access control mechanism that intercepts unauthenticated HTTP or HTTPS traffic from a connected device and redirects it to a web-based authentication page — what most users know as the WiFi login splash screen. The underlying mechanics rely on a combination of DNS hijacking, HTTP 302 redirects, and firewall rules that block all outbound traffic until the authentication handshake completes.

When a device connects to your SSID, it typically sends an HTTP probe request — a lightweight check to see whether the network is open or gated. Your access point or gateway intercepts that probe and returns a redirect to your splash page URL. The user completes whatever authentication method you've configured — email capture, social login, SMS OTP, or a voucher code — and your portal then signals the network controller to open the firewall rule for that device's MAC address or IP. That's the core loop.

Now, the standards that govern this are worth knowing. The IEEE 802.11 standard covers the wireless layer, but the captive portal detection and redirection behaviour is largely governed by RFC 7710 and the CAPPORT working group's RFC 8908 and RFC 8910, which define the Captive Portal API — a structured, machine-readable way for devices to discover and interact with captive portals. If you're building from scratch in 2024, you should be implementing the CAPPORT API rather than relying purely on legacy HTTP redirect tricks, because modern iOS and Android devices handle it more gracefully and you'll see fewer authentication failures.

On the authentication side, you have several patterns to choose from. The simplest is a click-through or terms-of-service acceptance — no credentials required, just a button press. This is compliant with basic regulatory requirements in many jurisdictions but gives you no guest identity data. One step up is email gating — the guest enters their email address, you validate it optionally via a confirmation link, and you capture a marketing consent record. This is where GDPR becomes directly relevant: you need a lawful basis for processing that data, a clear consent mechanism, and a documented retention policy. If you're operating in the UK or EU, this is non-negotiable.

For higher-security environments — corporate guest networks, healthcare facilities, or any deployment that touches PCI DSS scope — you'll want IEEE 802.1X port-based authentication with a RADIUS back-end. The flow here is: device associates with the SSID, the access point acts as a RADIUS client and forwards the authentication request to your RADIUS server — FreeRADIUS is the most widely deployed open-source option — the RADIUS server validates credentials against your directory, and returns an Access-Accept or Access-Reject. You can layer EAP methods on top of this: EAP-TLS for certificate-based auth, PEAP for username and password with a server-side certificate. WPA3-Enterprise with 192-bit mode is the current gold standard for high-security deployments.

Now, let's talk about the open-source landscape, because there are real options here. pfSense with its built-in captive portal module is a solid starting point for single-site deployments — it handles RADIUS integration, per-user bandwidth throttling, and basic session management. OpenWRT with Nodogsplash is lightweight and works well on embedded hardware, but it has limited social authentication support and minimal GDPR tooling. Coova-Chilli is a more mature option — it implements the WISPr protocol, supports RADIUS, and can be extended with plugins for social login. PacketFence is the most feature-complete open-source network access control platform — it handles 802.1X, social auth, and has reasonable compliance tooling, though the operational overhead is significant.

The honest assessment: open-source captive portal software gives you the authentication plumbing, but it leaves you to build everything else — the splash page UI, the data capture forms, the consent management, the analytics pipeline, the CRM integrations, and the ongoing compliance posture. For a single venue with a small IT team, that's a manageable project. For a 50-site retail estate or a hotel group with 200 properties, the total cost of ownership of a self-built stack almost always exceeds a managed platform within 18 months.

That's where platforms like Purple come in. Purple's guest WiFi platform sits on top of your existing network infrastructure — it's hardware-agnostic, so it works with Cisco Meraki, Aruba, Ruckus, Ubiquiti, and most enterprise access point vendors. It handles the splash page, the authentication flows, the consent management, the data capture, and then feeds that data into a WiFi analytics layer that gives you footfall heatmaps, dwell time analysis, repeat visitor rates, and direct integrations with marketing automation platforms. For a hospitality operator, that means connecting guest WiFi data to your PMS and CRM. For a retailer, it means correlating footfall data with sales transactions.

[IMPLEMENTATION RECOMMENDATIONS & PITFALLS — 2 minutes]

Let me give you the implementation framework I use when advising clients on this decision.

Start with your compliance requirements. If you're in scope for PCI DSS — and any venue that processes card payments on the same network as guest WiFi potentially is — you need network segmentation as a baseline, and your captive portal needs to sit on an isolated VLAN. GDPR compliance requires consent records with timestamps, a clear privacy notice linked from the splash page, and a documented data retention schedule. Don't bolt these on after the fact.

Second, think about your authentication method relative to your audience. A stadium with 60,000 concurrent connections needs a lightweight click-through or social login — anything that adds friction at that scale will result in support calls and abandoned connections. A conference centre with 500 delegates who need to be individually tracked for compliance purposes needs email gating with verification. A hospital guest network needs 802.1X with certificate-based auth and strict VLAN segmentation from clinical systems.

Third, plan your API integration points before you write a line of code. If you're building custom, define your webhook endpoints for authentication events, your data schema for guest records, and your integration contracts with downstream systems — CRM, marketing automation, analytics — before you start on the portal UI. Retrofitting integrations is where self-build projects typically go over budget.

The most common failure modes I see: DNS rebinding attacks on poorly configured portals — always validate redirect URLs server-side. MAC address spoofing — don't rely on MAC as your sole session identifier. HTTPS interception issues — modern browsers and apps increasingly refuse to follow captive portal redirects on HTTPS connections, which is why implementing the CAPPORT API is important. And finally, bandwidth management — if you don't implement per-device rate limiting, a single guest running a software update can degrade the experience for everyone else on the network.

[RAPID-FIRE Q&A — 1 minute]

Can I use a Raspberry Pi as a captive portal gateway? Yes, with OpenWRT or Coova-Chilli for a single small venue — but don't put it in production at scale.

Do I need a RADIUS server for social login? No — social OAuth flows bypass RADIUS entirely. You need RADIUS for 802.1X certificate or credential-based authentication.

Is WPA3 mandatory for new deployments? Not legally mandatory, but it should be your default for any new infrastructure procurement. WPA2 is still widely supported but has known vulnerabilities.

How do I handle Apple's Captive Network Assistant? Implement the CAPPORT API and ensure your splash page loads cleanly within the CNA browser window — avoid JavaScript redirects that the CNA can't follow.

[SUMMARY & NEXT STEPS — 1 minute]

To summarise: building a captive portal from scratch is entirely feasible with open-source tools like pfSense, Coova-Chilli, or PacketFence — but the build cost is only part of the equation. The ongoing cost of maintaining compliance, integrating with marketing systems, and scaling across multiple sites is where self-build projects typically struggle.

For most enterprise venue operators, the right answer is a managed platform that handles the authentication plumbing, the compliance layer, and the analytics pipeline — and exposes a clean API for custom integrations where you need them.

If you want to go deeper on the technical architecture, there's a full written guide linked in the show notes — it covers the CAPPORT API implementation, RADIUS configuration, and GDPR consent flow in detail. And if you're evaluating Purple's platform, the guest WiFi and analytics documentation is a good starting point for understanding what the integration looks like in practice.

Thanks for listening. Until next time.

Resumen Ejecutivo

Para arquitectos de red empresariales y directores de TI, desplegar un Captive Portal rara vez es solo un ejercicio de red; es una intersección crítica de seguridad de red, cumplimiento normativo e inteligencia de negocio. Ya sea que gestione una cartera de 200 propiedades de Hostelería , una extensa propiedad Minorista o un estadio de alta densidad, la decisión de construir un Captive Portal personalizado o desplegar una plataforma gestionada tiene profundas implicaciones para el coste total de propiedad (TCO) y el riesgo operativo.

Esta guía proporciona una inmersión técnica profunda y neutral en la arquitectura de los Captive Portals. Exploraremos la mecánica subyacente de redirección HTTP, la moderna Captive Portal API (RFC 8908), los flujos de autenticación RADIUS 802.1X y las principales opciones de código abierto. Fundamentalmente, proporcionamos un marco para evaluar cuándo tiene sentido una pila de código abierto autoconstruida y cuándo la sobrecarga de cumplimiento e integración requiere una plataforma empresarial como la solución Guest WiFi de Purple.

Escuche nuestro resumen de audio complementario para una visión estratégica:

Análisis Técnico Detallado: Cómo Funcionan los Captive Portals

Antes de evaluar las opciones de software, es esencial comprender la mecánica fundamental de la red. Un Captive Portal es esencialmente un mecanismo de control de acceso a la red (NAC) que intercepta el tráfico HTTP/HTTPS no autenticado y fuerza una redirección a una interfaz de autenticación basada en web.

El Modelo de Intercepción Heredado

Históricamente, los Captive Portals se basaban en una combinación de secuestro de DNS y redirecciones HTTP 302. Cuando un dispositivo invitado se conecta a un SSID, el Asistente de Red Cautiva (CNA) del sistema operativo envía una solicitud de sondeo a un punto final conocido (por ejemplo, captive.apple.com para iOS).

Intercepción de DNS: La puerta de enlace local intercepta la solicitud DNS para la URL de sondeo y la resuelve a la dirección IP del Captive Portal.
Redirección HTTP: Si no se utiliza la intercepción de DNS, la puerta de enlace intercepta la solicitud HTTP GET saliente y devuelve un HTTP 302 Found, redirigiendo al cliente a la página de bienvenida.
Jardín Amurallado del Firewall: Todo el demás tráfico saliente es bloqueado por el firewall de la puerta de enlace hasta que se completa la autenticación. Solo se permite el tráfico al portal y a los recursos externos aprobados (el "jardín amurallado").

Para un desglose más detallado de esta mecánica, consulte nuestra guía: ¿Cómo funciona un Captive Portal? Análisis Técnico Detallado .

El Estándar Moderno: RFC 8908 (CAPPORT API)

El modelo de intercepción heredado tiene dificultades con las arquitecturas modernas de HTTPS en todas partes. Los navegadores marcan correctamente el tráfico HTTPS interceptado como un ataque Man-in-the-Middle (MitM), lo que resulta en advertencias de certificado en lugar de una página de bienvenida limpia.

Para resolver esto, el grupo de trabajo CAPPORT de la IETF desarrolló RFC 8908 y RFC 8910. En lugar de interceptar el tráfico, la red anuncia explícitamente la presencia de un Captive Portal a través de DHCP (Opción 114) o Anuncios de Router IPv6. El dispositivo cliente consulta una JSON API para descubrir la URL del portal y su estado de autenticación actual. Si está construyendo un portal moderno, implementar la CAPPORT API es fundamental para una experiencia de usuario fluida en dispositivos iOS y Android modernos.

Flujos de Autenticación y Autorización

Una vez que se muestra la página de bienvenida, el flujo de autenticación dicta la experiencia del usuario y los datos recopilados.

Click-Through (Términos de Servicio): El enfoque de menor fricción. No se requieren credenciales, solo una aceptación booleana de los términos. Adecuado para entornos de alta densidad donde se prioriza el rendimiento sobre la captura de datos.
Captura de Identidad (Correo Electrónico/Social): El usuario se autentica a través de OAuth (Google, Facebook) o un formulario de correo electrónico. Esto requiere una integración cuidadosa con los proveedores de identidad y mecanismos robustos de cumplimiento del GDPR.
802.1X y RADIUS: Para entornos de alta seguridad (por ejemplo, Sanidad o redes de invitados corporativas), se requiere control de acceso a la red basado en puertos a través de IEEE 802.1X. El Punto de Acceso actúa como cliente RADIUS, reenviando las credenciales a un servidor RADIUS (como FreeRADIUS) para su validación contra un servicio de directorio.

Guía de Implementación: Código Abierto vs. Plataformas Gestionadas

Para los desarrolladores encargados de construir un Captive Portal, el ecosistema de código abierto ofrece varias bases robustas. Sin embargo, estas herramientas proporcionan la infraestructura de red, no la lógica de negocio.

Principales Opciones de Código Abierto

pfSense + Captive Portal: Una popular distribución de firewall que incluye un módulo de Captive Portal capaz. Gestiona la integración RADIUS, el filtrado de direcciones MAC y la configuración básica de ancho de banda. Ideal para despliegues de un solo sitio con ingenieros de red experimentados.
Coova-Chilli: Un controlador de acceso maduro y rico en funciones que implementa el protocolo WISPr. Destaca en entornos RADIUS complejos y puede extenderse para el inicio de sesión social, pero requiere una experiencia significativa en administración de sistemas Linux.
PacketFence: Una solución NAC de código abierto completa. Soporta 802.1X, la incorporación de BYOD y la integración con directorios empresariales. Altamente escalable, pero conlleva una curva de aprendizaje pronunciada y una sobrecarga operativa significativa.

El "Construir vs. Marco de decisión "Adquirir"

Aunque el software de código abierto es "gratuito", el coste total de propiedad de un portal autoconstruido escala de forma no lineal con el número de ubicaciones y la complejidad de los requisitos empresariales.

Cuándo construir:

Opera una única ubicación o un pequeño grupo de sitios altamente uniformes.
Sus requisitos se limitan a la aceptación básica de los Términos de Servicio o a un acceso WPA2-PSK sencillo.
Dispone de recursos de ingeniería de Linux y redes dedicados e internos.

Cuándo adquirir (Plataforma empresarial):

Escala multisitio: Está implementando en docenas o cientos de ubicaciones con hardware subyacente variado (Cisco, Aruba, Meraki).
Cumplimiento: Requiere gestión automatizada del consentimiento GDPR/CCPA, manejo de solicitudes de acceso de interesados (DSAR) y registros de auditoría verificables.
Inteligencia empresarial: Necesita integrar datos de red con sistemas de marketing. Plataformas como Purple proporcionan una capa unificada de WiFi Analytics , transformando las direcciones MAC sin procesar en métricas procesables de afluencia y tiempo de permanencia.
Integraciones avanzadas: Necesita una integración perfecta con sistemas de gestión de propiedades (PMS) o bases de datos de fidelización.

De forma similar a cómo las arquitecturas WAN empresariales están evolucionando hacia soluciones SD-WAN gestionadas (véase Los beneficios clave de SD-WAN para empresas modernas ), el WiFi para invitados empresarial está evolucionando hacia plataformas en la nube agnósticas al hardware que abstraen la complejidad de la red de borde.

Mejores prácticas y mitigación de riesgos

Si procede con una construcción personalizada o está evaluando un proveedor, asegúrese de que se cumplen estas mejores prácticas arquitectónicas:

1. Segmentación y seguridad de la red

Nunca implemente un Captive Portal en la misma VLAN que su red corporativa o de tecnología operativa (OT). El tráfico de invitados debe estar estrictamente segmentado. Si su ubicación procesa pagos (por ejemplo, un centro de Transporte con concesiones minoristas), la falta de segmentación del WiFi para invitados hará que toda la red entre en el ámbito de PCI DSS, aumentando enormemente los costes de cumplimiento.

2. Configuración de Walled Garden

Su Walled Garden debe permitir explícitamente el tráfico a los dominios necesarios para que la autenticación se realice correctamente. Para el inicio de sesión social, esto significa permitir el acceso a accounts.google.com, graph.facebook.com y sus CDN asociadas. Un Walled Garden mal configurado hace que los usuarios se queden atascados en una página de bienvenida en blanco.

3. Gestión de ancho de banda y sesiones

Implemente una limitación estricta de la tasa por usuario y tiempos de espera de sesión. Un único usuario que descargue una gran actualización del sistema operativo puede saturar el enlace ascendente WAN, degradando la experiencia para todos los invitados. Utilice atributos RADIUS (por ejemplo, WISPr-Bandwidth-Max-Down) para aplicar estos límites dinámicamente.

4. Mitigación de la suplantación de MAC

Depender únicamente de las direcciones MAC para la persistencia de la sesión es un riesgo de seguridad, ya que las direcciones MAC se pueden suplantar fácilmente, y las características modernas del sistema operativo (como iOS Private Wi-Fi Address) las aleatorizan por defecto. Asegúrese de que la arquitectura de su portal puede manejar la aleatorización de MAC de forma elegante, normalmente requiriendo una nueva autenticación cuando la MAC cambia, o utilizando Passpoint/Hotspot 2.0 para una itinerancia segura y sin interrupciones.

ROI e impacto empresarial

Un Captive Portal no debe verse simplemente como un centro de costes de TI; es un canal crítico de adquisición de datos.

Cuando se implementa correctamente —a menudo a través de una plataforma gestionada—, el ROI se mide en tres áreas:

Crecimiento de la base de datos de marketing: Un flujo de incorporación fluido con un claro intercambio de valor (por ejemplo, "WiFi gratuito a cambio de un correo electrónico") construye rápidamente una base de datos de marketing propia y conforme.
Inteligencia operativa: Los análisis derivados de los datos de conexión proporcionan a los operadores de las ubicaciones mapas de calor, análisis de carga máxima y métricas de visitantes recurrentes, lo que influye directamente en las decisiones de personal y diseño.
Reducción de riesgos: La gestión centralizada del cumplimiento reduce significativamente el riesgo de multas regulatorias asociadas con el manejo inadecuado de datos o violaciones de PCI DSS.

En última instancia, el objetivo de un desarrollador o arquitecto es ofrecer una experiencia de red segura y sin fricciones que sirva a los objetivos estratégicos del negocio. Elija la arquitectura que permita a su equipo centrarse en esos objetivos, en lugar de gestionar la infraestructura.

Términos clave y definiciones

Captive Portal

A web page that the user of a public-access network is obliged to view and interact with before access is granted.

The primary interface for guest network onboarding, used for terms acceptance, payment, or data capture.

RADIUS (Remote Authentication Dial-In User Service)

A networking protocol that provides centralized Authentication, Authorization, and Accounting (AAA) management for users who connect and use a network service.

The backend engine that validates credentials and tells the network equipment what permissions a guest should have.

Walled Garden

A limited environment that controls the user's access to external web content and services prior to full authentication.

Essential for allowing users to access identity providers (like Google or Facebook) to log in, before they have general internet access.

MAC Spoofing

The practice of altering a device's factory-assigned Media Access Control (MAC) address to masquerade as another device or bypass network restrictions.

A common method used to bypass captive portal time limits, requiring robust session management strategies to mitigate.

CAPPORT API (RFC 8908)

A modern IETF standard allowing devices to securely discover the captive portal URL and authentication status via DHCP or Router Advertisements, rather than relying on HTTP interception.

Critical for modern portal development to prevent HTTPS certificate errors and improve the user onboarding experience.

IEEE 802.1X

An IEEE Standard for port-based Network Access Control (PNAC), providing an authentication mechanism to devices wishing to attach to a LAN or WLAN.

Used in enterprise and high-security environments where simple web-based authentication is insufficient.

WISPr (Wireless Internet Service Provider roaming)

A draft protocol submitted to the Wi-Fi Alliance that allows users to roam between different wireless internet service providers.

Often implemented by access controllers to handle the XML-based authentication requests from the captive portal to the gateway.

VLAN Segmentation

The practice of partitioning a single layer-2 network to create multiple distinct broadcast domains.

A mandatory security practice to ensure guest WiFi traffic cannot access corporate or operational technology networks.

Casos de éxito

A 200-room hotel needs to deploy guest WiFi. They require guests to authenticate using their room number and last name to access a premium bandwidth tier, while non-guests receive a throttled 2Mbps connection. The underlying network uses Cisco Meraki access points.

Configure the Meraki SSID to use an external captive portal (Splash page URL pointing to the custom portal). 2. Set up a RADIUS server (e.g., FreeRADIUS) and configure the Meraki APs as RADIUS clients. 3. Develop the captive portal web application to present a login form requesting Room Number and Last Name. 4. Integrate the portal backend with the hotel's Property Management System (PMS) via API. When credentials are submitted, the portal queries the PMS to validate the guest. 5. Upon successful validation, the portal backend sends a RADIUS Access-Accept message to the Meraki controller, including Vendor-Specific Attributes (VSAs) to apply the 'Premium' group policy (unthrottled bandwidth). 6. For non-guests, provide a 'Free Access' button that bypasses the PMS check and returns a RADIUS Access-Accept with VSAs applying the 'Throttled' group policy.

Notas de implementación: This approach correctly separates the network layer (Meraki) from the business logic (PMS integration). By utilizing RADIUS VSAs, the network dynamically applies bandwidth shaping based on the user's identity tier, satisfying the core requirement while maintaining a centralized control plane.

A national retail chain with 50 locations wants to implement a captive portal to collect customer emails for marketing. They are concerned about GDPR compliance and the operational overhead of managing 50 separate local portal instances.

Instead of deploying local captive portal software (like pfSense) at each site, deploy a centralized, cloud-hosted captive portal platform (like Purple). Configure the local branch routers/APs to redirect guest traffic to the centralized portal URL. Implement a standardized splash page with explicit opt-in checkboxes for marketing consent and a link to the privacy policy. The centralized platform handles the capture, timestamping, and secure storage of consent records, and integrates directly via API with the retailer's central CRM system.

Notas de implementación: A centralized architecture is essential for multi-site retail. Attempting to manage compliance and data aggregation across 50 distributed open-source instances is highly risky and operationally inefficient. The centralized platform ensures uniform compliance posture and real-time data synchronization.

Análisis de escenarios

Q1. You are deploying a captive portal in an airport. The primary goal is maximum throughput and minimizing support tickets from users unable to connect. Which authentication method should you prioritize?

💡 Sugerencia:Consider the friction involved in verifying identities versus simply gaining legal consent.

Mostrar enfoque recomendado

A Click-Through (Terms of Service) portal. In high-density transit environments, requiring email verification or SMS OTP introduces significant friction and relies on external dependencies (cellular reception for SMS, existing email access). A simple Terms of Service acceptance minimizes support overhead while meeting basic legal requirements.

Q2. Your security team reports that users are bypassing the 2-hour free WiFi limit by changing their device's MAC address. How should you architect the network to mitigate this?

💡 Sugerencia:MAC addresses are layer-2 identifiers that can be easily spoofed. You need a layer-7 identity verification.

Mostrar enfoque recomendado

Shift from a purely MAC-based session tracking model to an identity-based model. Require users to authenticate via a unique identifier (e.g., SMS OTP or a verified email address) and tie the session limit to that identity in the RADIUS backend, rather than the device's MAC address.

Q3. A hospital requires a guest WiFi network for patients and visitors. They also need a separate network for medical IoT devices. What is the most critical architectural requirement?

💡 Sugerencia:Consider the impact if a compromised guest device could reach a medical device.

Mostrar enfoque recomendado

Strict VLAN segmentation. The guest WiFi network must be placed on a completely isolated VLAN that has no routing path to the clinical or IoT networks. The captive portal and guest traffic must be firewalled and routed directly to the internet.