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 informativa 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 informativa es para ti. WeChat tiene 1,380 millones de usuarios activos mensuales, según los datos de 2024 de Tencent. La gran mayoría está en China, pero la plataforma también tiene una presencia internacional importante - cuatro millones de usuarios en los Estados Unidos, 12 millones en Malasia y un número creciente en todo 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 tiene correo electrónico, Facebook o un código de cupón, se enfrenta a una fricción inmediata. Es posible que no tenga una dirección de correo electrónico local configurada en ese dispositivo. Lo más seguro es que tenga WeChat. Por lo tanto, la pregunta no es si debes ofrecer el inicio de sesión con WeChat - sino cómo configurarlo de forma correcta, segura y de manera que genere datos de origen que realmente puedas utilizar. Eso es lo que vamos a cubrir hoy. Explicaremos el flujo de OAuth 2.0, los dos registros de plataforma que necesitas, la decisión de alcance que determina qué datos recopilas, el mecanismo de aplicación en el lado de la red y las consideraciones de cumplimiento normativo que importan en 2026. --- INMERSIÓN TÉCNICA PROFUNDA (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 está alojada en un servidor de portal - ya sea de forma local o en la nube. Al añadir el OAuth de WeChat, estás insertando un proveedor de identidad externo en ese flujo. Esta es la secuencia. El invitado se conecta a tu SSID. El punto de acceso o el 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 selecciona 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, pasando tu AppID, la URI de redirección, el tipo de respuesta del 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 utiliza el navegador integrado de WeChat, la experiencia puede ser silenciosa con el alcance snsapi_base - sin ningún mensaje de consentimiento. A continuación, 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, pasando tu AppID, AppSecret, el código y el tipo de concesión de authorization_code. WeChat devuelve un token de acceso, un token de actualización, el OpenID del usuario y el alcance concedido. Si has solicitado el alcance snsapi_userinfo, puedes realizar una segunda llamada a la API para recuperar el apodo, avatar, género y ciudad del usuario. Ahora, hablemos de los dos registros de plataforma. Aquí es donde fallan la mayoría de las implementaciones. WeChat tiene dos plataformas de desarrollo independientes. WeChat Open Platform en open.weixin.qq.com maneja aplicaciones web y aplicaciones móviles. WeChat Official Accounts Platform en mp.weixin.qq.com maneja cuentas públicas, que es lo que la mayoría de los establecimientos necesitan en realidad. Para un Captive Portal que atienda a los usuarios dentro del navegador integrado de WeChat, necesita una Service Account en la Official Accounts Platform. Una Subscription Account no funcionará, ya que no tiene permisos de autorización de páginas web OAuth. Una Service Account sí los tiene y es compatible con los alcances snsapi_base y snsapi_userinfo. Para acceder a un Captive Portal desde un navegador móvil estándar fuera de WeChat (Chrome en Android o Safari en iOS), necesita una Website Application registrada en la Open Platform. Esta utiliza el alcance snsapi_login y muestra un código QR que el usuario escanea con su aplicación WeChat. En la práctica, la mayoría de las implementaciones en establecimientos utilizan ambas. Un usuario en el WiFi de un hotel puede abrir el portal en Chrome, ver un código QR, escanearlo con WeChat y autenticarse. O bien, puede seguir un enlace dentro del propio WeChat, abrir el navegador integrado y autenticarse de forma silenciosa con snsapi_base. Hablemos de la selección del alcance, ya que este es un punto de decisión importante. snsapi_base devuelve únicamente el OpenID, un identificador único para ese usuario dentro de su Official Account. No requiere ninguna solicitud de consentimiento del usuario. La autenticación es invisible para el usuario. Esto es ideal para los huéspedes que regresan y de los que ya tiene un perfil, o para establecimientos donde se busca eliminar cualquier 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 verá un mensaje preguntando si permite que su Official Account acceda a su información. La mayoría de los usuarios acepta, pero esto genera cierta fricción. La elección correcta depende de su caso de uso. Para el registro de un huésped nuevo en el que desea crear un perfil, utilice snsapi_userinfo y compleméntelo con una capa de consentimiento que cumpla con el GDPR en su página de portal. Para un huésped recurrente que ya ha dado su consentimiento y del cual ya tiene su perfil, utilice snsapi_base para una reautenticación silenciosa. Ahora, hablemos del lado de la aplicación en la red. Obtener un token de OAuth demuestra la identidad, pero no abre la red de forma automática. 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, el servidor de su 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 suplantar. La plataforma de Guest WiFi de Purple maneja ambos mecanismos. Después de que se completa WeChat OAuth, la superposición 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 Networks 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 que fallan las implementaciones de portal cautivo con WeChat OAuth. Primero: la discrepancia en la URI de redireccionamiento. WeChat valida la URI de redireccionamiento con el dominio autorizado que registró en la plataforma. Si el servidor de su 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, incluyendo 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. Debe permanecer en su servidor. Si queda expuesto, cualquiera puede suplantar su aplicación y realizar llamadas a las API de WeChat en su nombre. Tercero: la falta de protección CSRF. El parámetro state en la solicitud de OAuth existe específicamente para evitar la falsificación de solicitudes en sitios cruzados. Genere un valor de state criptográficamente aleatorio, 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. El navegador integrado de WeChat establece una cadena de agente de usuario específica que contiene "MicroMessenger". Si su portal no detecta esto y no 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 fallida 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 de WeChat OAuth. 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 exigen una base legal para el procesamiento, una limitación de finalidad clara 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) Pregunta: ¿Puedo usar el inicio de sesión con WeChat en un portal que también ofrece inicio de sesión por correo electrónico y SMS? Sí. La mayoría de las plataformas de portales empresariales, incluyendo Purple, admiten múltiples métodos de autenticación en la misma página de portal. WeChat aparece como una opción junto con las demás. Pregunta: ¿Funciona OAuth de WeChat en iOS? Sí, pero con un matiz. El marco de App Tracking Transparency de Apple no afecta a los flujos de OAuth del lado del servidor. El inicio de sesión con WeChat en Safari en iOS funciona a través del flujo de código QR o del flujo de redirección. La propia aplicación de WeChat gestiona la autenticación. Pregunta: ¿Qué pasa si la API de WeChat no está disponible? Su portal debe implementar una alternativa de respaldo. Si la llamada a la API de WeChat supera el tiempo de espera o devuelve un error, redireccione al usuario a un método de inicio de sesión alternativo. No lo deje con una pantalla en blanco. Pregunta: ¿Puedo usar el OpenID como un identificador de cliente persistente? Dentro de su Cuenta Oficial, sí. El OpenID es estable para un usuario determinado y una Cuenta Oficial determinada. Si tiene múltiples Cuentas Oficiales, el mismo usuario tendrá diferentes OpenIDs en cada una de ellas. Para la resolución de identidad entre cuentas, WeChat proporciona un UnionID, el cual requiere que sus cuentas estén vinculadas en la Plataforma Abierta. - RESUMEN Y PRÓXIMOS PASOS (aproximadamente 1 minuto) En resumen. La autenticación OAuth de WeChat para portales cautivos es un ejercicio de registro en dos plataformas, una decisión de alcance, una integración de aplicación de red y una revisión de cumplimiento. Si hace bien esas cuatro cosas, tendrá un método de inicio de sesión que atiende a más de mil millones de visitantes potenciales sin la fricción de ingresar una contraseña. Los pasos prácticos a seguir son estos. Primero, determine si sus visitantes se encuentran con el portal dentro del navegador interno de WeChat o en un navegador móvil estándar; eso determina qué registro de plataforma necesita. Segundo, decida el alcance: snsapi_base para huéspedes recurrentes, snsapi_userinfo para el registro de primera vez con consentimiento. Tercero, confirme que el hardware de su red sea compatible con RADIUS CoA o configure el bypass de MAC como alternativa. Cuarto, revise su aviso de privacidad y flujo de consentimiento frente a los requisitos de GDPR y PIPL. Quinto, pruebe la URI de redirección, la validación del parámetro state y la detección del navegador interno antes de iniciar. Si desea ver cómo Purple gestiona OAuth de WeChat como parte de una plataforma más amplia de WiFi de invitados y analítica - a través de 80,000 establecimientos y 440 millones de inicios de sesión en 2024 - visite purple.ai o hable con su equipo de cuenta. Gracias por escuchar. - FIN DEL GUION