Comment construire un Captive Portal : Guide du développeur

Un guide technique définitif pour les architectes informatiques et les gestionnaires de réseau sur la construction et le déploiement de portails captifs. Ce guide couvre les protocoles sous-jacents, les flux d'authentification, les architectures open-source et un cadre pour décider quand construire ou acheter une plateforme d'entreprise gérée.

📖 6 min de lecture📝 1,311 mots🔧 2 exemples❓ 3 questions📚 8 termes clés

🎧 Écouter ce guide

Voir la transcription

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.

Résumé Exécutif

Pour les architectes réseau d'entreprise et les directeurs informatiques, le déploiement d'un Captive Portal est rarement un simple exercice de mise en réseau – c'est une intersection critique entre la sécurité réseau, la conformité réglementaire et l'intelligence économique. Que vous gériez un portefeuille de 200 propriétés Hospitality , un vaste domaine Retail ou un stade à haute densité, la décision de construire un Captive Portal personnalisé ou de déployer une plateforme gérée a des implications profondes sur le coût total de possession (TCO) et le risque opérationnel.

Ce guide propose une analyse technique approfondie et neutre de l'architecture des portails captifs. Nous explorerons les mécanismes sous-jacents de redirection HTTP, la moderne Captive Portal API (RFC 8908), les flux d'authentification 802.1X RADIUS et les principales options open-source. De manière cruciale, nous fournissons un cadre pour évaluer quand une pile open-source auto-construite est pertinente, et quand la surcharge de conformité et d'intégration nécessite une plateforme d'entreprise comme la solution Guest WiFi de Purple.

Écoutez notre briefing audio complémentaire pour un aperçu stratégique :

Analyse Technique Approfondie : Comment fonctionnent les Captive Portals

Avant d'évaluer les options logicielles, il est essentiel de comprendre les mécanismes réseau fondamentaux. Un Captive Portal est essentiellement un mécanisme de contrôle d'accès réseau (NAC) qui intercepte le trafic HTTP/HTTPS non authentifié et force une redirection vers une interface d'authentification basée sur le web.

Le Modèle d'Interception Hérité

Historiquement, les portails captifs s'appuyaient sur une combinaison de détournement DNS et de redirections HTTP 302. Lorsqu'un appareil invité se connecte à un SSID, le Captive Network Assistant (CNA) du système d'exploitation envoie une requête de sonde à un point de terminaison connu (par exemple, captive.apple.com pour iOS).

Interception DNS : La passerelle locale intercepte la requête DNS pour l'URL de la sonde et la résout vers l'adresse IP du portail captif.
Redirection HTTP : Si l'interception DNS n'est pas utilisée, la passerelle intercepte la requête HTTP GET sortante et renvoie un HTTP 302 Found, redirigeant le client vers la splash page.
Firewall Walled Garden : Tout autre trafic sortant est bloqué par le firewall de la passerelle jusqu'à ce que l'authentification soit terminée. Seul le trafic vers le portail et les ressources externes approuvées (le "walled garden") est autorisé.

Pour une explication plus détaillée de ces mécanismes, consultez notre guide : Comment fonctionne un Captive Portal ? Analyse technique approfondie .

The Modern Standard: RFC 8908 (CAPPORT API)

Le modèle d'interception hérité rencontre des difficultés avec les architectures modernes "HTTPS-everywhere". Les navigateurs signalent à juste titre le trafic HTTPS intercepté comme une attaque de type Man-in-the-Middle (MitM), ce qui entraîne des avertissements de certificat plutôt qu'une splash page propre.

Pour résoudre ce problème, le groupe de travail IETF CAPPORT a développé les RFC 8908 et RFC 8910. Au lieu d'intercepter le trafic, le réseau annonce explicitement la présence d'un portail captif via DHCP (Option 114) ou les annonces de routeur IPv6. L'appareil client interroge une JSON API pour découvrir l'URL du portail et son état d'authentification actuel. Si vous construisez un portail moderne, l'implémentation de la CAPPORT API est essentielle pour une expérience utilisateur fluide sur les appareils iOS et Android modernes.

Flux d'Authentification et d'Autorisation

Une fois la splash page affichée, le flux d'authentification dicte l'expérience utilisateur et les données collectées.

Click-Through (Terms of Service) : L'approche la moins contraignante. Aucune information d'identification requise, juste une acceptation booléenne des conditions. Convient aux environnements à haute densité où le débit est prioritaire sur la capture de données.
Capture d'Identité (Email/Social) : L'utilisateur s'authentifie via OAuth (Google, Facebook) ou un formulaire d'e-mail. Cela nécessite une intégration minutieuse avec les fournisseurs d'identité et des mécanismes robustes de conformité GDPR.
802.1X et RADIUS : Pour les environnements à haute sécurité (par exemple, Healthcare ou les réseaux invités d'entreprise), un contrôle d'accès réseau basé sur les ports via IEEE 802.1X est requis. L'Access Point agit comme un client RADIUS, transmettant les informations d'identification à un serveur RADIUS (comme FreeRADIUS) pour validation par rapport à un service d'annuaire.

Guide d'Implémentation : Open-Source vs. Plateformes Gérées

Pour les développeurs chargés de construire un portail captif, l'écosystème open-source offre plusieurs bases robustes. Cependant, ces outils fournissent la plomberie réseau, pas la logique métier.

Principales Options Open-Source

pfSense + Captive Portal : Une distribution de firewall populaire qui inclut un module de portail captif performant. Il gère l'intégration RADIUS, le filtrage des adresses MAC et la mise en forme de bande passante de base. Idéal pour les déploiements sur un seul site avec des ingénieurs réseau expérimentés.
Coova-Chilli : Un contrôleur d'accès mature et riche en fonctionnalités qui implémente le protocole WISPr. Il excelle dans les environnements RADIUS complexes et peut être étendu pour la connexion sociale, mais nécessite une expertise significative en administration système Linux.
PacketFence : Une solution NAC open-source complète. Elle prend en charge 802.1X, l'intégration BYOD et l'intégration avec les annuaires d'entreprise. Hautement évolutive, mais implique une courbe d'apprentissage abrupte et une surcharge opérationnelle significative.

Le "Construire vs. "Cadre de décision « Acheter »

Bien que les logiciels open source soient « gratuits », le coût total de possession d'un portail auto-construit augmente de manière non linéaire avec le nombre de sites et la complexité des exigences commerciales.

Quand construire :

Vous exploitez un seul site ou un petit groupe de sites très uniformes.
Vos exigences se limitent à l'acceptation des conditions d'utilisation de base ou à un simple accès WPA2-PSK.
Vous disposez de ressources internes dédiées en ingénierie Linux et réseau.

Quand acheter (plateforme d'entreprise) :

Échelle multi-sites : Vous déployez sur des dizaines ou des centaines de sites avec du matériel sous-jacent varié (Cisco, Aruba, Meraki).
Conformité : Vous avez besoin d'une gestion automatisée du consentement GDPR/CCPA, du traitement des demandes d'accès des personnes concernées (DSAR) et de pistes d'audit vérifiables.
Business Intelligence : Vous devez intégrer les données réseau aux systèmes marketing. Des plateformes comme Purple fournissent une couche unifiée de WiFi Analytics , transformant les adresses MAC brutes en métriques exploitables de fréquentation et de temps de présence.
Intégrations avancées : Vous avez besoin d'une intégration transparente avec les systèmes de gestion immobilière (PMS) ou les bases de données de fidélité.

De même que les architectures WAN d'entreprise évoluent vers des solutions SD-WAN gérées (voir Les avantages clés du SD-WAN pour les entreprises modernes ), le WiFi invité d'entreprise se tourne vers des plateformes cloud indépendantes du matériel qui abstraient la complexité du réseau périphérique.

Bonnes pratiques et atténuation des risques

Si vous optez pour une construction personnalisée ou si vous évaluez un fournisseur, assurez-vous que ces bonnes pratiques architecturales sont respectées :

1. Segmentation et sécurité du réseau

Ne déployez jamais un Captive Portal sur le même VLAN que votre réseau d'entreprise ou de technologie opérationnelle (OT). Le trafic invité doit être strictement segmenté. Si votre site traite des paiements (par exemple, un pôle de Transport avec des concessions de vente au détail), le fait de ne pas segmenter le WiFi invité entraînera l'inclusion de l'ensemble du réseau dans le périmètre PCI DSS, augmentant considérablement les coûts de conformité.

2. Configuration du Walled Garden

Votre walled garden doit explicitement autoriser le trafic vers les domaines requis pour que l'authentification réussisse. Pour la connexion sociale, cela signifie autoriser l'accès à accounts.google.com, graph.facebook.com et leurs CDN associés. Un walled garden mal configuré a pour conséquence que les utilisateurs restent bloqués sur une page d'accueil vierge.

3. Gestion de la bande passante et des sessions

Mettez en œuvre une limitation stricte du débit par utilisateur et des délais d'expiration de session. Un seul utilisateur téléchargeant une mise à jour importante du système d'exploitation peut saturer la liaison montante WAN, dégradant l'expérience pour tous les invités. Utilisez les attributs RADIUS (par exemple, WISPr-Bandwidth-Max-Down) pour appliquer ces limites dynamiquement.

4. Atténuation de l'usurpation d'adresse MAC

Se fier uniquement aux adresses MAC pour la persistance de session est un risque de sécurité, car les adresses MAC sont facilement usurpées, et les fonctionnalités modernes des systèmes d'exploitation (comme iOS Private Wi-Fi Address) les randomisent par défaut. Assurez-vous que l'architecture de votre portail peut gérer la randomisation MAC avec élégance, généralement en exigeant une réauthentification lorsque l'adresse MAC change, ou en utilisant Passpoint/Hotspot 2.0 pour un roaming fluide et sécurisé.

ROI et impact commercial

Un Captive Portal ne doit pas être considéré uniquement comme un centre de coûts informatiques ; c'est un canal d'acquisition de données essentiel.

Lorsqu'il est déployé correctement — souvent via une plateforme gérée — le ROI est mesuré dans trois domaines :

Croissance de la base de données marketing : Un flux d'intégration fluide avec un échange de valeur clair (par exemple, « WiFi gratuit en échange d'un e-mail ») construit rapidement une base de données marketing conforme et de première partie.
Intelligence opérationnelle : Les analyses dérivées des données de connexion fournissent aux opérateurs de sites des cartes thermiques, des analyses de charge maximale et des métriques de visiteurs récurrents, influençant directement les décisions de personnel et d'aménagement.
Réduction des risques : La gestion centralisée de la conformité réduit considérablement le risque d'amendes réglementaires associées à une mauvaise gestion des données ou à des violations PCI DSS.

En fin de compte, l'objectif d'un développeur ou d'un architecte est de fournir une expérience réseau sécurisée et fluide qui sert les objectifs stratégiques de l'entreprise. Choisissez l'architecture qui permet à votre équipe de se concentrer sur ces objectifs, plutôt que de gérer la plomberie.

Termes clés et définitions

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.

Études de cas

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.

Notes de mise en œuvre : 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.

Notes de mise en œuvre : 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.

Analyse de scénario

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?

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

Afficher l'approche recommandée

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?

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

Afficher l'approche recommandée

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?

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

Afficher l'approche recommandée

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.