So konfigurieren Sie die WeChat-OAuth-Authentifizierung für Captive Portals

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) Herzlich 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 1,38 Milliarden monatlich aktive Nutzer. Die überwältigende 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 hat er auf diesem Gerät keine lokale E-Mail-Adresse eingerichtet. Aber er hat mit an Sicherheit grenzender Wahrscheinlichkeit WeChat. Die Frage ist also nicht, ob Sie einen WeChat-Login anbieten sollten, sondern wie Sie ihn korrekt, sicher und so konfigurieren, dass Sie tatsächlich nutzbare First-Party-Daten generieren. Genau darum geht es heute. Wir gehen den OAuth 2.0-Ablauf durch, die zwei erforderlichen Plattform-Registrierungen, die Entscheidung über den Scope, die bestimmt, welche Daten Sie erfassen, den netzwerkseitigen Durchsetzungsmechanismus und die Compliance-Überlegungen, die im Jahr 2026 wichtig sind. --- 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 lokal oder in der Cloud. Wenn Sie WeChat-OAuth hinzufügen, binden Sie einen Drittanbieter-Identitätsanbieter in diesen Ablauf ein. Hier ist die Abfolge. 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 Portalseite lädt und zeigt Login-Optionen an – einschließlich WeChat. Der Gast tippt auf den WeChat-Login. Ihr Portal-Server leitet den Browser an den Autorisierungsendpunkt von WeChat unter open.weixin.qq.com weiter und übergibt Ihre AppID, die 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 WeChat-In-App-Browser verwendet, kann der Vorgang mit dem Scope snsapi_base völlig geräuschlos ablaufen – ganz ohne Zustimmungsaufforderung. WeChat leitet dann mit einem temporären Autorisierungscode zurück an die Redirect-URI Ihres Portals. Ihr Portal-Server tauscht diesen Code gegen ein Access-Token aus, indem er api.weixin.qq.com/sns/oauth2/access_token aufruft und Ihre AppID, das AppSecret, den Code und den Grant-Typ authorization_code übergibt. WeChat gibt ein Access-Token, ein Refresh-Token, die OpenID des Benutzers und den gewährten Scope zurück. Wenn Sie den Scope snsapi_userinfo angefordert haben, können Sie anschließend einen zweiten API-Aufruf durchführen, um den Spitznamen, das Profilbild, das Geschlecht und die Stadt des Benutzers abzurufen. Nun zu den beiden Plattform-Registrierungen. Hier passieren die meisten Fehler bei Implementierungen. WeChat hat zwei separate Entwicklerplattformen. Die WeChat Open Platform unter open.weixin.qq.com ist für Website-Anwendungen und mobile Apps zuständig. Die WeChat Official Accounts Platform unter mp.weixin.qq.com verwaltet öffentliche Konten – was die meisten Veranstaltungsorte tatsächlich benötigen. Für ein Captive Portal, das Gäste innerhalb des WeChat-In-App-Browsers bedient, benötigen Sie ein Service-Konto auf der Official Accounts Platform. Ein Abonnement-Konto (Subscription Account) funktioniert nicht – es verfügt nicht über die erforderlichen Berechtigungen zur OAuth-Webseiten-Autorisierung. Ein Service-Konto hingegen schon, und es unterstützt sowohl den Scope snsapi_base als auch snsapi_userinfo. Für ein Captive Portal, auf das über einen Standard-Mobilbrowser außerhalb von WeChat zugegriffen wird – wie Chrome unter Android oder Safari unter iOS –, benötigen Sie eine auf der Open Platform registrierte Website-Anwendung. Diese verwendet den Scope snsapi_login und zeigt einen QR-Code an, den der Benutzer mit seiner WeChat-App scannt. In der Praxis nutzen die meisten Bereitstellungen an Veranstaltungsorten beides. Ein Gast im WiFi eines Hotels öffnet das Portal vielleicht 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 über snsapi_base. Lassen Sie uns über die Auswahl des Scopes sprechen, da dies eine wichtige Entscheidung ist. snsapi_base gibt nur die OpenID zurück – eine eindeutige Kennung für diesen Benutzer innerhalb Ihres Official Accounts. Es ist kein Zustimmungsfenster für den Benutzer erforderlich. Die Authentifizierung erfolgt für den Benutzer unsichtbar. Dies ist ideal für wiederkehrende Gäste, von denen Sie bereits ein Profil haben, oder für Orte, an denen Sie absolute Reibungslosigkeit auf Kosten neuer Daten bevorzugen. snsapi_userinfo gibt die OpenID sowie den WeChat-Spitznamen, das Profilbild, das Geschlecht, die Spracheinstellung und die Stadt des Benutzers zurück. Dies erfordert einen expliziten Zustimmungsbildschirm. Der Benutzer sieht eine Aufforderung, ob er Ihrem Official Account den Zugriff auf seine Informationen gestatten möchte. Die meisten Benutzer stimmen zu, aber es entsteht eine Hürde. Die richtige Wahl hängt von Ihrem Anwendungsfall ab. Für die Erstregistrierung eines Gastes, bei der Sie ein Profil erstellen möchten, verwenden Sie snsapi_userinfo und kombinieren Sie dies mit einer GDPR-konformen Zustimmungsebene auf Ihrer Portalseite. Für einen wiederkehrenden Gast, der bereits zugestimmt hat und dessen Profil Sie bereits besitzen, nutzen Sie snsapi_base für eine stille Re-Authentifizierung. Nun zur netzwerkseitigen Durchsetzung. Der Erhalt eines OAuth-Tokens beweist zwar die Identität, öffnet aber nicht automatisch das Netzwerk. Sie benötigen einen Mechanismus, um eine erfolgreiche Authentifizierung in einen Netzwerkzugriff zu übersetzen. Die beiden Standardansätze sind RADIUS Change of Authorisation (definiert in RFC 3576) und der MAC-Adressen-Bypass. Bei RADIUS CoA sendet Ihr Portal-Server nach erfolgreichem OAuth eine CoA-Anfrage an den Netzwerk-Controller, und der Controller verschiebt das Gerät aus dem 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 gibt sie frei. 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 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 Veranstaltungsorts muss diese Übersetzung nicht manuell verwalten. --- EMPFEHLUNGEN FÜR DIE IMPLEMENTIERUNG UND STOLPERSTEINE (ca. 2 Minuten) Lassen Sie mich Ihnen die fünf Gründe nennen, warum WeChat-OAuth-Implementierungen bei Captive Portals scheitern. Erstens: Abweichungen bei der Redirect-URI. WeChat validiert die Redirect-URI streng gegen die autorisierte Domain, die Sie auf der Plattform registriert haben. Wenn Ihr Portal-Server eine andere Subdomain, einen anderen Pfad oder HTTP statt HTTPS verwendet, schlägt der OAuth-Ablauf mit dem Fehler 40029 (ungültiger Code) fehl. Registrieren Sie jede von Ihnen verwendete Domain-Variante, einschließlich Staging-Umgebungen. Zweitens: Das AppSecret auf der Client-Seite. Ihr AppSecret darf niemals im clientseitigen JavaScript oder in einer mobilen App-Binärdatei auftauchen. Es gehört auf Ihren Server. Wenn es offengelegt wird, kann jeder Ihre Anwendung imitieren und in Ihrem Namen die APIs von WeChat aufrufen. Drittens: Fehlender CSRF-Schutz. Der State-Parameter in der OAuth-Anfrage dient speziell dazu, Cross-Site-Request-Forgery zu verhindern. Generieren Sie einen kryptografisch zufälligen State-Wert, speichern Sie ihn in der Sitzung des Benutzers und validieren Sie ihn, wenn WeChat zurückleitet. Wenn Sie dies überspringen, haben Sie eine echte Sicherheitslücke. Viertens: Fehlende Erkennung des In-App-Browsers. Der In-App-Browser von WeChat setzt einen spezifischen User-Agent-String, der „MicroMessenger“ enthält. Wenn Ihr Portal dies nicht erkennt und den richtigen OAuth-Ablauf bereitstellt – Official Account-Ablauf für den In-App-Browser, Open Platform QR-Ablauf für Standardbrowser –, erhalten die Benutzer eine fehlerhafte Darstellung oder eine Fehlermeldung. Fünftens: Abstimmung von GDPR und PIPL. Wenn Sie europäische Besucher bedienen, gilt die GDPR für die Daten, die Sie über WeChat-OAuth erfassen. Wenn Sie chinesische Besucher bedienen, gilt das chinesische Gesetz zum Schutz persönlicher Daten – PIPL – für die Verarbeitung ihrer Daten. Beide erfordern eine Rechtsgrundlage für die Verarbeitung, eine klare Zweckbindung und Datenminimierung. snsapi_base lässt sich unter den Grundsätzen 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) Frage: 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. WeChat erscheint dann als eine Option neben anderen. Frage: Funktioniert WeChat-OAuth unter iOS? Ja, aber mit einer Nuance. Das App Tracking Transparency-Framework von Apple hat keinen Einfluss auf serverseitige OAuth-Abläufe. Der WeChat-Login in Safari unter iOS funktioniert über den QR-Code-Ablauf oder den Redirect-Ablauf. Die WeChat-App selbst übernimmt die Authentifizierung. Frage: Was passiert, wenn die API von WeChat nicht verfügbar ist? Ihr Portal sollte ein Fallback implementieren. Wenn der WeChat-API-Aufruf das Zeitlimit überschreitet oder einen Fehler zurückgibt, leiten Sie den Benutzer zu einer alternativen Login-Methode weiter. Lassen Sie ihn nicht vor einem leeren Bildschirm stehen. Frage: Kann ich die OpenID als dauerhafte Kundenkennung verwenden? Innerhalb Ihres Official Accounts: Ja. Die OpenID ist für einen bestimmten Benutzer und einen bestimmten Official Account stabil. Wenn Sie mehrere Official Accounts haben, hat derselbe Benutzer in diesen Konten unterschiedliche OpenIDs. Für eine kontoübergreifende Identitätsauflösung stellt WeChat eine UnionID bereit, wofür Ihre Konten auf der Open Platform verknüpft sein müssen. --- 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-Durchsetzung und eine Compliance-Prüfung. Wenn Sie diese vier Punkte richtig umsetzen, haben Sie eine Login-Methode, die über eine Milliarde potenzieller Besucher völlig passwortfrei bedient. Die praktischen nächsten Schritte sind folgende: Bestimmen Sie erstens, ob Ihre Besucher das Portal innerhalb des WeChat-In-App-Browsers oder in einem Standard-Mobilbrowser aufrufen – das entscheidet darüber, welche Plattform-Registrierung Sie benötigen. Entscheiden Sie sich zweitens für den Scope – snsapi_base für wiederkehrende Gäste, snsapi_userinfo für die Erstregistrierung mit Zustimmung. Vergewissern Sie sich drittens, dass Ihre Netzwerkhardware RADIUS CoA unterstützt, oder konfigurieren Sie alternativ den MAC-Bypass. Überprüfen Sie viertens Ihre Datenschutzerklärung und Ihren Consent-Flow im Hinblick auf die Anforderungen von GDPR und PIPL. Testen Sie fünftens die Redirect-URI, die Validierung des State-Parameters und die Erkennung des In-App-Browsers, bevor Sie live gehen. Wenn Sie sehen möchten, wie Purple WeChat-OAuth als Teil einer umfassenderen Guest WiFi- und Analyseplattform handhabt – an 80.000 Veranstaltungsorten 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