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

COMO CONFIGURAR A AUTENTICAÇÃO OAUTH DO WECHAT PARA CAPTIVE PORTALS Uma Apresentação Técnica da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E ENQUADRAMENTO (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 serve visitantes chineses, esta apresentaçã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 significativa - 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, enfrenta uma fricção imediata. Pode não ter um endereço de e-mail local configurado nesse dispositivo. Quase de certeza que tem o WeChat. Portanto, a questão não é se deve oferecer o login do 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 percorrer 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 aplicação do lado da rede e as considerações de conformidade que importam em 2026. --- MERGULHO TÉCNICO PROFUNDO (aproximadamente 5 minutos) Comecemos pela arquitetura. Um Captive Portal intercetará 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 nuvem. Quando adiciona o WeChat OAuth, está a inserir 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 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 as opções de login - incluindo o WeChat. O convidado toca no login do WeChat. O seu servidor de portal redireciona o navegador 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 trata da autenticação inteiramente nos seus próprios servidores. Se o convidado já tiver sessão iniciada no WeChat no seu navegador, verá um ecrã de consentimento. Se estiver a utilizar o navegador integrado na aplicação WeChat, a experiência pode ser silenciosa com o âmbito snsapi_base - sem qualquer pedido 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 de portal troca esse código por um token de acesso chamando 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 concedido. Se solicitou o âmbito snsapi_userinfo, pode então fazer uma segunda chamada de API para obter a alcunha, o avatar, o género e a cidade do utilizador. Agora, os dois registos de 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 espaços realmente necessita. Para um Captive Portal que serve utilizadores dentro do browser integrado do WeChat, necessita de uma Service Account na Official Accounts Platform. Uma Subscription Account não irá funcionar - não tem permissões de autorização de página web OAuth. Uma Service Account tem, e suporta tanto o âmbito snsapi_base como o 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 digitaliza com a sua aplicação WeChat. Na prática, a maioria das implementações em espaços físicos utiliza ambos. Um convidado no WiFi de um hotel pode abrir o portal no Chrome, ver um código QR, digitalizá-lo com o WeChat e autenticar-se. Ou pode seguir uma hiperligação no próprio WeChat, aceder ao browser integrado e autenticar-se silenciosamente com o snsapi_base. Falemos sobre a seleção de âmbito, porque este é um ponto de decisão real. O snsapi_base devolve apenas o OpenID - um identificador único para esse utilizador dentro da sua Official Account. Não requer qualquer pedido de consentimento ao utilizador. A autenticação é invisível para o utilizador. Isto é ideal para convidados recorrentes que já perfilou, ou para espaços onde deseja fricção zero à custa de zero novos dados. O snsapi_userinfo devolve o OpenID mais a alcunha do WeChat do utilizador, a imagem de perfil, o género, a definição de idioma e a cidade. Requer um ecrã de consentimento explícito. O utilizador vê um pedido a perguntar se permite que a sua Official Account aceda às suas informações. A maioria dos utilizadores aceita, mas existe fricção. A escolha certa depende do seu caso de utilização. Para o registo de um convidado pela primeira vez, onde deseja 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 convidado recorrente que já consentiu e cujo perfil já possui, utilize o snsapi_base para uma nova autenticação silenciosa. Agora, o lado da 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 no RFC 3576, e o bypass de endereço MAC. 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 nível empresarial. Com o bypass de MAC, o servidor de portal regista o endereço MAC do dispositivo como um cliente autorizado, e o controlador permite o acesso. 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 na 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 espaço não precisa de gerir essa tradução manualmente. --- RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS (aproximadamente 2 minutos) Permita-me apresentar as cinco razões que levam à falha das implementações de Captive Portal com WeChat OAuth. 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 staging. 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. Pertence ao seu servidor. Se for exposto, qualquer pessoa pode fazer-se passar pela sua aplicação e chamar as APIs do WeChat em seu nome. Terceiro: falta de proteção contra CSRF. O parâmetro de estado no pedido de OAuth existe especificamente para evitar a falsificação de pedidos entre sites (cross-site request forgery). Gere um valor de estado criptograficamente aleatório, 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 lacuna na deteção do browser na aplicação. O browser interno do WeChat define uma string de user agent específica que contém "MicroMessenger". Se o seu portal não detetar isto e não disponibilizar o fluxo de OAuth correto - fluxo de Conta Oficial para o browser na aplicação, fluxo de QR da Plataforma Aberta para browsers 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, limitação clara da 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 recolher, documente a sua base legal e o seu período de retenção. --- PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Question: Can I use WeChat login on a portal that also offers email and SMS login? Yes. Most enterprise portal platforms, including Purple, support multiple authentication methods on the same portal page. WeChat appears as one option alongside others. Question: Does WeChat OAuth work on iOS? Yes, but with a nuance. Apple's App Tracking Transparency framework does not affect server-side OAuth flows. WeChat login in Safari on iOS works via the QR code flow or redirect flow. The WeChat app itself handles the authentication. Question: What happens if WeChat's API is unavailable? Your portal should implement a fallback. If the WeChat API call times out or returns an error, redirect the user to an alternative login method. Do not leave them with a blank screen. Question: Can I use the OpenID as a persistent customer identifier? Within your Official Account, yes. The OpenID is stable for a given user and a given Official Account. If you have multiple Official Accounts, the same user will have different OpenIDs across them. For cross-account identity resolution, WeChat provides a UnionID, which requires your accounts to be linked on the Open Platform. --- SUMMARY AND NEXT STEPS (approximately 1 minute) To summarise. WeChat OAuth authentication for captive portals is a two-platform registration exercise, a scope decision, a network enforcement integration, and a compliance review. Get those four things right and you have a login method that serves over a billion potential visitors with zero password friction. The practical next steps are these. First, determine whether your visitors encounter the portal inside the WeChat in-app browser or in a standard mobile browser - that determines which platform registration you need. Second, decide on scope - snsapi_base for returning guests, snsapi_userinfo for first-time registration with consent. Third, confirm your network hardware supports RADIUS CoA or configure MAC bypass as an alternative. Fourth, review your privacy notice and consent flow against GDPR and PIPL requirements. Fifth, test the redirect URI, the state parameter validation, and the in-app browser detection before you go live. If you want to see how Purple handles WeChat OAuth as part of a broader Guest WiFi and analytics platform - across 80,000 venues and 440 million logins in 2024 - visit purple.ai or speak to your account team. Thanks for listening. --- END OF SCRIPT