Como Configurar a Autenticação OAuth do WeChat para Captive Portals

COMO CONFIGURAR AUTENTICAÇÃO OAUTH WECHAT PARA CAPTIVE PORTALS Um Briefing Técnico da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto) Bem-vindo. Se você é responsável pelo WiFi de visitantes em um hotel, rede de varejo, estádio ou centro de convenções que atende visitantes chineses, este briefing é para você. O WeChat tem 1,38 bilhão de usuários ativos mensais, de acordo com os dados de 2024 da Tencent. A esmagadora maioria está na China, mas a plataforma também tem uma presença internacional significativa - 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 WiFi 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 tem 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 que você realmente possa usar. É isso que vamos abordar hoje. Vamos passar pelo fluxo do OAuth 2.0, os dois registros de plataforma que você precisa, a decisão de escopo que determina quais dados você coleta, o mecanismo de aplicação do lado da rede e as considerações de conformidade que importam em 2026. --- MERGULHO TÉCNICO PROFUNDO (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 ou na nuvem. Quando você adiciona o OAuth do WeChat, 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 controladora 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 em open.weixin.qq.com, passando seu AppID, a URI de redirecionamento, o tipo de resposta de código e o escopo. O WeChat lida com 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 ele estiver usando o navegador interno do WeChat, a experiência pode ser silenciosa com o escopo snsapi_base - sem nenhum prompt 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 chamando api.weixin.qq.com/sns/oauth2/access_token, passando seu AppID, AppSecret, o código e o tipo de concessão de authorization_code. O WeChat retorna um token de acesso, um token de atualização, o OpenID 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 em open.weixin.qq.com lida com aplicativos de site e aplicativos móveis. A WeChat Official Accounts Platform em mp.weixin.qq.com lida com contas públicas - o que a maioria dos locais realmente precisa. Para um Captive Portal que atende convidados 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 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 usa o escopo snsapi_login e apresenta um código QR que o usuário escaneia com o aplicativo WeChat deles. Na prática, a maioria das implantações em locais usa ambos. Um convidado no WiFi de um hotel pode abrir o portal no Chrome, ver um código QR, escaneá-lo com o WeChat e autenticar. Ou eles podem seguir um link no próprio WeChat, cair no navegador interno e autenticar silenciosamente com snsapi_base. Vamos falar sobre a seleção de escopo, pois este é um ponto de decisão real. O snsapi_base retorna apenas o OpenID - um identificador exclusivo para aquele usuário dentro da sua Official Account. Ele não requer nenhuma solicitação de consentimento do usuário. A autenticação é invisível para o usuário. Isso é ideal para convidados recorrentes que você já traçou o perfil, ou para locais onde você deseja atrito zero à custa de zero novos dados. O snsapi_userinfo retorna o OpenID mais o apelido do WeChat do usuário, foto de perfil, gênero, configuração de idioma e cidade. Requer uma tela de consentimento explícita. O usuário vê uma mensagem perguntando se permite que sua Official Account acesse suas informações. A maioria dos usuários aceita, mas há atrito. A escolha certa depende do seu caso de uso. Para o registro de um convidado pela primeira vez, onde você deseja criar um perfil, use snsapi_userinfo e combine-o com uma camada de consentimento em conformidade com a GDPR na página do seu portal. Para um convidado recorrente que já consentiu e de quem você já possui o perfil, use snsapi_base para reautenticação silenciosa. Agora, o lado da aplicação de 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 RADIUS Change of Authorisation, definida na RFC 3576, e 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 convidados. Isso funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e a maioria dos controladores de nível corporativo. 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 gerencia ambos os mecanismos. Após a conclusão do WeChat OAuth, a sobreposição de nuvem da Purple envia o sinal apropriado para o hardware subjacente - seja ele 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 as cinco coisas que fazem as implementações de Captive Portal com WeChat OAuth falharem. Primeiro: incompatibilidade da URI de redirecionamento. O WeChat valida a URI de redirecionamento com base no domínio autorizado que você registrou na plataforma. Se o servidor do seu portal usar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo OAuth falhará com o erro 40029 - código inválido. Registre cada variante de domínio que você usa, incluindo ambientes de teste. Segundo: o AppSecret no lado do cliente. Seu AppSecret nunca deve aparecer no JavaScript do lado do cliente ou em um binário de aplicativo móvel. Ele pertence ao seu servidor. Se for exposto, 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. 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: a falha na detecção do navegador integrado. O navegador interno do WeChat define uma string de user agent específica contendo "MicroMessenger". Se o seu portal não detectar isso e fornecer o fluxo OAuth correto - fluxo de Conta Oficial para o navegador interno, fluxo de QR da Open Platform para navegadores padrão - os usuários terão uma experiência instável ou um erro. Quinto: alinhamento com GDPR e PIPL. Se você atende visitantes europeus, a GDPR se aplica aos dados que você coleta via WeChat OAuth. Se você atende visitantes chineses, a Lei de Proteção de Informações Pessoais da China - PIPL - se aplica a como você processa os dados deles. 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 jurídica e seu período de retenção. - PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Pergunta: 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 empresarial, incluindo a Purple, suporta múltiplos métodos de autenticação na mesma página do portal. O WeChat aparece como uma opção ao lado de outras. Pergunta: O OAuth do WeChat funciona no iOS? Sim, mas com uma nuance. A estrutura de Transparência do Rastreamento de Aplicativos da Apple não afeta os fluxos de OAuth do lado do servidor. O login do WeChat no Safari no iOS funciona através do fluxo de código QR ou do fluxo de redirecionamento. O próprio aplicativo WeChat lida com a autenticação. Pergunta: O que acontece se a API do WeChat estiver indisponível? Seu portal deve implementar uma alternativa de segurança. Se a chamada da API do WeChat expirar ou retornar um erro, redirecione o usuário para um método de login alternativo. Não os deixe com uma tela em branco. Pergunta: Posso usar o OpenID como um identificador persistente de cliente? Dentro da sua Conta Oficial, sim. O OpenID é estável para um determinado usuário e uma determinada Conta Oficial. Se você tiver várias Contas Oficiais, o mesmo usuário terá diferentes OpenIDs nelas. Para resolução de identidade entre contas, o WeChat fornece um UnionID, que exige que suas contas estejam vinculadas na Open Platform. --- RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto) Para resumir. A autenticação OAuth do WeChat para portais cativos é um exercício de registro em duas plataformas, uma decisão de escopo, uma integração de aplicaçã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 são estes. Primeiro, determine se seus visitantes encontram o portal dentro do navegador interno do WeChat ou em um navegador móvel padrão - isso determina qual registro de plataforma você precisa. Segundo, decida sobre o escopo - snsapi_base para visitantes recorrentes, snsapi_userinfo para o primeiro registro com consentimento. Terceiro, confirme se o hardware da sua rede suporta RADIUS CoA ou configure o bypass de MAC como alternativa. Quarto, revise seu aviso de privacidade e fluxo de consentimento em relação aos requisitos do GDPR e PIPL. Quinto, 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 OAuth do WeChat como parte de uma plataforma mais ampla de WiFi de Convidados 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