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

COMO CONFIGURAR A AUTENTICAÇÃO OAUTH DO WECHAT PARA CAPTIVE PORTALS Uma Sessão Técnica da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto) Bem-vindo. Se é responsável pelo WiFi de convidados num hotel, cadeia de retalho, estádio ou centro de conferências que recebe visitantes chineses, esta sessão é para si. O WeChat tem 1,38 mil milhões de utilizadores ativos mensais, de acordo com os dados de 2024 da Tencent. A esmagadora maioria está na China, mas a plataforma tem também uma pegada internacional expressiva - quatro milhões de utilizadores nos Estados Unidos, 12 milhões na Malásia e números crescentes em todo o Sudeste Asiático, Europa e Médio Oriente. Quando um convidado chinês se liga ao seu WiFi e vê uma página de login apenas com e-mail, Facebook ou um código de voucher, depara-se com uma fricção imediata. Pode não ter um endereço de e-mail local configurado nesse dispositivo. No entanto, tem quase de certeza o WeChat. Por isso, a questão não é se deve oferecer o login com o WeChat - é como configurá-lo corretamente, de forma segura e de modo a gerar dados primários (first-party data) que possa realmente utilizar. É isso que vamos abordar hoje. Vamos analisar o fluxo OAuth 2.0, os dois registos de plataforma de que necessita, a decisão de âmbito (scope) que determina quais os dados que recolhe, o mecanismo de imposiçã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 pela arquitetura. Um Captive Portal intercepta o tráfego HTTP de um dispositivo não autenticado e redireciona-o para uma página de login. Essa página de login está alojada num servidor de portal - localmente ou na cloud. Quando adiciona o WeChat OAuth, está a introduzir um fornecedor de identidade de terceiros nesse fluxo. Eis a sequência. O convidado liga-se ao seu SSID. O ponto de acesso ou controlador sem fios deteta que o dispositivo não tem uma sessão autenticada e redireciona todo o tráfego HTTP para o URL do seu Captive Portal. A página do portal é carregada e apresenta opções de login - incluindo o WeChat. O convidado toca em login com WeChat. O seu servidor do portal redireciona o browser para o endpoint de autorização do WeChat em open.weixin.qq.com, transmitindo o seu AppID, o URI de redirecionamento, o tipo de resposta do código e o âmbito (scope). O WeChat lida com a autenticação inteiramente nos seus próprios servidores. Se o convidado já tiver sessão iniciada no WeChat no seu browser, verá um ecrã de consentimento. Se estiver a utilizar o browser integrado na aplicação do WeChat, a experiência pode ser silenciosa com o âmbito (scope) snsapi_base - sem qualquer aviso de consentimento. O WeChat redireciona então de volta para o URI de redirecionamento do seu portal com um código de autorização temporário. O seu servidor do portal troca esse código por um token de acesso ao chamar api.weixin.qq.com/sns/oauth2/access_token, transmitindo o seu AppID, AppSecret, o código e o tipo de concessão de authorization_code. O WeChat devolve um token de acesso, um token de atualização, o OpenID do utilizador e o âmbito (scope) concedido. Se tiver solicitado o âmbito (scope) snsapi_userinfo, pode então fazer uma segunda chamada de API para obter o pseudónimo (nickname), avatar, género e cidade do utilizador.Agora, os dois registos na plataforma. É aqui que a maioria das implementações falha. O WeChat tem duas plataformas de programador distintas. A WeChat Open Platform em open.weixin.qq.com gere aplicações web e aplicações móveis. A WeChat Official Accounts Platform em mp.weixin.qq.com gere contas públicas - aquilo de que a maioria dos locais realmente necessita. Para um Captive Portal que serve clientes dentro do browser integrado do WeChat, necessita de uma Service Account na Official Accounts Platform. Uma Subscription Account não irá funcionar - não possui permissões de autorização de página web OAuth. Uma Service Account possui, e suporta ambos os âmbitos snsapi_base e snsapi_userinfo. Para um Captive Portal acedido a partir de um browser móvel padrão fora do WeChat - Chrome no Android, Safari no iOS - necessita de uma Website Application registada na Open Platform. Esta utiliza o âmbito snsapi_login e apresenta um código QR que o utilizador lê com a sua aplicação WeChat. Na prática, a maioria das implementações em locais utiliza ambos. Um cliente no WiFi de um hotel pode abrir o portal no Chrome, ver um código QR, lê-lo com o WeChat e autenticar-se. Ou pode seguir uma ligação no próprio WeChat, aceder através do browser integrado e autenticar-se silenciosamente com snsapi_base. Falemos sobre a seleção do âmbito, porque este é um ponto de decisão real. O snsapi_base devolve apenas o OpenID - um identificador exclusivo para esse utilizador dentro da sua Official Account. Não requer qualquer pedido de consentimento do utilizador. A autenticação é invisível para o utilizador. Isto é ideal para clientes que regressam e que já foram perfilados, ou para locais onde pretende atrito zero à custa de zero novos dados. O snsapi_userinfo devolve o OpenID mais a alcunha do WeChat do utilizador, imagem de perfil, género, definição de idioma e cidade. Requer um ecrã de consentimento explícito. O utilizador vê uma mensagem a perguntar se permite que a sua Official Account aceda às suas informações. A maioria dos utilizadores aceita, mas existe atrito. A escolha certa depende do seu caso de utilização. Para o primeiro registo de um cliente onde pretende criar um perfil, utilize o snsapi_userinfo e associe-o a uma camada de consentimento em conformidade com o GDPR na página do seu portal. Para um cliente que regressa, que já consentiu e cujo perfil já possui, utilize o snsapi_base para uma nova autenticação silenciosa. Agora, a vertente de aplicação na rede. Obter um token OAuth prova a identidade, mas não abre automaticamente a rede. Necessita 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 MAC address bypass. Com o RADIUS CoA, o seu servidor de portal envia um pedido 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. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e a maioria dos controladores de classe empresarial. Com o MAC bypass, o servidor de portal regista o endereço MAC do dispositivo como um cliente autorizado, e o controlador permite-o. O MAC bypass é 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. Depois de o WeChat OAuth ser concluído, o cloud overlay 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 espaço não precisa de gerir essa tradução manualmente. - RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS (aproximadamente 2 minutos) Deixe-me apresentar-lhe as cinco coisas que fazem com que as implementações de Captive Portal com WeChat OAuth falhem. Primeiro: a incompatibilidade do URI de redirecionamento. O WeChat valida o URI de redirecionamento em relação ao domínio autorizado que registou na plataforma. Se o seu servidor de portal utilizar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo de OAuth falha com o erro 40029 - código inválido. Registe todas as variantes de domínio que utiliza, incluindo ambientes de teste. Segundo: o AppSecret no lado do cliente. O seu AppSecret nunca deve aparecer no JavaScript do lado do cliente ou num binário de aplicação móvel. Ele pertence ao seu servidor. Se for exposto, qualquer pessoa pode personificar a sua aplicação e chamar as API do WeChat em seu nome. Terceiro: falta de proteção CSRF. O parâmetro de estado no pedido de OAuth existe especificamente para evitar a falsificação de pedidos entre sites. Gere um valor de estado aleatório de forma criptográfica, armazene-o na sessão do utilizador e valide-o quando o WeChat redirecionar de volta. Ignore isto e terá uma vulnerabilidade real. Quarto: a falha de deteção do navegador na aplicação. O navegador integrado do WeChat define uma string de user agent específica contendo "MicroMessenger". Se o seu portal não detetar isto e não apresentar o fluxo de OAuth correto - fluxo de Conta Oficial para o navegador na aplicação, fluxo de QR da Open Platform para navegadores padrão - os utilizadores terão uma experiência com falhas ou um erro. Quinto: alinhamento com o GDPR e a PIPL. Se serve visitantes europeus, o GDPR aplica-se aos dados que recolhe através do WeChat OAuth. Se serve visitantes chineses, a Lei de Proteção de Informações Pessoais da China - PIPL - aplica-se à forma como processa os seus dados. Ambos exigem uma base legal para o processamento, uma limitação clara da finalidade e a minimização de dados. O snsapi_base é mais fácil de justificar ao abrigo dos princípios de minimização de dados do que o snsapi_userinfo. Independentemente do que recolher, documente a sua base jurídica e o seu período de retenção. - PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Pergunta: Posso utilizar o início de sessão WeChat num portal que também oferece início de sessão 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 WeChat OAuth funciona no iOS? Sim, mas com uma nuance. A framework App Tracking Transparency da Apple não afeta os fluxos OAuth do lado do servidor. O início de sessão WeChat no Safari no iOS funciona através do fluxo de código QR ou do fluxo de redirecionamento. A própria aplicação WeChat trata da autenticação. Pergunta: O que acontece se a API do WeChat estiver indisponível? O seu portal deve implementar uma alternativa de recurso. Se a chamada da API do WeChat expirar ou devolver um erro, redirecione o utilizador para um método de início de sessão alternativo. Não os deixe com um ecrã em branco. Pergunta: Posso utilizar o OpenID como um identificador de cliente persistente? Dentro da sua Official Account, sim. O OpenID é estável para um determinado utilizador e uma determinada Official Account. Se tiver várias Official Accounts, o mesmo utilizador terá OpenIDs diferentes entre elas. Para a resolução de identidade entre contas, o WeChat fornece um UnionID, o que requer que as suas contas estejam associadas na Open Platform. - RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto) Para resumir. A autenticação WeChat OAuth para portais cativos é um exercício de registo em duas plataformas, uma decisão de âmbito, uma integração de aplicação de rede e uma revisão de conformidade. Acerte nestes quatro pontos e terá um método de início de sessão que serve mais de mil milhões de visitantes potenciais com zero fricção de palavra-passe. Os próximos passos práticos são estes. Primeiro, determine se os seus visitantes encontram o portal dentro do navegador interno do WeChat ou num navegador móvel padrão - isso determina de qual registo de plataforma precisa. Segundo, decida sobre o âmbito - snsapi_base para visitantes que regressam, snsapi_userinfo para o primeiro registo com consentimento. Terceiro, confirme se o seu hardware de rede suporta RADIUS CoA ou configure o bypass de MAC como alternativa. Quarto, reveja o seu aviso de privacidade e o fluxo de consentimento face aos requisitos do GDPR e do PIPL. Quinto, teste o URI de redirecionamento, a validação do parâmetro de estado e a deteção do navegador interno antes de entrar em produção. Se quiser ver como a Purple lida com o WeChat OAuth como parte de uma plataforma mais ampla de WiFi para convidados e análise - em 80.000 locais e 440 milhões de inícios de sessão em 2024 - visite purple.ai ou fale com a sua equipa de conta. Obrigado por nos ouvir. - FIM DO GUIÃO