Cómo configurar la autenticación WeChat OAuth para Captive Portals

CÓMO CONFIGURAR LA AUTENTICACIÓN OAUTH DE WECHAT PARA CAPTIVE PORTALS Una sesión técnica de Purple - Aproximadamente 10 minutos --- INTRODUCCIÓN Y CONTEXTO (aproximadamente 1 minuto) Bienvenido. Si eres responsable del WiFi para invitados en un hotel, cadena de tiendas, estadio o centro de conferencias que atiende a visitantes chinos, esta sesión es para ti. WeChat tiene 1,380 millones de usuarios activos mensuales, según los datos de Tencent de 2024. La gran mayoría se encuentra en China, pero la plataforma también tiene una presencia internacional significativa: cuatro millones de usuarios en los Estados Unidos, 12 millones en Malasia y un número creciente en el sudeste asiático, Europa y Medio Oriente. Cuando un invitado chino se conecta a tu WiFi y ve una página de inicio de sesión que solo ofrece correo electrónico, Facebook o un código de cupón, se enfrenta a una fricción inmediata. Es posible que no tengan una dirección de correo electrónico local configurada en ese dispositivo. Lo que sí tienen, casi con toda seguridad, es WeChat. Por lo tanto, la pregunta no es si debes ofrecer el inicio de sesión con WeChat, sino cómo configurarlo de manera correcta, segura y de forma que genere datos de primera mano que realmente puedas utilizar. Eso es lo que vamos a cubrir hoy. Analizaremos el flujo de OAuth 2.0, los dos registros de plataforma que necesitas, la decisión de alcance (scope) que determina qué datos recopilas, el mecanismo de aplicación del lado de la red y las consideraciones de cumplimiento normativo que importan en 2026. --- ANÁLISIS TÉCNICO DETALLADO (aproximadamente 5 minutos) Comencemos con la arquitectura. Un Captive Portal intercepta el tráfico HTTP de un dispositivo no autenticado y lo redirige a una página de inicio de sesión. Esa página de inicio de sesión se aloja en un servidor de portal, ya sea de forma local o en la nube. Al agregar el OAuth de WeChat, estás insertando un proveedor de identidad de terceros en ese flujo. Esta es la secuencia. El invitado se conecta a tu SSID. El punto de acceso o controlador inalámbrico detecta que el dispositivo no tiene una sesión autenticada y redirige todo el tráfico HTTP a la URL de tu Captive Portal. La página del portal se carga y presenta las opciones de inicio de sesión, incluyendo WeChat. El invitado toca el inicio de sesión de WeChat. El servidor de tu portal redirige el navegador al endpoint de autorización de WeChat en open.weixin.qq.com, enviando tu AppID, la URI de redirección, el tipo de respuesta (response type) de código y el alcance (scope). WeChat gestiona la autenticación por completo en sus propios servidores. Si el invitado ya ha iniciado sesión en WeChat en su navegador, verá una pantalla de consentimiento. Si está utilizando el navegador integrado de la aplicación WeChat, la experiencia puede ser silenciosa con el alcance snsapi_base, sin ninguna solicitud de consentimiento. Luego, WeChat redirige de vuelta a la URI de redirección de tu portal con un código de autorización temporal. El servidor de tu portal intercambia ese código por un token de acceso llamando a api.weixin.qq.com/sns/oauth2/access_token, enviando tu AppID, AppSecret, el código y el tipo de concesión (grant type) de authorization_code. WeChat devuelve un token de acceso, un token de actualización, el OpenID del usuario y el alcance otorgado. Si solicitaste el alcance snsapi_userinfo, puedes realizar una segunda llamada a la API para recuperar el apodo, avatar, género y ciudad del usuario. Ahora, los dos registros de plataforma. Aquí es donde la mayoría de las implementaciones fallan. WeChat tiene dos plataformas de desarrollo independientes. La WeChat Open Platform en open.weixin.qq.com gestiona aplicaciones web y aplicaciones móviles. La WeChat Official Accounts Platform en mp.weixin.qq.com gestiona cuentas públicas, que es lo que la mayoría de los establecimientos realmente necesitan. Para un Captive Portal que atiende a los usuarios dentro del navegador integrado de WeChat, se necesita una Cuenta de Servicio (Service Account) en la Official Accounts Platform. Una Cuenta de Suscripción (Subscription Account) no funcionará, ya que no tiene permisos de autorización de páginas web OAuth. Una Cuenta de Servicio sí los tiene y es compatible con los alcances (scopes) snsapi_base y snsapi_userinfo. Para un Captive Portal al que se accede desde un navegador móvil estándar fuera de WeChat (Chrome en Android, Safari en iOS), se necesita una Aplicación Web registrada en la Open Platform. Esta utiliza el alcance snsapi_login y presenta un código QR que el usuario escanea con su aplicación de WeChat. En la práctica, la mayoría de las implementaciones en establecimientos utilizan ambas. Un huésped en el WiFi de un hotel podría abrir el portal en Chrome, ver un código QR, escanearlo con WeChat y autenticarse. O bien, podría seguir un enlace dentro de la propia aplicación de WeChat, llegar al navegador integrado y autenticarse de forma silenciosa con snsapi_base. Hablemos de la selección de alcances, porque este es un punto de decisión real. snsapi_base devuelve únicamente el OpenID: un identificador único para ese usuario dentro de su Cuenta Oficial. No requiere ninguna solicitud de consentimiento del usuario. La autenticación es invisible para el usuario. Esto es ideal para huéspedes recurrentes de los que ya tiene un perfil, o para establecimientos donde se busca cero fricción a costa de no obtener nuevos datos. snsapi_userinfo devuelve el OpenID más el apodo de WeChat del usuario, su foto de perfil, género, configuración de idioma y ciudad. Requiere una pantalla de consentimiento explícita. El usuario ve un mensaje preguntando si permite que su Cuenta Oficial acceda a su información. La mayoría de los usuarios acepta, pero existe fricción. La elección correcta depende de su caso de uso. Para el registro de un huésped por primera vez en el que desea crear un perfil, utilice snsapi_userinfo y combínelo con una capa de consentimiento que cumpla con el GDPR en la página de su portal. Para un huésped recurrente que ya ha dado su consentimiento y del cual ya tiene su perfil, utilice snsapi_base para una autenticación silenciosa. Ahora, el lado de la aplicación de red. Obtener un token OAuth demuestra la identidad, pero no abre la red automáticamente. Necesita un mecanismo para traducir una autenticación exitosa en acceso a la red. Los dos enfoques estándar son RADIUS Change of Authorisation, definido en RFC 3576, y MAC address bypass. Con RADIUS CoA, su servidor de portal envía una solicitud de CoA al controlador de red después de un OAuth exitoso, y el controlador mueve el dispositivo de la VLAN no autenticada a la VLAN de invitados. Esto funciona con Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist y la mayoría de los controladores de nivel empresarial. Con MAC bypass, el servidor del portal registra la dirección MAC del dispositivo como un cliente autorizado y el controlador lo permite. MAC bypass es más sencillo de implementar pero menos seguro, porque las direcciones MAC se pueden falsificar. La plataforma de Guest WiFi de Purple maneja ambos mecanismos. Después de que se completa el OAuth de WeChat, la capa en la nube de Purple envía la señal adecuada al hardware subyacente, ya sea Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme o Fortinet. El operador del establecimiento no necesita gestionar esa traducción de forma manual. --- RECOMENDACIONES DE IMPLEMENTACIÓN Y ERRORES COMUNES (aproximadamente 2 minutos) Permítame compartirle las cinco razones por las cuales fallan las implementaciones de Captive Portal con OAuth de WeChat. Primero: la discrepancia en la URI de redireccionamiento. WeChat valida la URI de redireccionamiento con el dominio autorizado que registró en la plataforma. Si su servidor de portal utiliza un subdominio diferente, una ruta distinta o HTTP en lugar de HTTPS, el flujo de OAuth fallará con el error 40029 (código no válido). Registre cada variante de dominio que utilice, incluidos los entornos de prueba. Segundo: el AppSecret en el lado del cliente. Su AppSecret nunca debe aparecer en el JavaScript del lado del cliente ni en el binario de una aplicación móvil. Pertenece a su servidor. Si queda expuesto, cualquiera puede suplantar su aplicación y llamar a las API de WeChat en su nombre. Tercero: la falta de protección CSRF. El parámetro de estado en la solicitud de OAuth existe específicamente para evitar la falsificación de solicitudes entre sitios. Genere un valor de estado aleatorio criptográficamente, almacénelo en la sesión del usuario y valídelo cuando WeChat redirija de vuelta. Si omite esto, tendrá una vulnerabilidad real. Cuarto: la brecha de detección del navegador integrado en la aplicación. El navegador integrado de WeChat establece una cadena de agente de usuario específica que contiene "MicroMessenger". Si su portal no detecta esto y ofrece el flujo de OAuth correcto (flujo de Cuenta Oficial para el navegador integrado, flujo de código QR de Open Platform para navegadores estándar), los usuarios tendrán una experiencia rota o un error. Quinto: la alineación con GDPR y PIPL. Si atiende a visitantes europeos, el GDPR se aplica a los datos que recopila a través del OAuth de WeChat. Si atiende a visitantes chinos, la Ley de Protección de Información Personal de China (PIPL) se aplica a cómo procesa sus datos. Ambos requieren una base legal para el procesamiento, una limitación clara de la finalidad y la minimización de datos. snsapi_base es más fácil de justificar bajo los principios de minimización de datos que snsapi_userinfo. Independientemente de lo que recopile, documente su base legal y su período de retención. --- PREGUNTAS Y RESPUESTAS RÁPIDAS (aproximadamente 1 minuto) Question: Can I use WeChat login on a portal that also offers email and SMS login? Yes. Most enterprise portal platforms, including Purple, support multiple authentication methods on the same portal page. WeChat appears as one option alongside others. Question: Does WeChat OAuth work on iOS? Yes, but with a nuance. Apple's App Tracking Transparency framework does not affect server-side OAuth flows. WeChat login in Safari on iOS works via the QR code flow or redirect flow. The WeChat app itself handles the authentication. Question: What happens if WeChat's API is unavailable? Your portal should implement a fallback. If the WeChat API call times out or returns an error, redirect the user to an alternative login method. Do not leave them with a blank screen. Question: Can I use the OpenID as a persistent customer identifier? Within your Official Account, yes. The OpenID is stable for a given user and a given Official Account. If you have multiple Official Accounts, the same user will have different OpenIDs across them. For cross-account identity resolution, WeChat provides a UnionID, which requires your accounts to be linked on the Open Platform. --- SUMMARY AND NEXT STEPS (approximately 1 minute) To summarise. WeChat OAuth authentication for captive portals is a two-platform registration exercise, a scope decision, a network enforcement integration, and a compliance review. Get those four things right and you have a login method that serves over a billion potential visitors with zero password friction. The practical next steps are these. First, determine whether your visitors encounter the portal inside the WeChat in-app browser or in a standard mobile browser - that determines which platform registration you need. Second, decide on scope - snsapi_base for returning guests, snsapi_userinfo for first-time registration with consent. Third, confirm your network hardware supports RADIUS CoA or configure MAC bypass as an alternative. Fourth, review your privacy notice and consent flow against GDPR and PIPL requirements. Fifth, test the redirect URI, the state parameter validation, and the in-app browser detection before you go live. If you want to see how Purple handles WeChat OAuth as part of a broader Guest WiFi and analytics platform - across 80,000 venues and 440 million logins in 2024 - visit purple.ai or speak to your account team. Thanks for listening. --- END OF SCRIPT