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

CÓMO CONFIGURAR LA AUTENTICACIÓN OAUTH DE WECHAT PARA CAPTIVE PORTALS Un informe técnico de Purple - Aproximadamente 10 minutos --- INTRODUCCIÓN Y CONTEXTO (aproximadamente 1 minuto) Bienvenido. Si es responsable del WiFi para invitados en un hotel, cadena de tiendas, estadio o centro de conferencias que atiende a visitantes chinos, este informe es para usted. 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 Oriente Medio. Cuando un invitado chino se conecta a su 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 tenga una dirección de correo electrónico local configurada en ese dispositivo. Pero es casi seguro que tiene WeChat. Por lo tanto, la pregunta no es si debe ofrecer el inicio de sesión con WeChat, sino cómo configurarlo correctamente, de forma segura y de manera que genere datos de primera mano que realmente pueda utilizar. Eso es lo que vamos a cubrir hoy. Repasaremos el flujo de OAuth 2.0, los dos registros de plataforma que necesita, la decisión sobre el alcance (scope) que determina qué datos recopila, el mecanismo de aplicación en el 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 está alojada en un servidor de portal, ya sea de forma local o en la nube. Al añadir OAuth de WeChat, 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, incluido WeChat. El invitado pulsa en el inicio de sesión de WeChat. El servidor de su portal redirige el navegador al punto de conexión de autorización de WeChat en open.weixin.qq.com, pasando su AppID, la URI de redirección, el tipo de respuesta 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 WeChat, la experiencia puede ser silenciosa con el alcance `snsapi_base`, sin ninguna solicitud de consentimiento. 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 de authorization_code. WeChat devuelve un token de acceso, un token de actualización, el OpenID del usuario y el alcance concedido. Si solicitó el alcance `snsapi_userinfo`, puede realizar una segunda llamada a la API para recuperar el apodo, el avatar, el género y la 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. La Plataforma Abierta de WeChat (Open Platform) en open.weixin.qq.com gestiona aplicaciones de sitios web y aplicaciones móviles. La Plataforma de Cuentas Oficiales de WeChat en mp.weixin.qq.com gestiona cuentas públicas, que es lo que realmente necesitan la mayoría de los establecimientos. Para un captive portal que atiende a invitados dentro del navegador integrado de WeChat, necesita una Cuenta de Servicio en la Plataforma de Cuentas Oficiales. Una Cuenta de Suscripción no funcionará, ya que no tiene permisos de autorización de páginas web de OAuth. Una Cuenta de Servicio sí los tiene y admite los alcances `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), necesita una Aplicación Web registrada en la Plataforma Abierta. Esta utiliza el alcance `snsapi_login` y presenta 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 invitado 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 en el propio WeChat, aterrizar en el navegador integrado y autenticarse silenciosamente con `snsapi_base`. Hablemos de la selección del alcance, porque este es un punto de decisión crucial. `snsapi_base` devuelve solo 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 invitados recurrentes de los que ya tiene un perfil, o para establecimientos donde desea una fricción cero a cambio de no recopilar 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 ve una solicitud que le pregunta si permite que su Cuenta Oficial acceda a su información. La mayoría de los usuarios la aceptan, pero genera fricción. La elección correcta depende de su caso de uso. Para el registro de un invitado por primera vez en el que desea crear un perfil, utilice `snsapi_userinfo` y combínelo con una capa de consentimiento que cumpla con la GDPR en la página de su portal. Para un invitado recurrente que ya ha dado su consentimiento y del que ya dispone de su perfil, utilice `snsapi_base` para una reautenticación silenciosa. Ahora, el lado de la aplicación en la red. Obtener un token de 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 (CoA), definido en RFC 3576, y la omisión de dirección MAC (MAC address bypass). Con RADIUS CoA, el servidor de su portal envía una solicitud de CoA al controlador de red tras 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 la omisión de MAC, el servidor del portal registra la dirección MAC del dispositivo como un cliente autorizado y el controlador lo permite. La omisión de MAC es más sencilla de implementar pero menos segura, ya que las direcciones MAC se pueden suplantar. La plataforma de WiFi para invitados 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 o Fortinet. El operador del establecimiento no necesita gestionar esa traducción manualmente. --- RECOMENDACIONES DE IMPLEMENTACIÓN Y ERRORES COMUNES (aproximadamente 2 minutos) Permítame indicarle las cinco cosas que hacen que fallen las implementaciones de captive portal con OAuth de WeChat. Primero: la discrepancia en la URI de redirección. WeChat valida la URI de redirección con respecto al dominio autorizado que registró en la plataforma. Si el servidor de su portal utiliza un subdominio diferente, una ruta diferente 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 código 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 contra CSRF. El parámetro de estado (state) en la solicitud de OAuth existe específicamente para evitar la falsificación de peticiones en sitios cruzados. Genere un valor de estado 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 falta 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 ofrece el flujo de OAuth correcto (flujo de Cuenta Oficial para el navegador integrado, flujo de código QR de la Plataforma Abierta para navegadores estándar), los usuarios tendrán una experiencia rota o un error. Quinto: la alineación con la GDPR y la PIPL. Si atiende a visitantes europeos, la GDPR se aplica a los datos que recopila a través de 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 marcos requieren una base legal para el tratamiento, 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) Pregunta: ¿Puedo utilizar el inicio de sesión de 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, 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 el OAuth de WeChat en iOS? Sí, pero con un matiz. El marco de transparencia de seguimiento de aplicaciones (App Tracking Transparency) de Apple no afecta a los flujos de OAuth del lado del servidor. El inicio de sesión de 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é ocurre 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 lo deje con una pantalla en blanco. Pregunta: ¿Puedo utilizar 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 OpenID en cada una de ellas. Para la resolución de identidad entre cuentas, WeChat proporciona un UnionID, lo que 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 captive portals es un ejercicio de registro en dos plataformas, una decisión de alcance (scope), una integración de aplicación de red y una revisión de cumplimiento normativo. Si hace bien esas cuatro cosas, tendrá un método de inicio de sesión que atenderá a más de mil millones de visitantes potenciales con cero fricciones de contraseña. Los pasos prácticos a seguir son los siguientes. Primero, determine si sus visitantes acceden al portal dentro del navegador integrado de WeChat o en un navegador móvil estándar; eso determinará qué registro de plataforma necesita. Segundo, decida el alcance: `snsapi_base` para invitados recurrentes, `snsapi_userinfo` para el registro por primera vez con consentimiento. Tercero, confirme que el hardware de su red admite RADIUS CoA o configure la omisión de MAC como alternativa. Cuarto, revise su aviso de privacidad y el flujo de consentimiento frente a los requisitos de la GDPR y la PIPL. Quinto, pruebe la URI de redirección, la validación del parámetro de estado y la detección del navegador integrado antes de la puesta en marcha. Si desea ver cómo gestiona Purple el OAuth de WeChat como parte de una plataforma más amplia de WiFi para invitados y analítica (en 80.000 establecimientos y con 440 millones de inicios de sesión en 2024), visite purple.ai o hable con su equipo de cuentas. Gracias por su atención. --- FIN DEL INFORME