Voir la transcription du podcast
Captive Portal pour Ubiquiti UniFi - Un briefing technique Purple
[INTRODUCTION & CONTEXTE - environ 1 minute]
Bienvenue dans la série de briefings techniques Purple. Je suis votre hôte, et aujourd'hui nous entrons dans les détails du déploiement d'un Captive Portal externe sur l'infrastructure Ubiquiti UniFi - l'une des plateformes réseau les plus déployées dans les secteurs de l'hôtellerie, de la vente au détail et des entreprises à l'échelle mondiale.
Si vous êtes responsable informatique, architecte réseau ou intégrateur de systèmes travaillant avec des UniFi Cloud Gateways, des Dream Machines ou l'application UniFi Network, cet épisode est pour vous. Nous allons détailler exactement comment le mécanisme de portail externe fonctionne sous le capot, comment le configurer correctement, où se trouvent les pièges courants, et pourquoi superposer Purple sur un déploiement UniFi est la bonne décision architecturale pour les établissements qui ont besoin de plus qu'une simple page d'accueil de base.
C'est parti.
[ANALYSE TECHNIQUE APPROFONDIE - environ 5 minutes]
Tout d'abord, comprenons ce qui se passe réellement lorsqu'un appareil invité se connecte à un SSID UniFi sur lequel un Captive Portal est activé.
Lorsqu'un appareil invité s'associe à votre SSID invité, le point d'accès UniFi lui attribue une adresse IP via DHCP de manière normale. Mais l'appareil est immédiatement placé dans ce que UniFi appelle un état "en attente". Dans cet état, le processus DNSmasq intégré du point d'accès intercepte chaque requête DNS formulée par l'appareil, quel que soit le serveur DNS que l'appareil pense utiliser. Le point d'accès redirige tout le trafic DNS vers lui-même.
Simultanément, le point d'accès exécute un redirecteur HTTP léger sur le port 80. Dès que le navigateur de l'invité effectue une requête HTTP - et c'est le mot clé, HTTP, pas HTTPS - le redirecteur renvoie une redirection 302, envoyant le navigateur vers la page d'accueil du Captive Portal. C'est ce mécanisme qui déclenche la notification "Se connecter au WiFi" sur les appareils iOS et Android.
C'est là que la distinction entre portail intégré et portail externe devient essentielle. Avec le portail Hotspot UniFi intégré, la page d'accueil est servie directement par l'application UniFi Network. C'est fonctionnel, rapide à configurer, mais c'est extrêmement limité. Vous disposez d'une authentification de base par mot de passe, de coupons et de paiements Stripe. Il n'y a pas de collecte d'e-mails, pas de connexion via les réseaux sociaux, pas de gestion du consentement GDPR, pas d'intégration CRM, et pas d'analyses significatives au-delà du nombre de sessions.
Lorsque vous configurez un serveur de portail externe (External Portal Server) - qui est le paramètre sur lequel nous nous concentrons aujourd'hui - vous indiquez au contrôleur UniFi de rediriger les invités vers une application web complètement distincte. Dans notre cas, il s'agit de Purple. L'URL que vous saisissez dans le champ External Portal Server devient la destination de toutes ces redirections 302.Voici le détail technique important concernant cette URL de redirection. Lorsque UniFi redirige un invité vers votre portail externe, il ajoute plusieurs paramètres de requête à l'URL. Ceux-ci incluent : l'adresse MAC de l'AP, l'adresse MAC de l'appareil client, un horodatage Unix, l'URL d'origine que le client tentait d'atteindre et le nom du SSID. Votre portail externe - Purple dans ce contexte - capture ces paramètres, les utilise pour identifier l'appareil qui se connecte, présente la splash page appropriée, gère l'authentification, puis effectue un appel API vers l'application réseau UniFi pour autoriser cette adresse MAC.
Cet appel API est l'étape cruciale de communication. Depuis la version 9.1 et les versions ultérieures de l'application réseau UniFi, il existe une API REST officielle avec une authentification par clé appropriée. Le point de terminaison d'autorisation est une requête POST vers la version un de l'API des sites, ciblant l'identifiant client spécifique, avec un corps JSON qui peut spécifier des limites de temps en minutes, des limites d'utilisation des données en mégaoctets et des limites de débit en kilobits par seconde. Une fois que le contrôleur reçoit cette autorisation, il envoie l'instruction à l'AP et l'invité passe du statut en attente à celui d'autorisé. L'accès Internet est accordé.
Parlons maintenant du Walled Garden, que UniFi appelle l'accès pré-autorisation. Il s'agit de la liste blanche des domaines et des adresses IP que les invités peuvent atteindre avant de s'être authentifiés. C'est essentiel, et c'est l'une des sources de mauvaise configuration les plus courantes.
Au minimum, votre walled garden doit inclure le nom de domaine complet de votre portail Purple, ainsi que les adresses IP ou les plages CIDR vers lesquelles l'infrastructure de Purple se résout. Si vous utilisez la connexion via les réseaux sociaux - Facebook, Google, Microsoft - vous devez également ajouter les domaines des points de terminaison OAuth de ces fournisseurs. Les points de terminaison de connexion de Google couvrent plusieurs plages IP et plusieurs domaines, notamment accounts.google.com et oauth2.googleapis.com. De même, l'infrastructure de connexion de Facebook nécessite plusieurs entrées. La documentation de Purple fournit une liste mise à jour des entrées exactes requises, et cette liste est actualisée à mesure que ces fournisseurs mettent à jour leur infrastructure.
Il existe une particularité critique propre à UniFi qui piège de nombreux déploiements. Le redirecteur HTTP sur l'AP n'intercepte que le trafic HTTP classique sur le port 80. Les appareils modernes - iOS, Android, Windows, macOS - effectuent tous une détection de Captive Portal via HTTPS. Les appareils Apple contactent captive.apple.com en HTTPS. Les appareils Android contactent connectivitycheck.gstatic.com. Si ces requêtes HTTPS ne reçoivent pas de réponse spécifique, l'appareil peut décider qu'il n'y a pas de Captive Portal et tout simplement ne pas afficher l'invite de connexion.
La solution consiste à s'assurer que votre walled garden inclut les domaines de détection de Captive Portal pour les principaux systèmes d'exploitation, et que votre portail Purple est accessible en HTTPS avec un certificat SSL valide et approuvé. Les certificats auto-signés provoqueront des avertissements de sécurité du navigateur qui bloqueront le chargement du portail. C'est non négociable pour les déploiements en production.
L'autre aspect spécifique à UniFi concerne l'accessibilité du contrôleur. L'application UniFi Network - qu'elle soit exécutée sur une Cloud Gateway, une Cloud Key ou un serveur auto-hébergé - doit être accessible depuis l'infrastructure de Purple pour que les appels d'autorisation API réussissent. Si votre contrôleur se trouve sur un réseau privé derrière un NAT, vous devrez vous assurer que les ports API correspondants sont accessibles. Pour les contrôleurs auto-hébergés, il s'agit généralement du port 8443 pour l'ancienne API, ou du port HTTPS standard 443 pour la nouvelle API introduite dans la version 9.1. La documentation d'assistance de Purple spécifie les plages IP exactes qui nécessitent un accès entrant à votre contrôleur.
Pour l'authentification basée sur RADIUS - qui s'applique lorsque vous déployez Purple avec des SSID WPA2-Enterprise ou WPA3-Enterprise plutôt qu'avec le modèle de SSID invité ouvert - le serveur RADIUS intégré d'UniFi prend en charge les méthodes EAP standard 802.1X. Vous configurez le profil RADIUS sous Paramètres, Réseaux, Serveurs RADIUS, puis vous référencez ce profil dans la configuration de votre SSID. UniFi prend également en charge RADIUS sur TLS, connu sous le nom de RADSEC, à partir de la version 8.4, ce qui chiffre le trafic RADIUS entre la borne d'accès et le serveur d'authentification. Pour les déploiements multi-sites où le trafic RADIUS traverse l'internet public, RADSEC est fortement recommandé.
[RECOMMANDATIONS DE MISE EN ŒUVRE ET PIÈGES À ÉVITER - environ 2 minutes]
Voici la liste de contrôle de mise en œuvre pratique que je passerais en revue avec tout client déployant Purple sur UniFi.
Premièrement, la segmentation du réseau. Votre SSID invité doit être sur un VLAN dédié, isolé de vos réseaux d'entreprise et IoT. UniFi rend cela très simple : créez un réseau dédié dans Paramètres, Réseaux, attribuez-lui un ID de VLAN et associez votre SSID invité à ce réseau. Activez l'isolation des clients sur le réseau invité pour empêcher le trafic d'invité à invité.
Deuxièmement, le contrôleur doit disposer d'un FQDN valide et d'un certificat SSL de confiance. Ne vous fiez pas à l'adresse IP. Utilisez un nom de domaine approprié, installez-y un certificat Let's Encrypt ou commercial, et configurez UniFi pour utiliser ce certificat. Cela résout la majorité des problèmes de redirection HTTPS.
Troisièmement, configurez votre walled garden (jardin secret) avec soin et testez-le. Les entrées minimales sont : le domaine de votre Captive Portal Purple et ses plages IP, les domaines de détection de portail captif pour iOS, Android et Windows, ainsi que tous les domaines de fournisseurs OAuth que vous utilisez. Testez avec un appareil qui ne s'est jamais connecté au réseau auparavant - le cache DNS et l'état du réseau peuvent masquer des lacunes de configuration du walled garden lors des tests.
Quatrièmement, pour l'intégration de l'API, utilisez un compte d'administrateur local dédié dans l'application UniFi Network avec les autorisations minimales requises. N'utilisez pas vos identifiants d'administrateur principal. Si vous utilisez la version Network Application 9.1 ou ultérieure, utilisez le nouveau mécanisme de clé API sous Control Plane, Intégrations - il est plus sécurisé et ne nécessite pas d'authentification basée sur des identifiants.
Cinquièmement, réfléchissez attentivement à la durée de la session. L'expiration par défaut de la session invité de UniFi peut être de seulement huit heures. Pour les déploiements dans le secteur de l'hôtellerie où les clients peuvent séjourner plusieurs nuits, configurez des durées de session appropriées dans les paramètres du portail Purple, et assurez-vous que ces durées sont correctement transmises dans l'appel d'autorisation de l'API.
Le piège le plus courant que je rencontre est le déploiement sur un contrôleur auto-hébergé qui n'est pas accessible publiquement. Si Purple ne peut pas joindre votre contrôleur pour autoriser les invités, le portail se chargera mais l'authentification échouera silencieusement. Vérifiez toujours la connectivité de l'API depuis l'infrastructure de Purple avant la mise en service.
[QUESTIONS - RÉPONSES RAPIDES - environ 1 minute]
Cela fonctionne-t-il sur UniFi Dream Machine Pro ? Oui. Toutes les consoles UniFi OS - UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max - prennent en charge la configuration du serveur de portail externe. L'application réseau s'exécute sur l'appareil.
Puis-je utiliser Purple sur plusieurs sites UniFi à partir d'un seul compte Purple ? Oui. L'architecture multi-site de Purple est conçue exactement pour cela. Chaque site physique est configuré comme un site distinct dans Purple, mappé au site UniFi correspondant.
Dois-je ouvrir des ports de pare-feu sur la passerelle UniFi ? Vous devez vous assurer que le trafic du VLAN invité peut atteindre le domaine du portail Purple sur le port 443. Le port de l'API du contrôleur doit également être accessible depuis les serveurs de Purple. La documentation de Purple fournit les plages d'adresses IP spécifiques.
Qu'en est-il du WPA3 ? UniFi prend en charge le WPA3 Personal et le WPA3 Enterprise. Le mécanisme de Captive Portal fonctionne avec le WPA3 Personal sur les réseaux invités. Le WPA3 Enterprise utilise le 802.1X et le RADIUS, ce qui correspond à un flux d'authentification différent.
[RÉSUMÉ ET PROCHAINES ÉTAPES - environ 1 minute]
En résumé : le déploiement de Purple en tant que Captive Portal externe sur UniFi est une intégration bien prise en charge et structurellement solide. Les étapes clés sont les suivantes : configurez votre SSID invité avec l'option de serveur de portail externe pointant vers l'URL de votre portail Purple, créez un walled garden complet qui couvre l'infrastructure de Purple et tous les fournisseurs OAuth que vous utilisez, assurez-vous que votre contrôleur UniFi dispose d'un certificat SSL valide et est accessible depuis les serveurs API de Purple, et configurez des durées de session adaptées à votre type d'établissement.
L'intérêt commercial est évident. Le portail UniFi intégré vous offre une simple page d'accueil. Purple vous offre une plateforme d'expérience client axée sur l'analyse et conforme aux réglementations, qui s'intègre à votre CRM, capture des données de première partie conformément au consentement GDPR, et fournit les analyses de fréquentation et de temps de présence dont les exploitants de sites et les équipes marketing ont réellement besoin.
Si vous êtes un MSP ou un intégrateur de systèmes déployant UniFi à grande échelle, la gestion multi-site de Purple et ses capacités de marque blanche en font la solution idéale pour vos clients.
Pour obtenir une documentation de configuration détaillée, les listes d'adresses IP pour le walled garden et les guides d'intégration API, rendez-vous sur purple.ai. Merci pour votre écoute.
