Captive Portal pour Ubiquiti UniFi

Ce guide technique de référence détaille la configuration d'un Captive Portal externe (Purple) sur l'application réseau Ubiquiti UniFi. Il couvre les mécanismes réseau sous-jacents, le déploiement étape par étape du réseau invité, la configuration du Walled Garden (liste blanche), l'authentification RADIUS et les stratégies de dépannage pour les professionnels de l'IT et les administrateurs réseau.

📖 10 min de lecture📝 2,475 mots🔧 2 exemples concrets❓ 3 questions d'entraînement📚 8 définitions clés

Écouter ce guide

Voir la transcription du podcast

Captive Portal for 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 allons entrer 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 les UniFi Cloud Gateways, les Dream Machines ou l'application réseau UniFi, cet épisode vous est destiné. Nous allons analyser précisément le fonctionnement sous-jacent du mécanisme de portail externe, comment le configurer correctement, quels sont les pièges courants et pourquoi l'intégration de Purple sur un déploiement UniFi constitue la bonne décision architecturale pour les établissements qui ont besoin de plus qu'une simple page de connexion basique.

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, comme d'habitude. Cependant, l'appareil est immédiatement placé dans ce que UniFi appelle un état « en attente ». Dans cet état, le processus DNSmasq intégré au 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, et non HTTPS), le redirecteur renvoie une redirection 302, envoyant le navigateur vers la page de connexion 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 ici que la distinction entre le portail intégré et le portail externe devient essentielle. Avec le portail Hotspot UniFi intégré, la page de connexion est directement hébergée par l'application réseau UniFi. C'est fonctionnel, rapide à configurer, mais 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 pertinentes au-delà du nombre de sessions.

Lorsque vous configurez un serveur de portail externe (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 totalement distincte. Dans notre cas, il s'agit de Purple. L'URL que vous saisissez dans le champ du serveur de portail externe 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 du point d'accès (AP), l'adresse MAC de l'appareil client, un horodatage Unix, l'URL d'origine que le client tentait de joindre 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 page de connexion appropriée, gère l'authentification, puis effectue un appel API vers l'application UniFi Network pour autoriser cette adresse MAC.

Cet appel API est l'étape d'authentification (handshake) cruciale. Depuis la version 9.1 de l'application UniFi Network, 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 1 de l'API des sites, ciblant l'ID client spécifique, avec un corps JSON permettant de 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 transmet l'instruction au point d'accès, et le statut de l'invité passe de « en attente » à « autorisé ». L'accès Internet est accordé.

Parlons maintenant du Walled Garden (espace sécurisé), qu'UniFi appelle l'accès de pré-autorisation. Il s'agit de la liste blanche de domaines et d'adresses IP que les invités peuvent consulter avant de s'authentifier. C'est un élément essentiel, et l'une des sources d'erreur de configuration les plus courantes.

Au minimum, votre walled garden doit inclure le nom de domaine complet (FQDN) de votre portail Purple, ainsi que les adresses IP ou plages CIDR vers lesquelles l'infrastructure de Purple pointe. 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 d'adresses 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 le point d'accès intercepte uniquement le trafic HTTP en clair 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 considérer qu'il n'y a pas de Captive Portal et ne pas afficher l'invitation à se connecter.

La solution consiste à s'assurer que votre walled garden inclut les domaines de détection de Captive Portal des principaux systèmes d'exploitation, et que votre portail Purple soit accessible en HTTPS avec un certificat SSL valide et approuvé. Les certificats auto-signés provoqueront des avertissements de sécurité sur les navigateurs qui bloqueront le chargement du portail. C'est une condition non négociable pour les déploiements en production.

L'autre considération spécifique à UniFi concerne l'accessibilité du contrôleur. L'Application Réseau UniFi — 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 concernés sont accessibles. Pour les contrôleurs auto-hébergés, il s'agit généralement du port 8443 pour l'API héritée, 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 — ce qui est pertinent lorsque vous déployez Purple aux côtés de SSIDs WPA2-Enterprise ou WPA3-Enterprise plutôt que selon le modèle de SSID invité ouvert — le serveur RADIUS intégré d'UniFi prend en charge les méthodes EAP 802.1X standard. 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 l'AP 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]

Laissez-moi vous présenter la liste de contrôle pratique pour la mise en œuvre, que je passerais en revue avec tout client déployant Purple sur UniFi.

Premièrement, la segmentation du réseau. Votre SSID invité doit se trouver 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 avoir un FQDN valide et un certificat SSL de confiance. Ne vous fiez pas à l'adresse IP. Utilisez un nom de domaine approprié, obtenez un certificat Let's Encrypt ou commercial pour celui-ci, et configurez UniFi pour utiliser ce certificat. Cela résout la majorité des problèmes de redirection HTTPS.

Troisièmement, construisez soigneusement votre walled garden et testez-le. Les entrées minimales sont : le domaine de votre portail Purple et ses plages IP, les domaines de détection de Captive Portal 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 dans le walled garden lors des tests.

Quatrièmement, pour l'intégration de l'API, utilisez un compte administrateur local dédié dans l'Application Réseau UniFi avec les autorisations minimales requises. N'utilisez pas vos identifiants d'administrateur principaux. Si vous utilisez l'Application Réseau 9.1 ou une version ultérieure, utilisez le nouveau mécanisme de clé API sous Plan de contrôle, Intégrations — c'est plus sécurisé et cela ne nécessite pas d'authentification basée sur des identifiants.

Cinquièmement, tenez compte de la durée de session. L'expiration par défaut des sessions invités de UniFi peut être de seulement huit heures. Pour les déploiements dans le secteur de l'hôtellerie où les clients séjournent 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 transmises correctement dans l'appel d'autorisation API.

Le piège le plus courant que je constate 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 de passer en production.

[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 de l'External Portal Server. L'application Network fonctionne 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 lieu est configuré comme un site distinct dans Purple, associé 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 Captive Portal de 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 d'invités. Le WPA3 Enterprise utilise 802.1X et RADIUS, ce qui correspond à un flux d'authentification différent.

[RÉSUMÉ & PROCHAINES ÉTAPES — environ 1 minute]

Pour résumer : le déploiement de Purple en tant que Captive Portal externe sur UniFi est une intégration bien prise en charge et à l'architecture solide. Les étapes clés sont : configurer votre SSID invité avec l'option External Portal Server pointant vers l'URL de votre portail Purple, créer un walled garden complet qui couvre l'infrastructure de Purple et tous les fournisseurs OAuth que vous utilisez, vous assurer que votre contrôleur UniFi dispose d'un certificat SSL valide et est accessible depuis les serveurs API de Purple, et configurer 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 conforme aux réglementations et axée sur l'analyse qui s'intègre à votre CRM, capture des données de première main conformément au consentement GDPR, et fournit les analyses de fréquentation et de temps de séjour dont les exploitants de sites et les équipes marketing ont réellement besoin.

Si vous êtes un MSP ou un intégrateur système déployant UniFi à grande échelle, la gestion multi-site et les fonctionnalités de marque blanche de Purple 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 des guides d'intégration API, visitez purple.ai. Merci pour votre écoute.

Points clés à retenir

✓L'intégration de Purple avec Ubiquiti UniFi utilise la fonctionnalité External Portal Server pour acheminer l'authentification des invités via le cloud sécurisé de Purple.
✓Les clients non authentifiés sont placés dans un état de quarantaine où l'AP UniFi intercepte le trafic DNS et HTTP, émettant une redirection 302 vers Purple.
✓Une liste complète d'accès de pré-autorisation (Walled Garden) est obligatoire pour permettre aux clients d'atteindre Purple et les fournisseurs d'identité tiers (Google, Facebook) avant l'authentification.
✓Un certificat SSL de confiance publique sur le contrôleur UniFi est non négociable afin d'éviter les avertissements de sécurité du navigateur pendant le flux de redirection.
✓L'autorisation API est établie en utilisant soit les clés API REST modernes d'UniFi (Network Application 9.1+) soit un compte administrateur local dédié pour les systèmes existants.
✓Le déploiement de Purple ajoute des analyses avancées de fréquentation, de l'automatisation marketing, de l'intégration CRM et de la conformité multi-sites sur le matériel haute performance d'UniFi.

📚 Part of our core series: Multi-Tenant WiFi →

Synthèse de haut niveau

Alors que les espaces physiques d'entreprise — allant des grandes chaînes de vente au détail [1] et des groupes hôteliers multi-sites [2] aux principaux hubs de transport [3] et institutions éducatives [4] — cherchent à maximiser la valeur de leur infrastructure sans fil, les limites des contrôleurs de hotspot intégrés deviennent un goulot d'étranglement opérationnel majeur. L'écosystème Ubiquiti UniFi fournit un matériel hautement fiable, rentable et évolutif. Cependant, son portail invité natif ne dispose pas de la capture de données avancée, des analyses multi-sites, de l'intégration CRM, de la conformité mondiale en matière de confidentialité (GDPR, CCPA, PCI DSS) et des capacités de monétisation requises par les opérations d'entreprise modernes.

Ce guide de référence technique propose un parcours architectural complet pour superposer la Plateforme d'Intelligence Enterprise WiFi de Purple [5] sur une architecture réseau Ubiquiti UniFi. En utilisant la fonctionnalité de Serveur de Portail Externe de UniFi, les architectes réseau et les intégrateurs de systèmes peuvent contourner les limites du contrôleur local. Cette intégration oriente l'authentification des invités vers le moteur d'identité et d'analyse sécurisé et hébergé dans le cloud de Purple, transformant un simple service utilitaire en un actif marketing et opérationnel de classe entreprise.

Analyse technique approfondie

Pour déployer un Captive Portal externe sécurisé et stable, les ingénieurs réseau doivent comprendre la communication de bas niveau et les transitions d'état qui se produisent lorsqu'un client non authentifié se connecte au réseau sans fil.

Le cycle de vie de la connexion et de la redirection des invités

Le flux de travail du Captive Portal UniFi fonctionne sur un modèle strict basé sur des états. Lorsqu'un client s'associe à un SSID configuré pour les invités, le processus séquentiel suivant est initié :

Phase	Composant	Action / Transition d'état	Mécanisme technique
1. Association	Client & Point d'accès	Le client s'associe au SSID ; le serveur DHCP attribue l'adresse IP, le masque de sous-réseau, la passerelle et les serveurs DNS.	Association standard 802.11 et bail DHCP.
2. Quarantaine	Point d'accès UniFi (AP)	L'AP place l'adresse MAC du client dans un état de Quarantaine / En attente (`authorized: false`).	Règles de blocage de Couche 2/3 appliquées localement sur l'interface virtuelle de l'AP.
3. Interception DNS	Démon local de l'AP	L'AP exécute un processus DNSmasq local qui intercepte toutes les requêtes DNS des clients en attente.	L'AP redirige tout le trafic du port 53 (UDP/TCP) vers son résolveur DNS local, quels que soient les paramètres DNS du client.
4. Interception HTTP	Redirecteur d'AP	L'AP exécute un démon de redirection HTTP léger sur le port 80.	Toute requête HTTP effectuée par le client est interceptée. L'AP répond par une redirection HTTP 302 Found.
5. Redirection	Navigateur client	Le navigateur du client (ou l'assistant de Captive Portal du système d'exploitation) est redirigé vers l'URL du portail externe configuré.	L'URL de redirection 302 est complétée par des paramètres de requête critiques contenant les métadonnées du client et de l'AP.
6. Authentification	Portail externe (Purple)	Le client interagit avec la page d'accueil Purple, complétant l'authentification (ex. connexion sociale, inscription par e-mail, OTP par SMS).	Session HTTPS sécurisée hébergée sur l'infrastructure cloud de Purple.
7. API Handshake	Cloud Purple & Contrôleur UniFi	Purple valide les identifiants et émet un appel API sécurisé vers l'application réseau UniFi.	Appel REST API (requête POST) contenant l'adresse MAC du client, l'ID du site et les paramètres de session.
8. Autorisation	Contrôleur UniFi & AP	Le contrôleur UniFi met à jour l'état du client sur `authorized: true` et pousse l'ACL mise à jour vers l'AP.	L'AP supprime les blocages de Couche 2/3 pour l'adresse MAC du client, accordant un routage complet vers la passerelle Internet.

Les paramètres de requête de redirection

Lorsque l'AP UniFi émet la redirection HTTP 302, elle ajoute un ensemble standardisé de paramètres de requête à l'URL du portail externe. Le portail externe doit capturer ces paramètres pour identifier le client et effectuer l'autorisation API ultérieure :

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&amp;id=1c:71:25:63:e4:24&amp;t=1742398732&amp;url=http://connectivitycheck.gstatic.com%2F&amp;ssid=purple-guest

ap : L'adresse MAC de l'Access Point UniFi spécifique auquel le client est associé.
id : L'adresse MAC de l'appareil client demandant l'accès au réseau.
t : Un horodatage d'époque Unix représentant l'heure d'initiation de la redirection, utilisé pour la vérification de la sécurité.
url : L'URL d'origine à laquelle le client a tenté d'accéder (souvent un point de terminaison de détection de Captive Portal du système d'exploitation).
ssid : Le nom du SSID auquel le client s'est connecté, permettant au portail de présenter une image de marque spécifique au site.

Le Walled Garden (Contrôle d'accès de pré-autorisation)

Avant qu'un client ne soit autorisé, tout le trafic est bloqué à l'exception des destinations explicitement définies dans la liste de Contrôle d'accès de pré-autorisation (communément appelée Walled Garden). Étant donné que les appareils clients modernes exécutent des assistants de Captive Portal (CPA) automatisés qui testent la connectivité via HTTPS, et que l'authentification externe repose souvent sur des fournisseurs d'identité tiers (IdP), la configuration d'un walled garden robuste et précis est essentielle.

Si un domaine ou une plage IP requis est omis du walled garden, la page d'accueil ne se chargera pas, les boutons de connexion sociale se figeront ou l'appareil client abandonnera complètement la connexion WiFi, supposant un réseau défectueux.

Guide d'implémentation

Cette section décrit la configuration étape par étape requise pour intégrer le Captive Portal externe de Purple avec l'application réseau Ubiquiti UniFi (Contrôleur).

Étape 1 : Segmentation du réseau et configuration du VLAN

Pour garantir une sécurité et une conformité de niveau entreprise (telles que PCI DSS et le GDPR), le trafic invité doit être complètement isolé des ressources de l'entreprise, des systèmes de point de vente et des réseaux IoT.

Accédez à Settings > Networks dans l'application réseau UniFi.
Cliquez sur Create New Network.
Configurez les paramètres réseau comme suit :
- Name : Purple Guest Network
- VLAN ID : 90 (ou tout autre tag VLAN invité dédié)
- Network Type : Guest (ceci applique automatiquement l'isolation des clients, empêchant la communication d'invité à invité).
- Gateway IP/Subnet : Configurez un sous-réseau approprié (par exemple, 10.90.0.1/22 pour prendre en charge jusqu'à 1022 baux d'invités simultanés).
- DHCP Range : Activez le DHCP et définissez la plage (par exemple, 10.90.0.10 à 10.90.3.254).
- DNS Server : Configurez des résolveurs publics fiables (par exemple, Cloudflare 1.1.1.1 et Google 8.8.8.8) pour garantir une résolution DNS rapide.

Étape 2 : Configuration du SSID Invité

Accédez à Settings > WiFi et cliquez sur Create New WiFi Network.
Configurez les paramètres du SSID :
- Name (SSID) : Purple Guest WiFi
- Security Protocol : Open (le captive portal gérera l'authentification).
- Network : Sélectionnez le Purple Guest Network (VLAN 90) créé à l'étape 1.
- Client Device Isolation : Assurez-vous que cette option est activée (ON).
Faites défiler vers le bas jusqu'à Hotspot Portal et cochez la case Enable Captive Portal.

Étape 3 : Configuration du serveur de portail externe

Une fois le Hotspot Portal activé, vous devez rediriger l'authentification vers les serveurs cloud sécurisés de Purple.

Accédez à Settings > Profiles > Guest Hotspot (ou Settings > Guest Control dans les anciennes versions du contrôleur).
Sous Authentication, sélectionnez External Portal Server.
Configurez les champs suivants :
- IP / FQDN : Saisissez le FQDN fourni par Purple (par exemple, portal.purplehotspot.com).
- Use Secure Portal (HTTPS) : Activez (ON) (Obligatoire pour la sécurité et la compatibilité avec les navigateurs modernes).
- Redirect Using Hostname : Activez (ON) et saisissez le FQDN portal.purplehotspot.com.
- Port : 443 (HTTPS standard).
- HTTPS Redirection : Activez (ON) (cela permet au point d'accès d'intercepter les requêtes HTTPS initiales et de les rediriger, bien que cela nécessite une gestion DNS rigoureuse).

Étape 4 : Configuration de l'accès de pré-autorisation (Walled Garden)

Pour permettre aux invités non authentifiés de charger la page de démarrage de Purple et de s'authentifier via des fournisseurs d'identité tiers, ajoutez les domaines et plages d'adresses IP suivants à la liste Pre-Authorization Access sous Settings > Profiles > Guest Hotspot > Pre-Authorization Access :

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
  "ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

Note : Pour les déploiements utilisant le traitement des paiements Stripe, ajoutez *.stripe.com et *.stripe.network à la liste de pré-autorisation.

Étape 5 : Établissement de la liaison API

Pour que Purple autorise les visiteurs, ses serveurs cloud doivent communiquer avec votre application UniFi Network.

Pour l'application UniFi Network 9.1 et ultérieure (API REST recommandée)

Dans le contrôleur UniFi, accédez à Paramètres > Plan de contrôle > Intégrations.
Sous la section Clés API, cliquez sur Générer une nouvelle clé API.
Attribuez un nom (par exemple, Clé d'intégration Purple) et définissez les autorisations sur Administrateur.
Copiez la clé API générée.
Connectez-vous à votre Portail Purple, accédez à Paramètres du site > Intégration > Ubiquiti UniFi, puis collez la clé API ainsi que le FQDN public de votre contrôleur UniFi (par exemple, unifi.votredomaine.com:443).

Pour les contrôleurs hérités (API basée sur les identifiants)

Accédez à Paramètres > Système > Administrateurs.
Créez un compte d'administrateur local dédié (par exemple, purple_api).
Attribuez les privilèges d'Administrateur ou d'Opérateur de point d'accès.
Configurez un mot de passe fort et unique.
Dans le Portail Purple, saisissez ces identifiants sous l'onglet d'intégration UniFi.

Bonnes pratiques

1. Exigences relatives aux certificats SSL

N'utilisez jamais de certificat SSL auto-signé sur un contrôleur UniFi de production ou un serveur de portail externe. Les navigateurs web modernes et les assistants de portail captif (CPA) des systèmes d'exploitation imposent une validation SSL/TLS stricte. Un certificat auto-signé déclenchera un avertissement de sécurité très visible (par exemple, "Votre connexion n'est pas privée"), entraînant des taux d'abandon élevés et nuisant à l'image de marque.

Déployez un certificat SSL valide et publiquement approuvé (par exemple, Let's Encrypt ou un certificat d'autorité de certification commerciale) sur le FQDN du contrôleur UniFi.
Assurez-vous que le FQDN du contrôleur se résout correctement à la fois depuis le VLAN invité interne et depuis l'internet public.

2. Configuration du DNS

Une résolution DNS lente est la cause principale de la lenteur de redirection du portail captif.

Ne dirigez pas le DNS invité vers l'adresse IP locale de la passerelle UniFi, sauf si la passerelle dispose d'un transfert DNS haute performance configuré.
Configurez plutôt la plage DHCP invité pour distribuer directement aux clients des serveurs DNS publics rapides et résilients (par exemple, Principal : 1.1.1.1, Secondaire : 8.8.8.8).

3. Configuration du Wi-Fi invité RADIUS (alternative d'entreprise)

Pour les sites nécessitant une sécurité 802.1X basée sur des certificats ou des identifiants plutôt qu'un SSID ouvert avec un portail web, UniFi prend en charge l'intégration Cloud RADIUS externe [6].

Configurez un Profil RADIUS sous Paramètres > Profils > RADIUS.
Saisissez les adresses IP et les secrets partagés des serveurs RADIUS principal et secondaire fournis par Purple.
Activez la comptabilité RADIUS (Accounting) et réglez l'intervalle de mise à jour intermédiaire (Interim Update Interval) sur 300 secondes pour garantir un suivi des sessions en temps réel.
Sous les paramètres du SSID, réglez le protocole de sécurité sur WPA2 Enterprise ou WPA3 Enterprise [7] et sélectionnez le profil RADIUS.

Dépannage et atténuation des risques

Lors du déploiement de Captive Portals externes, les administrateurs réseau rencontrent fréquemment plusieurs modes de défaillance courants. Le tableau ci-dessous détaille ces problèmes, leurs causes profondes et les mesures d'atténuation exactes :

Symptôme	Analyse de la cause profonde	Action corrective et atténuation
Écran blanc / Échec du chargement du portail	L'appareil client ne peut pas résoudre ou atteindre le FQDN du serveur de portail externe.	1. Vérifiez que `portal.purplehotspot.com` figure dans la liste d'accès de pré-autorisation (Pre-Authorization Access). 2. Assurez-vous que le client invité a reçu une adresse IP et un serveur DNS valides via DHCP. 3. Effectuez une recherche DNS sur l'appareil client pour vérifier la résolution du FQDN du portail.
Erreur SSL "Connexion non privée"	Le contrôleur UniFi utilise un certificat auto-signé, ou le FQDN de redirection ne correspond pas au nom commun (Common Name) du certificat SSL.	1. Installez un certificat SSL publiquement approuvé sur le contrôleur UniFi. 2. Vérifiez que l'option Rediriger à l'aide du nom d'hôte (Redirect Using Hostname) est activée et correspond exactement au FQDN du certificat. 3. Désactivez "Rediriger HTTPS (Redirect HTTPS)" dans les paramètres de contrôle des invités UniFi pour empêcher le point d'accès de tenter d'intercepter le trafic HTTPS sur le port 443, ce qui déclenche naturellement des avertissements SSL.
Authentification réussie, mais l'accès Internet est bloqué	Le cloud Purple a pu authentifier l'utilisateur, mais l'appel API pour autoriser l'adresse MAC du client sur le contrôleur UniFi a échoué.	1. Vérifiez les règles du pare-feu pour vous assurer que le port `443` (ou `8443` pour l'héritage) est ouvert en entrée vers le contrôleur UniFi depuis les plages IP de Purple. 2. Vérifiez que la clé API ou les identifiants d'administrateur local saisis dans le portail Purple sont valides et disposent des autorisations d'administrateur. 3. Consultez les journaux du contrôleur UniFi (`server.log`) pour rechercher d'éventuels échecs d'authentification API.
Échec des boutons de connexion sociale (ex. Google)	Les domaines d'authentification du fournisseur d'identité (IdP) sont bloqués par la liste de contrôle d'accès du point d'accès.	1. Ajoutez les domaines génériques (wildcard) complets pour l'IdP spécifique à la liste d'accès de pré-autorisation (ex. `.google.com`, `.googleapis.com`). 2. Si vous utilisez Facebook, assurez-vous que les domaines du SDK Facebook sont entièrement autorisés.
Déconnexions fréquentes / Demandes de réauthentification	Le délai d'expiration de la session du contrôleur UniFi est plus court que la durée de la session Purple, ou les temps de bail DHCP sont trop courts.	1. Alignez le paramètre Session Timeout du hotspot invité UniFi avec la politique de session Purple (par ex., 24 heures). 2. Augmentez le temps de bail DHCP sur le VLAN invité à au moins 12 ou 24 heures pour éviter l'épuisement des adresses IP et la réauthentification en milieu de session.

ROI et impact commercial

Bien que le déploiement d'un Captive Portal externe nécessite une ingénierie réseau rigoureuse, les résultats commerciaux et le retour sur investissement (ROI) l'emportent largement sur la complexité initiale de la mise en œuvre.

Capture de données d'entreprise et enrichissement CRM

Le portail invité natif UniFi est un outil « aveugle » ; il accorde un accès internet sans capturer l'identité de l'utilisateur. En y superposant Purple, les établissements peuvent capturer des données de première main précieuses (e-mails, numéros de téléphone, profils sociaux) de manière entièrement conforme au GDPR et à la CCPA. Ces données sont automatiquement synchronisées en temps réel avec les systèmes CRM, les plateformes marketing (par ex., Salesforce, HubSpot, Mailchimp) et les programmes de fidélité, permettant des campagnes marketing hautement ciblées qui stimulent les visites répétées et la valeur de vie client.

Gestion multi-site et marque blanche

Pour les fournisseurs de services gérés (MSP) et les opérateurs d'entreprises multi-sites, la gestion du WiFi invité sur des centaines d'établissements via des contrôleurs UniFi individuels est très inefficace. Purple fournit un tableau de bord cloud unique et centralisé pour gérer les pages d'accueil, les conditions de conformité et les analyses pour tous les établissements dans le monde entier, quelle que soit la distribution du contrôleur UniFi sous-jacent.

Analyses en temps réel et intelligence spatiale

Purple transforme le réseau sans fil UniFi en un puissant réseau de capteurs. En analysant les requêtes de sonde (probe requests) et les métadonnées de connexion, Purple fournit une intelligence spatiale approfondie, notamment :

Analyses de fréquentation : Nombre total de visiteurs, trafic de passage et taux de conversion (passage vers entrée).
Temps de séjour : Durée moyenne des visites, segmentée par type de client (nouveau vs. récurrent).
Récence et fréquence : Fréquence de retour des clients et temps écoulé entre les visites.
Cartes thermiques des établissements : Représentation visuelle du flux et de la densité des visiteurs, permettant aux exploitants de commerces et d'établissements d'optimiser l'agencement et la dotation en personnel.

Monétisation via les réseaux de médias de détail

Pour les grands établissements tels que les stades, les centres commerciaux et les aéroports, la page d'accueil du Captive Portal représente un espace numérique de grande valeur. Purple permet aux établissements de monétiser cet espace en s'intégrant aux réseaux de médias de détail, en diffusant des publicités programmatiques ciblées, des expériences de connexion sponsorisées et des promotions localisées directement aux invités au moment de la connexion.

Références

[1] Purple pour le commerce de détail : Marketing WiFi et analyses pour les commerces de détail
[2] Purple pour l'hôtellerie : Solutions de WiFi invité d'entreprise pour les hôtels et restaurants
[3] Purple for Transport : WiFi public et analyses pour les hubs de transport
[4] Purple for Healthcare : Solutions WiFi pour les patients et visiteurs des établissements de santé
[5] Purple Core Products : Plateforme WiFi invité pour entreprise
[6] Guide d'intégration Cloud RADIUS : Comment implémenter l'authentification 802.1X avec Cloud RADIUS
[7] Meilleures pratiques de contrôle d'accès au réseau : Top 10 des solutions de contrôle d'accès au réseau (NAC) pour 2026
[8] Référence Cisco sans fil (architecture comparative) : Points d'accès sans fil Cisco : Guide 2026 des produits et du déploiement
[9] Référence WiFi dans l'éducation : Le WiFi dans les écoles : Le guide 2026 de l'administrateur et de l'IT
[10] Purple Analytics Platform : Plateforme d'analyse et de marketing WiFi

Définitions clés

Captive Portal

Une page web qui intercepte la connexion réseau initiale d'un invité et nécessite une authentification, une inscription ou l'acceptation des conditions d'utilisation avant d'accorder un accès complet à Internet.

Rencontré immédiatement lors de la connexion à un SSID invité ouvert ; géré par le redirecteur de l'AP et le serveur de portail externe.

External Portal Server

Une application web tierce (telle que Purple) qui héberge la splash page des invités et gère l'authentification des utilisateurs, contournant ainsi les limitations du portail du contrôleur intégré.

Configuré dans les paramètres UniFi Guest Hotspot pour remplacer la page d'accueil UniFi native.

Walled Garden (Pre-Authorization Access)

Une liste blanche de domaines, sous-domaines ou adresses IP auxquels les clients non authentifiés peuvent accéder avant de terminer le processus de connexion au Captive Portal.

Indispensable pour charger la page du portail elle-même, les ressources CSS/JS et les points de terminaison de connexion OAuth tiers.

DNSmasq

Un redirecteur DNS et serveur DHCP léger exécuté localement sur les points d'accès UniFi pour intercepter et rediriger les requêtes DNS des invités pendant l'état de pré-autorisation.

Gère la redirection DNS initiale qui force les appareils clients à déclencher leurs assistants de Captive Portal intégrés.

API Authorization Handshake

Le processus par lequel le serveur de portail externe (Purple) effectue un appel API sécurisé vers le contrôleur UniFi pour faire passer l'adresse MAC d'un client de l'état « quarantaine » à l'état « autorisé ».

Se produit immédiatement après que l'utilisateur a réussi le processus de connexion sur la splash page.

Client Device Isolation

Une fonctionnalité de sécurité qui empêche les clients sans fil sur le même SSID ou VLAN de communiquer entre eux, atténuant ainsi le risque d'attaques sur le réseau local.

Activé dans les paramètres UniFi WiFi et réseau pour protéger la confidentialité des invités et sécuriser le réseau de l'établissement.

RADSEC (RADIUS over TLS)

Un protocole qui sécurise le trafic d'authentification et de comptabilité RADIUS en l'enveloppant dans un tunnel TLS sécurisé, empêchant ainsi l'écoute clandestine et l'altération sur les réseaux publics.

Pris en charge dans UniFi Network 8.4+ pour les déploiements d'entreprise multi-sites sécurisés utilisant WPA2/WPA3 Enterprise.

CPA (Captive Portal Assistant)

Un utilitaire de système d'exploitation intégré sur iOS, Android, Windows et macOS qui détecte automatiquement un Captive Portal en tentant de récupérer un point de terminaison HTTP/HTTPS connu.

Déclenche la fenêtre contextuelle « Se connecter au WiFi » sur l'appareil de l'utilisateur immédiatement après la connexion.

Exemples concrets

Un centre commercial à forte fréquentation équipé de 150 AP UniFi et d'une application réseau UniFi auto-hébergée sur AWS doit déployer Purple. L'équipe informatique souhaite utiliser la connexion via les réseaux sociaux Google et Facebook pour l'authentification des invités. Cependant, lors des tests initiaux, les invités qui cliquent sur les boutons de connexion sociale se retrouvent face à un écran blanc ou à une erreur de résolution DNS.

Ce problème est causé par un Walled Garden (Pre-Authorization Access) trop restrictif qui empêche l'appareil de l'invité de résoudre ou d'atteindre les points de terminaison d'authentification de Google et Facebook avant d'être autorisé. Pour résoudre ce problème, l'administrateur réseau doit se connecter à l'application réseau UniFi, aller dans Settings > Profiles > Guest Hotspot, puis développer la section Pre-Authorization Access. Il doit ajouter les domaines génériques complets pour les fournisseurs d'identité Google et Facebook. Pour Google, cela inclut accounts.google.com, ssl.gstatic.com et *.googleapis.com. Pour Facebook, cela nécessite *.facebook.com, *.facebook.net et *.fbcdn.net. De plus, assurez-vous que la plage DHCP du réseau invité est configurée pour distribuer des serveurs DNS publics rapides (par exemple, 1.1.1.1 et 8.8.8.8) directement aux clients, plutôt que de les orienter vers la passerelle UniFi locale, qui peut devenir un goulot d'étranglement pour les requêtes DNS de pré-autorisation.

Commentaire de l'examinateur : Il s'agit d'un échec classique lié à un manque dans le Walled Garden. Étant donné que les flux de connexion sociale reposent sur des redirections OAuth complexes à travers plusieurs sous-domaines, l'omission d'un seul domaine de diffusion de contenu (comme le CDN de Facebook `fbcdn.net`) empêchera le rendu de la page. Les architectes réseau doivent toujours utiliser des caractères génériques (`*.domain.com`) lorsque le contrôleur le permet, et vérifier la résolution DNS depuis un client non authentifié à l'aide d'outils standards comme `nslookup` ou `dig` sur les domaines autorisés.

Un MSP déploie Purple dans une chaîne de 50 hôtels de charme. Chaque hôtel dispose d'une passerelle locale UniFi Cloud Gateway Max sur site. Le MSP souhaite gérer tous les sites à partir d'un seul compte Purple mais s'inquiète de la sécurité et de la manière dont le cloud de Purple communiquera avec les contrôleurs locaux individuels pour autoriser les adresses MAC des invités, étant donné que les passerelles locales sont derrière des IP publiques dynamiques avec NAT.

L'architecture optimale utilise l'API REST officielle d'UniFi avec redirection de port entrant ou un reverse proxy, combiné à un DNS dynamique (DDNS). Pour chaque hôtel : 1) Configurez un nom d'hôte DDNS sur la Cloud Gateway Max (par exemple, hotel01.mspdomain.com) afin que l'IP publique de la passerelle soit toujours traçable. 2) Configurez une règle de redirection de port sur la passerelle pour rediriger le trafic HTTPS entrant sur un port élevé et non standard (par exemple, 10443) vers l'IP d'administration de la passerelle locale sur le port 443. 3) Dans le contrôleur UniFi, allez dans Settings > Control Plane > Integrations et générez une clé API unique. 4) Dans le portail Purple, configurez un site (Venue) unique pour chaque hôtel, en sélectionnant l'intégration Ubiquiti UniFi. Saisissez l'adresse DDNS unique avec le port redirigé (par exemple, hotel01.mspdomain.com:10443) et la clé API spécifique générée pour ce site. Enfin, sécurisez la redirection de port entrant sur chaque passerelle en limitant les IP sources aux plages d'adresses IP du cloud public de Purple, empêchant ainsi tout accès non autorisé depuis le reste d'internet.

Commentaire de l'examinateur : L'utilisation d'un port élevé et non standard pour la redirection de port, combinée à une restriction stricte des IP sources pour n'autoriser que les blocs d'IP cloud de Purple, atténue les risques de sécurité liés à l'exposition du port de l'API du contrôleur sur l'internet public. Cette architecture évite d'avoir recours à des adresses IP publiques statiques coûteuses sur chaque site tout en conservant des capacités d'autorisation MAC robustes et en temps réel.

Questions d'entraînement

Q1. Un administrateur réseau a configuré un Captive Portal externe sur un réseau invité UniFi. Lors des tests, il constate que la splash page du Captive Portal se charge correctement, mais après que l'invité a saisi son adresse e-mail et cliqué sur « Se connecter », le navigateur se fige et finit par afficher une erreur de délai d'attente dépassé. Le client reste en quarantaine. Quelle est la cause la plus probable de ce problème et comment doit-on l'étudier ?

Conseil : La page du portail s'est chargée, ce qui signifie que le DNS et le walled garden fonctionnent. L'échec se produit *après* que l'invité a soumis ses identifiants.

Voir la réponse type

La cause la plus probable est un échec de la liaison d'autorisation (handshake) API entre le cloud Purple et le contrôleur UniFi. Comme la page du portail s'est chargée et que l'invité a pu interagir avec elle, les configurations DNS et d'accès de pré-autorisation (Walled Garden) sont correctes. Cependant, lorsque l'invité termine l'authentification, Purple tente d'envoyer un appel API REST sécurisé (requête POST) au contrôleur UniFi pour autoriser l'adresse MAC du client. Si le contrôleur UniFi est derrière un pare-feu, un NAT ou sur un réseau privé sans redirection de port appropriée, ou si les identifiants API (ou la clé API) sont incorrects, la demande d'autorisation échouera ou expirera. Pour enquêter : 1) Vérifiez que le FQDN et le port du contrôleur UniFi sont accessibles publiquement depuis les plages d'adresses IP de Purple. 2) Vérifiez les règles de pare-feu entrantes sur la passerelle protégeant le contrôleur UniFi pour vous assurer que le port 443 (ou 8443) est ouvert. 3) Dans le portail Purple, vérifiez que les paramètres d'intégration d'UniFi contiennent la clé API ou les identifiants d'administrateur corrects et que l'URL du contrôleur est exacte. 4) Inspectez le fichier server.log du contrôleur UniFi pour détecter d'éventuelles tentatives de connexion entrantes ou des erreurs d'authentification API provenant des adresses IP de Purple.

Q2. Un déploiement en entreprise nécessite la mise en place d'un réseau invité avec un Captive Portal externe. L'architecte réseau souhaite utiliser le protocole HTTPS pour l'ensemble du trafic du Captive Portal afin de bloquer l'interception des identifiants. Il active les options « Use Secure Portal (HTTPS) » et « Redirect Using Hostname » dans UniFi, en pointant vers le FQDN du portail externe. Pourtant, lors de la connexion des clients, leurs navigateurs affichent immédiatement un avertissement bloquant de type « SSL Certificate Common Name Mismatch » ou « Certificate Not Trusted ». Comment résoudre ce problème ?

Conseil : Pensez au périphérique qui gère la redirection initiale et au certificat SSL qu'il présente au client.

Voir la réponse type

Ce problème se produit car le point d'accès ou le contrôleur UniFi tente d'intercepter une requête HTTPS du client pour la rediriger vers le Captive Portal. Lorsqu'un client se connecte et tente de visiter un site Web HTTPS (par exemple, https://www.google.com), le redirecteur du point d'accès intercepte le trafic. Pour effectuer la redirection en HTTPS, le point d'accès doit présenter un certificat SSL. Étant donné que le point d'accès ne possède pas de certificat SSL valide pour www.google.com, le navigateur du client détecte une condition de type Man-in-the-Middle (MITM) et affiche un avertissement SSL critique. Pour résoudre ce problème : 1) Assurez-vous que le contrôleur UniFi lui-même dispose d'un certificat SSL valide et publiquement approuvé qui correspond à son FQDN configuré. 2) Dans les paramètres du réseau invité UniFi, désactivez l'option « Redirect HTTPS » (laissez uniquement la redirection HTTP activée). Cela empêche le point d'accès de tenter d'intercepter le trafic HTTPS. À la place, le réseau s'appuiera sur l'assistant de Captive Portal (CPA) du système d'exploitation du périphérique client, qui teste la connectivité à l'aide de points de terminaison HTTP simples (par exemple, http://captive.apple.com ou http://connectivitycheck.gstatic.com). Le point d'accès peut alors intercepter ces requêtes HTTP sur le port 80 en toute sécurité et les rediriger vers l'URL HTTPS sécurisée du portail Purple (https://portal.purplehotspot.com) sans déclencher d'avertissement SSL sur le navigateur.

Q3. Une chaîne hôtelière souhaite déployer la sécurité WPA3-Enterprise pour son réseau invité VIP tout en conservant l'intégration avec la plateforme d'analyse de Purple. L'équipe informatique locale ne sait pas s'il est possible d'utiliser la redirection classique de serveur de Captive Portal externe avec le WPA3-Enterprise. Quelle est l'approche architecturale correcte pour ce scénario ?

Conseil : Le WPA3-Enterprise utilise l'authentification 802.1X, qui intervient lors de la phase d'association, avant l'attribution d'une adresse IP. Cela est fondamentalement différent d'un SSID ouvert avec un Captive Portal.

Voir la réponse type

Le WPA3-Enterprise (et le WPA2-Enterprise) utilise l'authentification 802.1X, qui est fondamentalement incompatible avec la redirection web standard d'un Captive Portal. Dans un réseau 802.1X, l'authentification a lieu lors de la phase d'association (couche 2) à l'aide de méthodes EAP (telles que EAP-TLS ou PEAP) avant que le client ne se voie attribuer une adresse IP ou ne soit autorisé sur le réseau. Par conséquent, vous ne pouvez pas rediriger un client vers une page d'accueil web. Pour intégrer WPA3-Enterprise à Purple : 1) Passez du modèle "External Portal Server" à un modèle RADIUS externe. 2) Configurez un profil RADIUS dans l'application réseau UniFi, en saisissant les adresses IP du serveur Cloud RADIUS de Purple, les ports d'authentification (généralement 1812), les ports de comptabilité (généralement 1813) et le secret partagé. 3) Activez la comptabilité RADIUS (RADIUS Accounting) et définissez un intervalle de mise à jour intermédiaire (Interim Update Interval) de 300 secondes. 4) Configurez le SSID VIP pour utiliser WPA3 Enterprise et sélectionnez le profil RADIUS. Lorsqu'un invité VIP se connecte, son appareil s'authentifie directement auprès du serveur Cloud RADIUS de Purple en utilisant ses identifiants d'entreprise uniques ou son certificat. Le serveur RADIUS de Purple autorise la connexion et reçoit les mises à jour de comptabilité, permettant ainsi au site de capturer les analyses de connexion, la durée des sessions et l'utilisation des données sans nécessiter de page d'accueil web.

Continuer la lecture de cette série

Intégration de CommScope Ruckus avec Purple WiFi : Guide d'installation et de configuration

Ce guide de référence technique fournit un manuel de configuration faisant autorité pour l'intégration des architectures CommScope Ruckus avec Purple WiFi. Il détaille les déploiements étape par étape pour les Captive Portals de WiFi invité, le WiFi personnel sécurisé via 802.1X et l'isolation réseau multi-locataire à l'aide de Ruckus Dynamic PSK.

Intégration des points d'accès Allied Telesis avec Purple WiFi

Ce guide fournit un manuel de configuration complet pour l'intégration des points d'accès Allied Telesis de la série TQ avec Purple WiFi. Il traite de la redirection vers le Captive Portal externe, de l'authentification RADIUS 802.1X et de l'orientation VLAN dynamique à l'aide de clés prépartagées privées (PPSK) pour des déploiements multi-locataires sécurisés.

Intégration des points d'accès Grandstream GWN avec Purple WiFi

Ce guide de référence technique officiel détaille comment intégrer les points d'accès Grandstream GWN avec le Guest WiFi de Purple et sa plateforme d'analyse. Il couvre la configuration du Captive Portal Grandstream, les paramètres RADIUS AAA, la configuration du walled garden, l'authentification sécurisée du personnel en 802.1X avec routage dynamique des VLAN, et la segmentation PPSK multi-tenant - offrant ainsi des instructions étape par étape directement exploitables pour les MSP et les équipes informatiques déployant du WiFi invités et personnel à grande échelle.