Integration der WeChat-Authentifizierung in Captive Portals für Guest WiFi

SO KONFIGURIEREN SIE DIE WECHAT OAUTH-AUTHENTIFIZIERUNG FÜR CAPTIVE PORTALS Ein technisches Briefing von Purple - Ca. 10 Minuten --- EINFÜHRUNG UND KONTEXT (ca. 1 Minute) Willkommen. Wenn Sie für das Gäste-WiFi in einem Hotel, einer Einzelhandelskette, einem Stadion oder einem Konferenzzentrum verantwortlich sind, das chinesische Besucher bedient, ist dieses Briefing genau das Richtige für Sie. WeChat hat laut den Daten von Tencent aus dem Jahr 2024 monatlich 1,38 Milliarden aktive Nutzer. Die überwiegende Mehrheit befindet sich in China, aber die Plattform hat auch eine bedeutende internationale Präsenz – vier Millionen Nutzer in den USA, 12 Millionen in Malaysia und wachsende Zahlen in Südostasien, Europa und dem Nahen Osten. Wenn sich ein chinesischer Gast mit Ihrem WiFi verbindet und eine Login-Seite sieht, die nur E-Mail, Facebook oder einen Gutscheincode anbietet, stößt er sofort auf Barrieren. Möglicherweise ist auf diesem Gerät keine lokale E-Mail-Adresse eingerichtet. Er hat jedoch mit ziemlicher Sicherheit WeChat. Die Frage ist also nicht, ob Sie den WeChat-Login anbieten sollten – sondern wie Sie ihn korrekt, sicher und so konfigurieren, dass First-Party-Daten generiert werden, die Sie tatsächlich nutzen können. Darum geht es heute. Wir werden den OAuth 2.0-Flow, die beiden erforderlichen Plattformregistrierungen, die Scope-Entscheidung (die bestimmt, welche Daten Sie erfassen), den netzwerkseitigen Durchsetzungsmechanismus und die Compliance-Überlegungen, die im Jahr 2026 wichtig sind, durchgehen. --- TECHNISCHER DEEP-DIVE (ca. 5 Minuten) Beginnen wir mit der Architektur. Ein Captive Portal fängt den HTTP-Verkehr von einem nicht authentifizierten Gerät ab und leitet ihn auf eine Login-Seite weiter. Diese Login-Seite wird auf einem Portal-Server gehostet – entweder vor Ort oder in der Cloud. Wenn Sie WeChat-OAuth hinzufügen, fügen Sie einen externen Identitätsanbieter in diesen Ablauf ein. Hier ist der Ablauf. Der Gast verbindet sich mit Ihrer SSID. Der Access Point oder Wireless-Controller erkennt, dass das Gerät keine authentifizierte Sitzung hat, und leitet den gesamten HTTP-Verkehr an Ihre Captive Portal-URL weiter. Die Portal-Seite lädt und zeigt Login-Optionen an – einschließlich WeChat. Der Gast tippt auf den WeChat-Login. Ihr Portal-Server leitet den Browser zum Autorisierungs-Endpunkt von WeChat weiter und übergibt Ihre App-ID, den Redirect-URI, den Antworttyp „code“ und den Scope. WeChat wickelt die Authentifizierung vollständig auf den eigenen Servern ab. Wenn der Gast in seinem Browser bereits bei WeChat angemeldet ist, sieht er einen Zustimmungsbildschirm. Wenn er den In-App-Browser von WeChat verwendet, kann die Benutzererfahrung mit dem Scope „snsapi_base“ geräuschlos sein – ganz ohne Zustimmungsaufforderung. WeChat leitet dann zurück an den Redirect-URI Ihres Portals mit einem temporären Autorisierungscode. Ihr Portal-Server tauscht diesen Code gegen ein Access-Token aus, indem er Ihre App-ID, das App-Secret, den Code und den Grant-Typ „authorization_code“ übergibt. WeChat gibt ein Access-Token, ein Refresh-Token, die Open-ID des Benutzers und den erteilten Scope zurück. Wenn Sie den Scope „snsapi_userinfo“ angefordert haben, können Sie anschließend einen zweiten API-Aufruf durchführen, um den Benutzernamen, den Avatar, das Geschlecht und die Stadt des Benutzers abzurufen.Nun zu den beiden Plattformregistrierungen. Hier schleichen sich bei den meisten Implementierungen Fehler ein. WeChat verfügt über zwei separate Entwicklerplattformen. Die WeChat Open Platform ist für Website-Anwendungen und mobile Apps zuständig. Die WeChat Official Accounts Platform verwaltet öffentliche Konten – also das, was die meisten Standorte tatsächlich benötigen. Für ein Captive Portal, das Gästen innerhalb des In-App-Browsers von WeChat angezeigt wird, benötigen Sie ein Service Account auf der Official Accounts Platform. Ein Subscription Account funktioniert hier nicht – es verfügt nicht über die Berechtigungen zur OAuth-Webseiten-Autorisierung. Ein Service Account bietet diese und unterstützt sowohl den snsapi_base- als auch den snsapi_userinfo-Scope. Für ein Captive Portal, auf das über einen Standard-Mobilbrowser außerhalb von WeChat zugegriffen wird – Chrome auf Android, Safari auf iOS –, benötigen Sie eine auf der Open Platform registrierte Website-Anwendung. Diese nutzt den snsapi_login-Scope und zeigt einen QR-Code an, den der Nutzer mit seiner WeChat-App scannt. In der Praxis nutzen die meisten Implementierungen an Standorten beide Varianten. Ein Gast im WiFi eines Hotels öffnet das Portal eventuell in Chrome, sieht einen QR-Code, scannt ihn mit WeChat und authentifiziert sich. Oder er folgt einem Link direkt in WeChat, landet im In-App-Browser und authentifiziert sich geräuschlos via snsapi_base. Lassen Sie uns über die Auswahl des Scopes sprechen, da dies eine wichtige Entscheidung darstellt. snsapi_base gibt nur die Open ID zurück – eine eindeutige Kennung für diesen Nutzer innerhalb Ihres Official Accounts. Hierfür ist keine Zustimmung des Nutzers erforderlich. Die Authentifizierung erfolgt für den Nutzer unsichtbar. Dies ist ideal für wiederkehrende Gäste, von denen Sie bereits ein Profil haben, oder für Standorte, an denen Sie absolute Reibungslosigkeit wünschen. snsapi_userinfo gibt die Open ID sowie den WeChat-Spitznamen, das Profilbild, das Geschlecht, die Spracheinstellung und die Stadt des Nutzers zurück. Dies erfordert ein explizites Zustimmungsfenster. Die meisten Nutzer stimmen zu, aber es bedeutet eine Hürde im Ablauf. Die richtige Wahl hängt von Ihrem Anwendungsfall ab. Für die Erstregistrierung eines Gastes, bei der Sie ein Profil erstellen möchten, nutzen Sie snsapi_userinfo in Kombination mit einer GDPR-konformen Einwilligungsebene auf Ihrer Portal-Seite. Für einen wiederkehrenden Gast, der bereits eingewilligt hat und dessen Profil Sie bereits besitzen, nutzen Sie snsapi_base für eine geräuschlose Re-Authentifizierung. Nun zur Netzwerkdurchsetzung. Der Erhalt eines OAuth-Tokens beweist die Identität, gibt das Netzwerk jedoch nicht automatisch frei. Sie benötigen einen Mechanismus, um eine erfolgreiche Authentifizierung in Netzzugang zu übersetzen. Die beiden Standardansätze sind RADIUS Change of Authorisation (CoA), definiert in RFC 3576, und das MAC-Adressen-Bypass-Verfahren. Bei RADIUS CoA sendet Ihr Portal-Server nach erfolgreichem OAuth eine CoA-Anfrage an den Netzwerk-Controller, und der Controller verschiebt das Gerät vom nicht-authentifizierten VLAN in das Gäste-VLAN. Dies funktioniert mit Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist und den meisten anderen Enterprise-Controllern. Beim MAC-Bypass registriert der Portal-Server die MAC-Adresse des Geräts als autorisierten Client, und der Controller lässt die Verbindung zu. Der MAC-Bypass ist einfacher zu implementieren, aber weniger sicher, da MAC-Adressen gefälscht werden können.Die Guest WiFi-Plattform von Purple unterstützt beide Mechanismen. Nach Abschluss des WeChat-OAuth-Vorgangs sendet das Cloud-Overlay von Purple das entsprechende Signal an die zugrunde liegende Hardware – sei es Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme oder Fortinet. Der Betreiber des Standorts muss diese Übersetzung nicht manuell verwalten. --- IMPLEMENTIERUNGSEMPFEHLUNGEN UND STOLPERSTEINE (ca. 2 Minuten) Hier sind die fünf Hauptgründe, warum Implementierungen von WeChat-OAuth-Captive Portals scheitern. Erstens: Die Diskrepanz bei der Redirect-URI. WeChat gleicht die Redirect-URI mit der autorisierten Domain ab, die Sie auf der Plattform registriert haben. Wenn Ihr Portal-Server eine andere Subdomain, einen anderen Pfad oder HTTP anstelle von HTTPS verwendet, schlägt der OAuth-Flow mit dem Fehler 40029 (ungültiger Code) fehl. Registrieren Sie jede von Ihnen verwendete Domain-Variante, einschließlich Staging-Umgebungen. Zweitens: Das App Secret auf der Client-Seite. Ihr App Secret darf niemals im clientseitigen JavaScript auftauchen. Es gehört auf Ihren Server. Wenn es offengelegt wird, kann jeder Ihre Anwendung imitieren und WeChat-APIs in Ihrem Namen aufrufen. Drittens: Fehlender CSRF-Schutz. Der State-Parameter in der OAuth-Anfrage existiert speziell zur Vermeidung von Cross-Site-Request-Forgery. Generieren Sie einen kryptografisch zufälligen State-Wert, speichern Sie ihn in der Benutzersitzung und validieren Sie ihn, wenn WeChat zurückleitet. Wenn Sie dies überspringen, riskieren Sie eine echte Sicherheitslücke. Viertens: Die fehlende In-App-Browser-Erkennung. Der In-App-Browser von WeChat setzt einen spezifischen User-Agent-String, der „MicroMessenger“ enthält. Wenn Ihr Portal dies nicht erkennt und den korrekten OAuth-Flow bereitstellt, erhalten Benutzer eine fehlerhafte Darstellung oder eine Fehlermeldung. Fünftens: Abstimmung mit GDPR und PIPL. Wenn Sie europäische Besucher bedienen, gilt die GDPR. Wenn Sie chinesische Besucher bedienen, gilt das chinesische Gesetz zum Schutz persönlicher Daten (PIPL). Beide erfordern eine rechtmäßige Grundlage für die Verarbeitung, eine klare Zweckbindung und Datenminimierung. „snsapi_base“ lässt sich im Rahmen der Datenminimierung leichter rechtfertigen als „snsapi_userinfo“. Was auch immer Sie erfassen: Dokumentieren Sie Ihre Rechtsgrundlage und Ihre Aufbewahrungsfrist. --- SCHNELLE FRAGEN UND ANTWORTEN (ca. 1 Minute) Kann ich den WeChat-Login auf einem Portal nutzen, das auch E-Mail- und SMS-Login anbietet? Ja. Die meisten Enterprise-Portal-Plattformen, einschließlich Purple, unterstützen mehrere Authentifizierungsmethoden auf derselben Portalseite. Funktioniert WeChat-OAuth auf iOS? Ja. Der WeChat-Login in Safari auf iOS funktioniert über den QR-Code-Flow oder den Redirect-Flow. Die WeChat-App selbst übernimmt die Authentifizierung. Was passiert, wenn die WeChat-API nicht verfügbar ist? Implementieren Sie einen Fallback. Wenn der WeChat-API-Aufruf das Zeitlimit überschreitet oder einen Fehler zurückgibt, leiten Sie den Benutzer zu einer alternativen Login-Methode weiter. Kann ich die OpenID als dauerhafte Kundenkennung verwenden? Innerhalb Ihres Official Accounts: Ja. Für eine kontoübergreifende Identitätsauflösung über mehrere Standorte hinweg sollten Sie stattdessen die UnionID verwenden. --- ZUSAMMENFASSUNG UND NÄCHSTE SCHRITTE (ca. 1 Minute) Zusammenfassend lässt sich sagen: Die WeChat OAuth-Authentifizierung für Captive Portals erfordert eine Registrierung auf zwei Plattformen, eine Entscheidung über den Scope, eine Integration der Netzwerk-Erzwingung und eine Compliance-Prüfung. Wenn Sie diese vier Punkte richtig angehen, erhalten Sie eine Anmeldemethode, die über eine Milliarde potenzieller Besucher ganz ohne Passwort-Frustration bedient. Die praktischen nächsten Schritte: Bestimmen Sie, ob Ihre Besucher das Portal im WeChat-In-App-Browser oder in einem Standard-Mobilbrowser aufrufen. Entscheiden Sie sich für den Scope – „snsapi_base“ für wiederkehrende Gäste, „snsapi_userinfo“ für die Erstregistrierung mit Einwilligung. Bestätigen Sie, dass Ihre Netzwerk-Hardware RADIUS CoA unterstützt. Überprüfen Sie Ihre Datenschutzerklärung im Hinblick auf GDPR und PIPL. Testen Sie die Redirect-URI, die Validierung des State-Parameters und die In-App-Browser-Erkennung, bevor Sie live gehen. Wenn Sie sehen möchten, wie Purple WeChat OAuth als Teil einer umfassenderen Guest WiFi- und Analyseplattform handhabt – an über 80.000 Standorten und bei 440 Millionen Logins im Jahr 2024 –, besuchen Sie purple.ai oder sprechen Sie mit Ihrem Account-Team. Vielen Dank fürs Zuhören. --- ENDE DES SKRIPTS