Integrating WeChat Authentication with Guest WiFi Captive Portals

COMO CONFIGURAR A AUTENTICAÇÃO OAUTH DO WECHAT PARA CAPTIVE PORTALS Um Informativo Técnico da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto) Boas-vindas. Se você é responsável pelo Wi-Fi de visitantes em um hotel, rede de varejo, estádio ou centro de convenções que atende visitantes chineses, este informativo é para você. O WeChat possui 1,38 bilhão de usuários ativos mensais, de acordo com os dados de 2024 da Tencent. A grande maioria está na China, mas a plataforma também possui uma presença internacional expressiva - quatro milhões de usuários nos Estados Unidos, 12 milhões na Malásia e números crescentes em todo o Sudeste Asiático, Europa e Oriente Médio. Quando um visitante chinês se conecta ao seu Wi-Fi e vê uma página de login apenas com e-mail, Facebook ou um código de voucher, ele enfrenta uma barreira imediata. Ele pode não ter um endereço de e-mail local configurado naquele dispositivo. Ele quase certamente possui o WeChat. Portanto, a questão não é se você deve oferecer o login do WeChat - é como configurá-lo de forma correta, segura e de uma maneira que gere dados proprietários (first-party data) que você possa realmente usar. É isso que vamos abordar hoje. Vamos percorrer o fluxo do OAuth 2.0, os dois registros de plataforma necessários, a decisão de escopo (scope) que determina quais dados você coleta, o mecanismo de imposição do lado da rede e as considerações de conformidade que importam em 2026. --- APROFUNDAMENTO TÉCNICO (aproximadamente 5 minutos) Vamos começar com a arquitetura. Um Captive Portal intercepta o tráfego HTTP de um dispositivo não autenticado e o redireciona para uma página de login. Essa página de login é hospedada em um servidor de portal - seja local (on-premises) ou na nuvem. Ao adicionar o WeChat OAuth, você está inserindo um provedor de identidade de terceiros nesse fluxo. Aqui está a sequência. O visitante se conecta ao seu SSID. O ponto de acesso ou controlador sem fio detecta que o dispositivo não possui uma sessão autenticada e redireciona todo o tráfego HTTP para a URL do seu Captive Portal. A página do portal é carregada e apresenta as opções de login - incluindo o WeChat. O visitante toca no login do WeChat. O servidor do seu portal redireciona o navegador para o endpoint de autorização do WeChat, transmitindo o seu App ID, a URI de redirecionamento, o tipo de resposta (response type) do código e o escopo (scope). O WeChat gerencia a autenticação inteiramente em seus próprios servidores. Se o visitante já estiver logado no WeChat em seu navegador, ele verá uma tela de consentimento. Se estiver usando o navegador interno do aplicativo WeChat, a experiência pode ser silenciosa com o escopo base snsapi - sem nenhuma solicitação de consentimento. O WeChat então redireciona de volta para a URI de redirecionamento do seu portal com um código de autorização temporário. O servidor do seu portal troca esse código por um token de acesso, transmitindo seu App ID, App Secret, o código e o tipo de concessão (grant type) do código de autorização. O WeChat retorna um token de acesso, um token de atualização (refresh token), o Open ID do usuário e o escopo concedido. Se você solicitou o escopo snsapi userinfo, poderá fazer uma segunda chamada de API para recuperar o apelido, avatar, gênero e cidade do usuário. Agora, os dois registros de plataforma. É aqui que a maioria das implementações dá errado. O WeChat possui duas plataformas de desenvolvedor distintas. A WeChat Open Platform gerencia aplicativos de sites e aplicativos móveis. A WeChat Official Accounts Platform gerencia contas públicas - o que a maioria dos locais realmente precisa. Para um Captive Portal que atende usuários dentro do navegador interno do WeChat, você precisa de uma Service Account na Official Accounts Platform. Uma Subscription Account não funcionará - ela não possui permissões de autorização de página web via OAuth. Uma Service Account possui, e suporta os escopos snsapi base e snsapi userinfo. Para um Captive Portal acessado a partir de um navegador móvel padrão fora do WeChat - Chrome no Android, Safari no iOS - você precisa de um Website Application registrado na Open Platform. Isso utiliza o escopo snsapi login e apresenta um código QR que o usuário escaneia com o aplicativo WeChat. Na prática, a maioria das implantações em locais físicos utiliza ambos. Um visitante na rede WiFi de um hotel pode abrir o portal no Chrome, ver um código QR, escaneá-lo com o WeChat e se autenticar. Ou pode seguir um link dentro do próprio WeChat, cair no navegador interno e se autenticar silenciosamente com o snsapi base. Vamos falar sobre a seleção de escopo, pois este é um ponto de decisão real. O snsapi base retorna apenas o Open ID - um identificador exclusivo para aquele usuário dentro da sua Official Account. Ele não exige nenhuma solicitação de consentimento do usuário. A autenticação é invisível para o usuário. Isso é ideal para visitantes que retornam e que você já traçou o perfil, ou para locais onde você deseja atrito zero. O snsapi userinfo retorna o Open ID mais o apelido do WeChat do usuário, foto de perfil, gênero, configuração de idioma e cidade. Ele exige uma tela de consentimento explícita. A maioria dos usuários aceita, mas há atrito. A escolha certa depende do seu caso de uso. Para o registro de um visitante de primeira viagem onde você deseja criar um perfil, use snsapi userinfo e combine-o com uma camada de consentimento em conformidade com a GDPR na sua página de portal. Para um visitante que retorna, que já deu consentimento e cujo perfil você já possui, use snsapi base para uma reautenticação silenciosa. Agora, o lado da aplicação na rede. Obter um token OAuth comprova a identidade, mas não abre a rede automaticamente. Você precisa de um mecanismo para traduzir uma autenticação bem-sucedida em acesso à rede. As duas abordagens padrão são o RADIUS Change of Authorisation, definido na RFC 3576, e o bypass de endereço MAC. Com o RADIUS CoA, o servidor do seu portal envia uma solicitação de CoA para o controlador de rede após o OAuth bem-sucedido, e o controlador move o dispositivo da VLAN não autenticada para a VLAN de visitantes. Isso funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e a maioria dos controladores de classe empresarial. Com o bypass de MAC, o servidor do portal registra o endereço MAC do dispositivo como um cliente autorizado, e o controlador o permite. O bypass de MAC é mais simples de implementar, mas menos seguro, porque os endereços MAC podem ser falsificados. A plataforma de Guest WiFi da Purple lida com ambos os mecanismos. Após a conclusão do WeChat OAuth, a sobreposição em nuvem da Purple envia o sinal apropriado para o hardware subjacente - seja Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme ou Fortinet. O operador do local não precisa gerenciar essa tradução manualmente. --- RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS (aproximadamente 2 minutos) Deixe-me apresentar os cinco motivos que fazem com que as implementações de Captive Portal com WeChat OAuth falhem. Primeiro: incompatibilidade da URI de redirecionamento. O WeChat valida a URI de redirecionamento em relação ao domínio autorizado que você registrou na plataforma. Se o seu servidor de portal usar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo de OAuth falhará com o erro 40029 - código inválido. Registre todas as variantes de domínio que você utiliza, incluindo ambientes de homologação. Segundo: a App Secret no lado do cliente. Sua App Secret nunca deve aparecer no JavaScript do lado do cliente. Ela pertence ao seu servidor. Se for exposta, qualquer pessoa poderá se passar pelo seu aplicativo e chamar as APIs do WeChat em seu nome. Terceiro: falta de proteção CSRF. O parâmetro de estado na solicitação OAuth existe especificamente para evitar falsificação de solicitação entre sites (cross-site request forgery). Gere um valor de estado criptograficamente aleatório, armazene-o na sessão do usuário e valide-o quando o WeChat redirecionar de volta. Ignorar isso cria uma vulnerabilidade real. Quarto: falha na detecção do navegador integrado. O navegador integrado do WeChat define uma string de user agent específica contendo MicroMessenger. Se o seu portal não detectar isso e fornecer o fluxo de OAuth correto, os usuários terão uma experiência instável ou um erro. Quinto: alinhamento com GDPR e PIPL. Se você atende a visitantes europeus, a GDPR se aplica. Se você atende a visitantes chineses, a Lei de Proteção de Informações Pessoais da China - PIPL - se aplica. Ambas exigem uma base legal para o processamento, limitação clara de finalidade e minimização de dados. O snsapi base é mais fácil de justificar sob os princípios de minimização de dados do que o snsapi userinfo. Independentemente do que você coletar, documente sua base legal e seu período de retenção. --- PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Posso usar o login do WeChat em um portal que também oferece login por e-mail e SMS? Sim. A maioria das plataformas de portal corporativo, incluindo a Purple, suporta múltiplos métodos de autenticação na mesma página de portal. O WeChat OAuth funciona no iOS? Sim. O login do WeChat no Safari no iOS funciona por meio do fluxo de código QR ou do fluxo de redirecionamento. O próprio aplicativo WeChat lida com a autenticação. O que acontece se a API do WeChat estiver indisponível? Implemente uma alternativa. Se a chamada da API do WeChat expirar ou retornar um erro, redirecione o usuário para um método de login alternativo. Posso usar o Open ID como um identificador de cliente persistente? Dentro de sua Conta Oficial, sim. Para resolução de identidade cruzada entre múltiplas propriedades, use o UnionID em seu lugar. --- RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto) Para resumir. A autenticação WeChat OAuth para Captive Portals é um exercício de registro em duas plataformas, uma decisão de escopo, uma integração de imposição de rede e uma revisão de conformidade. Acerte esses quatro pontos e você terá um método de login que atende a mais de um bilhão de visitantes em potencial com zero atrito de senha. Os próximos passos práticos: determine se seus visitantes encontram o portal dentro do navegador interno do WeChat ou em um navegador móvel padrão. Decida sobre o escopo - snsapi base para visitantes recorrentes, snsapi userinfo para registro de primeira viagem com consentimento. Confirme se o hardware da sua rede suporta RADIUS CoA. Revise seu aviso de privacidade em relação ao GDPR e ao PIPL. Teste a URI de redirecionamento, a validação do parâmetro de estado e a detecção do navegador interno antes de entrar no ar. Se você quiser ver como a Purple lida com o WeChat OAuth como parte de uma plataforma mais ampla de Guest WiFi e analytics - em 80.000 locais e 440 milhões de logins em 2024 - visite purple.ai ou fale com sua equipe de conta. Obrigado por ouvir. --- FIM DO ROTEIRO