Cómo configurar la autenticación OAuth de WeChat 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 es usted 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 usted. WeChat cuenta con 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 todo el sudeste asiático, Europa y Oriente Medio. Cuando un invitado chino se conecta a su WiFi y ve una página de inicio de sesión con solo 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. Es casi seguro que sí tiene WeChat. Por lo tanto, la pregunta no es si debe 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 pueda utilizar. Eso es lo que vamos a tratar hoy. Repasaremos el flujo de OAuth 2.0, los dos registros de plataforma que necesita, la decisión del alcance que determina qué datos recopila, el mecanismo de aplicación en el lado de la red y las consideraciones de cumplimiento normativo más importantes para 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 local o en la nube. Al añadir WeChat OAuth, está introduciendo un proveedor de identidad de terceros en ese flujo. Esta es la secuencia. El invitado se conecta a su 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 su Captive Portal. La página del portal se carga y presenta las opciones de inicio de sesión, incluida WeChat. El invitado toca el inicio de sesión de WeChat. El servidor de su portal redirige el navegador al endpoint de autorización de WeChat en open.weixin.qq.com, pasando su AppID, el URI de redirección, el tipo de respuesta (response_type) de código y el alcance (scope). WeChat gestiona la autenticación de forma totalmente independiente 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 en la aplicación de WeChat, la experiencia puede ser silenciosa con el alcance snsapi_base (sin solicitud de consentimiento en absoluto). A continuación, WeChat redirige de nuevo a la URI de redirección de su portal con un código de autorización temporal. El servidor de su portal intercambia ese código por un token de acceso llamando a api.weixin.qq.com/sns/oauth2/access_token, pasando su 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 concedido. Si ha solicitado el alcance snsapi_userinfo, puede realizar una segunda llamada a la API para recuperar el apodo, el avatar, el sexo y la ciudad del usuario. Ahora, los dos registros en las plataformas. Aquí es donde fallan la mayoría de las implementaciones. WeChat tiene dos plataformas de desarrolladores distintas. WeChat Open Platform, en open.weixin.qq.com, gestiona aplicaciones de sitios web y aplicaciones móviles. 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 atienda a usuarios dentro del navegador integrado de WeChat, se necesita una Service Account en la Official Accounts Platform. Una Subscription Account no servirá, ya que no tiene permisos de autorización de página web OAuth. Una Service Account sí los tiene y es compatible con los alcances (scopes) 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), se necesita una Website Application registrada en la Open Platform. Esta opción 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 los despliegues en establecimientos utilizan ambos. Un cliente de la red WiFi de un hotel puede abrir el portal en Chrome, ver un código QR, escanearlo con WeChat y autenticarse. O puede seguir un enlace dentro del propio WeChat, llegar al navegador integrado de la aplicación y autenticarse de forma silenciosa con snsapi_base. Hablemos de la selección del alcance (scope), ya que este es un punto de decisión crucial. snsapi_base devuelve únicamente el OpenID, un identificador único para ese usuario dentro de su Official Account. No requiere ninguna solicitud de consentimiento al usuario. La autenticación es invisible para él. Esto es ideal para clientes habituales 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, la foto de perfil, el género, la configuración de idioma y la ciudad. Requiere una pantalla de consentimiento explícita. El usuario verá un mensaje preguntándole si permite que su Official Account acceda a su información. La mayoría de los usuarios lo aceptan, pero existe cierta fricción. La elección correcta depende de su caso de uso. Para el registro de un cliente nuevo sobre el que desea crear un perfil, utilice snsapi_userinfo y combínelo con una capa de consentimiento que cumpla con el GDPR en su página de portal. Para un cliente habitual que ya ha dado su consentimiento y del que ya tiene un perfil, utilice snsapi_base para una autenticación silenciosa. Por último, la aplicación de red. Obtener un token OAuth demuestra la identidad, pero no abre la red de forma automática. Necesita un mecanismo para traducir una autenticación correcta en acceso a la red. Los dos enfoques estándar son RADIUS Change of Authorisation (CoA), definido en el RFC 3576, y el bypass de dirección MAC. 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 clase empresarial. Con el bypass de MAC, el servidor del portal registra la dirección MAC del dispositivo como un cliente autorizado y el controlador lo permite. El bypass de MAC es más sencillo de implementar pero menos seguro, ya que las direcciones MAC se pueden suplantar. La plataforma Guest WiFi de Purple gestiona ambos mecanismos. Una vez completado 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 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 presentarle los cinco factores que hacen que fallen las implementaciones de portales cautivos con OAuth de WeChat. Primero: la discrepancia en la URI de redirección. WeChat valida la URI de redirección 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, incluidos los entornos de prueba (staging). 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 la identidad de su aplicación y realizar llamadas a las API de WeChat en su nombre. Tercero: la falta de protección CSRF. El parámetro de estado (state) en la solicitud de OAuth existe específicamente para evitar la falsificación de solicitudes en sitios cruzados. Genere un valor de estado criptográficamente aleatorio, almacénelo en la sesión del usuario y valídelo cuando WeChat realice la redirección 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 QR de Open Platform para navegadores estándar), los usuarios experimentarán fallos o errores. Quinto: la alineación con GDPR y PIPL. Si ofrece servicios a visitantes europeos, el GDPR se aplica a los datos que recopila a través de OAuth de WeChat. Si ofrece servicios a visitantes chinos, la Ley de Protección de Información Personal de China (PIPL) se aplica a cómo procesa sus datos. Ambas normativas exigen una base jurídica 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. Recopile lo que recopile, documente su base legal y su periodo 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 ofrezca inicio de sesión por correo electrónico y SMS? Sí. La mayoría de las plataformas de portal empresarial, incluida Purple, admiten múltiples métodos de autenticación en la misma página del portal. WeChat aparece como una opción junto a las demás. Pregunta: ¿Funciona OAuth de WeChat en iOS? Sí, pero con un matiz. El marco App Tracking Transparency de Apple no afecta a los flujos 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 el flujo de redirección. La propia aplicación de WeChat se encarga de la autenticación. Pregunta: ¿Qué pasa si la API de WeChat no está disponible? Su portal debe implementar una alternativa. Si la llamada a la API de WeChat agota el tiempo de espera o devuelve un error, redirija al usuario a un método de inicio de sesión alternativo. No los deje con la 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 varias 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, que requiere que sus cuentas estén vinculadas en la Open Platform. - RESUMEN Y SIGUIENTES PASOS (aproximadamente 1 minuto) Para resumir. 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 servirá a más de mil millones de visitantes potenciales sin la fricción de las contraseñas. Los siguientes pasos prácticos son estos. En primer lugar, determine si sus visitantes acceden al portal dentro del navegador interno de la aplicación de WeChat o en un navegador móvil estándar - eso determina qué registro de plataforma necesita. En segundo lugar, decida el alcance - snsapi_base para huéspedes recurrentes, snsapi_userinfo para el registro por primera vez con consentimiento. En tercer lugar, confirme que el hardware de su red es compatible con RADIUS CoA o configure el bypass de MAC como alternativa. En cuarto lugar, revise su aviso de privacidad y el flujo de consentimiento según los requisitos de GDPR y PIPL. En quinto lugar, pruebe la URI de redirección, la validación del parámetro de estado y la detección del navegador interno de la aplicación antes de publicar. Si desea ver cómo gestiona Purple el OAuth de WeChat como parte de una plataforma más amplia de WiFi de invitados y análisis - en 80 000 establecimientos y 440 millones de inicios de sesión en 2024 - visite purple.ai o hable con su equipo de cuentas. Gracias por escuchar. - FIN DEL GUION