Integrar a Autenticação WeChat com Captive Portals de Wi-Fi de Convidados

COMO CONFIGURAR A AUTENTICAÇÃO WECHAT OAUTH PARA CAPTIVE PORTALS Uma Apresentação Técnica da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto) Bem-vindo. Se é responsável pelo Wi-Fi 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 no Sudeste Asiático, Europa e Médio Oriente. Quando um convidado chinês se liga ao seu Wi-Fi e vê uma página de início de sessão apenas com e-mail, Facebook ou um código de voucher, depara-se com um atrito imediato. É muito provável que não tenha um endereço de e-mail local configurado nesse dispositivo. Mas tem quase de certeza o WeChat. Portanto, a questão não é se deve oferecer o início de sessão com o WeChat – é como configurá-lo corretamente, de forma segura e de modo a gerar dados primários (first-party) que possa realmente utilizar. É isso que vamos abordar hoje. Vamos percorrer o fluxo do OAuth 2.0, os dois registos de plataforma de que necessita, a decisão sobre o â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. --- ANÁLISE TÉCNICA DETALHADA (aproximadamente 5 minutos) Comecemos pela arquitetura. Um Captive Portal interpeta o tráfego HTTP de um dispositivo não autenticado e redireciona-o para uma página de início de sessão. Essa página de início de sessão é 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 uma sessão autenticada e redireciona todo o tráfego HTTP para o URL do seu Captive Portal. A página do portal carrega e apresenta as opções de início de sessão – incluindo o WeChat. O convidado toca no início de sessão do WeChat. O servidor do seu portal redireciona o navegador para o endpoint de autorização do WeChat, transmitindo o seu App ID, o URI de redirecionamento, o tipo de resposta 'code' 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 na aplicação (in-app) do 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 servidor do seu portal troca esse código por um token de acesso, transmitindo o seu App ID, App Secret, o código e o tipo de concessão 'authorization_code'. O WeChat devolve um token de acesso, um token de atualização, o Open ID do utilizador e o âmbito concedido. Se tiver solicitado o âmbito snsapi userinfo, pode então fazer uma segunda chamada de API para obter o pseudónimo, 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 programadores distintas. A WeChat Open Platform lida com aplicações web e aplicações móveis. A WeChat Official Accounts Platform lida com contas públicas – o que a maioria dos espaços realmente necessita. Para um Captive Portal que serve convidados dentro do navegador na aplicação (in-app) do WeChat, necessita de uma Conta de Serviço (Service Account) na Official Accounts Platform. Uma Conta de Subscrição (Subscription Account) não funcionará – não tem permissões de autorização de páginas web OAuth. Uma Conta de Serviço tem, e suporta os âmbitos snsapi base e snsapi userinfo. Para um Captive Portal acedido a partir de um navegador móvel padrão fora do WeChat – Chrome no Android, Safari no iOS – necessita de uma Aplicação Web (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 utiliza ambos. Um convidado no Wi-Fi 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 ligação no próprio WeChat, aceder ao navegador na aplicação (in-app) e autenticar-se silenciosamente com o snsapi base. Falemos sobre a seleção do âmbito (scope), porque este é um verdadeiro ponto de decisão. O snsapi base devolve apenas o Open ID – um identificador exclusivo para esse utilizador dentro da sua Conta Oficial (Official Account). Não requer qualquer pedido de consentimento do utilizador. A autenticação é invisível para o utilizador. Isto é ideal para convidados frequentes dos quais já tem o perfil criado, ou para espaços onde deseja zero atrito. O snsapi userinfo devolve o Open ID mais o pseudónimo do WeChat, a imagem de perfil, o género, a definição de idioma e a cidade do utilizador. Requer um ecrã de consentimento explícito. A maioria dos utilizadores aceita, mas existe atrito. 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 combine-o com uma camada de consentimento em conformidade com o GDPR na página do seu portal. Para um convidado frequente que já deu o seu consentimento e cujo perfil já possui, utilize o snsapi base para uma reautenticação silenciosa. Agora, o lado da imposição de 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 Authorization, definido no RFC 3576, e o bypass de endereço MAC. Com o RADIUS CoA, o servidor do seu 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 do portal regista o endereço MAC do dispositivo como um cliente autorizado, e o controlador permite-o. O bypass de MAC é mais simples de implementar, mas menos seguro, porque os endereços MAC podem ser falsificados. A plataforma de Wi-Fi de convidados 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 Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme ou Fortinet. O operador do espaço não necessita 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 falhar as implementações de Captive Portal com WeChat OAuth. Primeiro: a incompatibilidade do URI de redirecionamento. O WeChat valida o URI de redirecionamento face ao domínio autorizado que registou na plataforma. Se o servidor do seu 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 (staging). Segundo: o App Secret no lado do cliente. O seu App Secret nunca deve aparecer no JavaScript do lado do cliente. O seu lugar é no servidor. Se for exposto, qualquer pessoa pode personificar a sua aplicação e fazer chamadas para as APIs do WeChat em seu nome. Terceiro: a falta de proteção CSRF. O parâmetro state no pedido de OAuth existe especificamente para evitar a falsificação de pedidos entre sites (cross-site request forgery). Gere um valor de state 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 falha na deteção do navegador na aplicação (in-app). O navegador na aplicação 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, os utilizadores terão uma experiência com falhas ou um erro. Quinto: o alinhamento com o GDPR e a PIPL. Se serve visitantes europeus, aplica-se o GDPR. Se serve visitantes chineses, aplica-se a Lei de Proteção de Informações Pessoais da China – PIPL. Ambas exigem uma base jurídica para o tratamento, limitação clara da finalidade e 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) Posso utilizar o início de sessão do 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 OAuth funciona no iOS? Sim. O início de sessão do 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. O que acontece se a API do WeChat estiver indisponível? Implemente uma alternativa (fallback). Se a chamada de API do WeChat expirar ou devolver um erro, redirecione o utilizador para um método de início de sessão alternativo. Posso utilizar o Open ID como um identificador de cliente persistente? Dentro da sua Conta Oficial (Official Account), sim. Para a resolução de identidade entre contas em múltiplas propriedades, utilize o UnionID em vez disso. --- RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto) Para resumir. A autenticação WeChat OAuth para Captive Portals é um exercício de registo em duas plataformas, uma decisão de âmbito (scope), uma integração de imposição de rede e uma revisão de conformidade. Acerte nestas quatro coisas e terá um método de início de sessão que serve mais de mil milhões de potenciais visitantes com zero atrito de palavra-passe. Os próximos passos práticos: determine se os seus visitantes encontram o portal dentro do navegador na aplicação (in-app) do WeChat ou num navegador móvel padrão. Decida sobre o âmbito – snsapi base para convidados frequentes, snsapi userinfo para o registo pela primeira vez com consentimento. Confirme que o seu hardware de rede suporta RADIUS CoA. Reveja o seu aviso de privacidade face ao GDPR e à PIPL. Teste o URI de redirecionamento, a validação do parâmetro state e a deteção do navegador na aplicação antes de avançar para o ambiente de produção (go-live). Se deseja ver como a Purple lida com o WeChat OAuth como parte de uma plataforma mais ampla de Wi-Fi de convidados e análise – em 80 000 espaços 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 ouvir. --- FIM DA APRESENTAÇÃO