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 Anmeldeseite sieht, die nur E-Mail, Facebook oder einen Gutscheincode anbietet, stößt er sofort auf Hindernisse. Möglicherweise hat er auf diesem Gerät keine lokale E-Mail-Adresse eingerichtet. Aber er hat mit fast absoluter Sicherheit WeChat. Die Frage ist also nicht, ob Sie den WeChat-Login anbieten sollten - sondern wie Sie ihn korrekt, sicher und so konfigurieren, dass Sie nutzbare First-Party-Daten generieren. Genau darum geht es heute. Wir gehen den OAuth 2.0-Ablauf durch, 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. --- 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 Anmeldeseite weiter. Diese Anmeldeseite wird auf einem Portal-Server gehostet - entweder vor Ort oder in der Cloud. Wenn Sie WeChat-OAuth hinzufügen, binden Sie einen Drittanbieter-Identitätsanbieter in diesen Ablauf ein. Hier ist die Sequenz. 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 die Anmeldeoptionen an - einschließlich WeChat. Der Gast tippt auf WeChat-Login. Ihr Portal-Server leitet den Browser an den Autorisierungs-Endpunkt von WeChat unter open.weixin.qq.com weiter und übergibt dabei 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 bereits im Browser 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 völlig geräuschlos sein - ohne jegliche Zustimmungsaufforderung. WeChat leitet dann mit einem temporären Autorisierungscode zurück zur Redirect-URI Ihres Portals weiter. 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, Ihr AppSecret, den Code und den Grant Type authorization_code übergibt. WeChat gibt ein Access Token, ein Refresh Token, die OpenID des Benutzers und den erteilten Scope zurück. Wenn Sie den Scope snsapi_userinfo angefordert haben, können Sie einen zweiten API-Aufruf durchführen, um den Spitznamen, den Avatar, das Geschlecht und die Stadt des Benutzers abzurufen.Nun zu den beiden Plattform-Registrierungen. Hier schleichen sich bei den meisten Implementierungen Fehler ein. WeChat bietet zwei separate Entwicklerplattformen. Die WeChat Open Platform unter open.weixin.qq.com verwaltet Website-Anwendungen und mobile Apps. Die WeChat Official Accounts Platform unter mp.weixin.qq.com verwaltet öffentliche Konten - also das, was die meisten Standorte tatsächlich benötigen. Für ein Captive Portal, das Gästen innerhalb des WeChat-In-App-Browsers bereitgestellt wird, benötigen Sie ein Service Account auf der Official Accounts Platform. Ein Subscription Account funktioniert hierbei nicht - es verfügt nicht über die erforderlichen OAuth-Berechtigungen zur Autorisierung von Webseiten. Ein Service Account bietet diese und unterstützt sowohl die Scopes snsapi_base als auch snsapi_userinfo. Für ein Captive Portal, auf das über einen standardmäßigen mobilen Browser außerhalb von WeChat zugegriffen wird - Chrome auf Android oder Safari auf iOS - benötigen Sie eine Website-Anwendung, die auf der Open Platform registriert ist. Diese verwendet den Scope snsapi_login und stellt einen QR-Code dar, den der Benutzer mit seiner WeChat-App scannt. In der Praxis nutzen die meisten Bereitstellungen an Standorten beide Varianten. Ein Gast im WiFi eines Hotels öffnet das Portal beispielsweise in Chrome, sieht einen QR-Code, scannt ihn mit WeChat und authentifiziert sich. Oder er folgt einem Link direkt in WeChat selbst, gelangt in den 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 ist. snsapi_base gibt nur die OpenID zurück - eine eindeutige Kennung für diesen Benutzer innerhalb Ihres Official Accounts. Dies erfordert keine Zustimmung des Benutzers. Die Authentifizierung erfolgt für den Benutzer unsichtbar. Dies eignet sich ideal für wiederkehrende Gäste, von denen Sie bereits ein Profil haben, oder für Standorte, 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 Daten gestattet. Die meisten Benutzer stimmen zu, aber es entsteht eine Hürde. Die richtige Wahl hängt von Ihrem Anwendungsfall ab. Für die Registrierung eines Erstbesuchers, bei der Sie ein Profil erstellen möchten, verwenden Sie snsapi_userinfo und kombinieren Sie dies mit einer GDPR-konformen Einwilligungsebene auf Ihrer Portalseite. 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 Netzwerk-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 zwei Standardverfahren sind RADIUS Change of Authorisation, definiert in RFC 3576, und MAC-Adress-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 lässt sie zu. Ein 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 - ob es sich nun um Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme oder Fortinet handelt. Der Standortbetreiber muss diese Übersetzung nicht manuell verwalten. --- IMPLEMENTIERUNGSEMPFEHLUNGEN UND STOLPERSTEINE (ca. 2 Minuten) Hier sind die fünf häufigsten Gründe, warum Implementierungen von WeChat-OAuth-Captive-Portalen fehlschlagen. Erstens: Abweichungen bei der Redirect-URI. WeChat validiert die Redirect-URI mit der autorisierten Domain, 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 AppSecret auf 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 WeChat-APIs in Ihrem Namen aufrufen. Drittens: Fehlender CSRF-Schutz. Der State-Parameter in der OAuth-Anfrage existiert speziell zur Verhinderung 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, haben Sie eine echte Sicherheitslücke. Viertens: 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 nicht den richtigen OAuth-Flow ausliefert - Official-Account-Flow für den In-App-Browser, Open-Platform-QR-Flow für Standard-Browser - erhalten 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 Chinas Personal Information Protection Law - PIPL - für die Verarbeitung ihrer Daten. Beide erfordern eine Rechtsgrundlage für die Verarbeitung, eine klare Zweckbindung und Datenminimierung. snsapi_base ist unter den Grundsätzen der Datenminimierung leichter zu rechtfertigen als snsapi_userinfo. Dokumentieren Sie unabhängig von Ihren erfassten Daten Ihre Rechtsgrundlage und Ihre Speicherfrist. --- SCHNELLE FRAGEN UND ANTWORTEN (ca. 1 Minute) Frage: Kann ich die WeChat-Anmeldung auf einem Portal nutzen, das auch E-Mail- und SMS-Anmeldung anbietet? Ja. Die meisten Portal-Plattformen für Unternehmen, einschließlich Purple, unterstützen mehrere Authentifizierungsmethoden auf derselben Portalseite. WeChat wird als eine Option neben anderen angezeigt. Frage: Funktioniert WeChat OAuth auf iOS? Ja, aber mit einer Nuance. Das App-Tracking-Transparency-Framework von Apple hat keinen Einfluss auf serverseitige OAuth-Flows. Die WeChat-Anmeldung in Safari unter iOS funktioniert über den QR-Code-Flow oder den Redirect-Flow. 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 ein Timeout aufweist oder einen Fehler zurückgibt, leiten Sie den Benutzer zu einer alternativen Anmeldemethode 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 bei diesen unterschiedliche OpenIDs. Für die kontoübergreifende Identitätsauflösung bietet WeChat eine UnionID an, 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 ist eine Registrierung auf zwei Plattformen, eine Scope-Entscheidung, eine Integration der Netzwerkdurchsetzung und eine Compliance-Prüfung. Wenn Sie diese vier Punkte richtig angehen, erhalten Sie eine Anmeldemethode, die über eine Milliarde potenzieller Besucher ohne jeglichen Passwort-Frust bedient. Die praktischen nächsten Schritte sind folgende: Bestimmen Sie erstens, ob Ihre Besucher das Portal im In-App-Browser von WeChat oder in einem Standard-Mobilbrowser aufrufen - das entscheidet darüber, welche Plattformregistrierung Sie benötigen. Entscheiden Sie zweitens über den Scope - snsapi_base für wiederkehrende Gäste, snsapi_userinfo für die Erstregistrierung mit Einwilligung. Bestätigen Sie drittens, ob Ihre Netzwerkhardware RADIUS CoA unterstützt, oder konfigurieren Sie MAC-Bypass als Alternative. Überprüfen Sie viertens Ihre Datenschutzerklärung und Ihren Einwilligungsprozess im Hinblick auf die Anforderungen der GDPR und des PIPL. Testen Sie fünftens 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 - auf über 80.000 Standorten und bei 440 Millionen Anmeldungen im Jahr 2024 - besuchen Sie purple.ai oder sprechen Sie mit Ihrem Account-Team. Vielen Dank fürs Zuhören. - ENDE DES SKRIPTS