Como configurar a autenticação WeChat OAuth para Captive Portals

COMO CONFIGURAR A AUTENTICAÇÃO WECHAT OAUTH 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 convidados em um hotel, rede de varejo, estádio ou centro de conferências 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 possui uma presença internacional significativa - quatro milhões de usuários nos Estados Unidos, 12 milhões na Malásia e números crescentes no Sudeste Asiático, Europa e Oriente Médio. Quando um convidado 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 um atrito imediato. Ele pode não ter um endereço de e-mail local configurado nesse dispositivo. Ele quase certamente tem 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 primários que você possa realmente usar. É isso que vamos cobrir hoje. Passaremos pelo fluxo do OAuth 2.0, os dois registros de plataforma de 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 captive portal - local ou na nuvem. Quando você adiciona o WeChat OAuth, está inserindo um provedor de identidade de terceiros nesse fluxo. Aqui está a sequência. O convidado 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 captive portal carrega e apresenta as opções de login - incluindo o WeChat. O convidado toca no login do WeChat. O servidor do seu captive portal redireciona o navegador para o endpoint de autorização do WeChat em open.weixin.qq.com, transmitindo seu AppID, o URI de redirecionamento, o tipo de resposta 'code' e o escopo. O WeChat lida com a autenticação inteiramente em seus próprios servidores. Se o convidado já estiver logado no WeChat em seu navegador, ele verá uma tela de consentimento. Se estiver usando o navegador interno do WeChat (in-app browser), a experiência pode ser silenciosa com o escopo snsapi_base - sem nenhuma solicitação de consentimento. O WeChat então redireciona de volta para o URI de redirecionamento do seu captive portal com um código de autorização temporário. O servidor do seu captive portal troca esse código por um token de acesso chamando api.weixin.qq.com/sns/oauth2/access_token, transmitindo seu AppID, AppSecret, o código e o tipo de concessão 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 falha. O WeChat possui duas plataformas de desenvolvedor distintas. A WeChat Open Platform em open.weixin.qq.com lida com aplicações de website e aplicativos móveis. A WeChat Official Accounts Platform em mp.weixin.qq.com lida com contas públicas - o que a maioria dos estabelecimentos realmente precisa. Para um captive portal que atende convidados dentro do navegador interno do WeChat, você precisa de uma Conta de Serviço (Service Account) na Official Accounts Platform. Uma Conta de Assinatura (Subscription Account) não funcionará - ela não possui permissões de autorização de página web OAuth. Uma Conta de Serviço 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 uma Aplicação de Website (Website Application) registrada na Open Platform. Isso usa o escopo snsapi_login e apresenta um código QR que o usuário escaneia com seu aplicativo WeChat. Na prática, a maioria das implantações em estabelecimentos usa ambos. Um convidado no WiFi de um hotel pode abrir o captive portal no Chrome, ver um código QR, escaneá-lo com o WeChat e se autenticar. Or pode seguir um link no próprio WeChat, cair no navegador interno e se autenticar silenciosamente com o snsapi_base. Vamos falar sobre a seleção de escopo, porque este é um ponto de decisão real. O snsapi_base retorna apenas o OpenID - um identificador exclusivo para esse usuário dentro da sua Conta Oficial (Official Account). Não exige nenhuma solicitação de consentimento do usuário. A autenticação é invisível para o usuário. Isso é ideal para convidados recorrentes sobre os quais você já traçou um perfil, ou para estabelecimentos onde você deseja atrito zero ao custo 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. Exige uma tela de consentimento explícita. O usuário vê uma solicitação perguntando se ele permite que sua Conta Oficial acesse suas informações. A maioria dos usuários aceita, mas há atrito. A escolha certa depende do seu caso de uso. Para o primeiro registro de um convidado onde você deseja criar um perfil, use o snsapi_userinfo e combine-o com uma camada de consentimento em conformidade com a GDPR na página do seu captive portal. Para um convidado recorrente que já consentiu e cujo perfil você já possui, use o snsapi_base para autenticação silenciosa. Agora, o lado da aplicação de rede. Obter um token OAuth prova 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 desvio de endereço MAC (MAC address bypass). Com o RADIUS CoA, o servidor do seu captive 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 classe corporativa. Com o desvio de MAC, o servidor do captive portal registra o endereço MAC do dispositivo como um cliente autorizado, e o controlador o permite. O desvio de MAC é mais simples de implementar, mas menos seguro, porque os endereços MAC podem ser clonados. A plataforma Guest WiFi da Purple lida com 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 estabelecimento não precisa gerenciar essa tradução manualmente. --- RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ARMADILHAS (aproximadamente 2 minutos) Deixe-me apresentar as cinco coisas que fazem as implementações de captive portal com WeChat OAuth falharem. Primeiro: a incompatibilidade do URI de redirecionamento. O WeChat valida o URI de redirecionamento em relação ao domínio autorizado que você registrou na plataforma. Se o servidor do seu captive portal usar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo do OAuth falhará com o erro 40029 - código inválido. Registre todas as variantes de domínio que você usa, incluindo ambientes de homologação. 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 por sua aplicação e chamar as APIs do WeChat em seu nome. Terceiro: falta de proteção CSRF. O parâmetro 'state' 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. Pule isso e você terá uma vulnerabilidade real. Quarto: a lacuna de detecção do navegador interno. O navegador interno do WeChat define uma string de user agent específica contendo 'MicroMessenger'. Se o seu captive portal não detectar isso e fornecer o fluxo OAuth correto - fluxo de Conta Oficial para navegador interno, fluxo de QR da Open Platform para navegadores padrão - os usuários terão uma experiência corrompida 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. O que quer que você colete, documente sua base legal e seu período de retenção. --- PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Pergunta: Posso usar o login do WeChat em um captive portal que também oferece login por e-mail e SMS? Sim. A maioria das plataformas de captive portal corporativo, incluindo a Purple, suporta múltiplos métodos de autenticação na mesma página do captive 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 estrutura App Tracking Transparency da Apple não afeta os fluxos OAuth do lado do servidor. 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. Pergunta: O que acontece se a API do WeChat estiver indisponível? Seu captive portal deve implementar 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. 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á OpenIDs diferentes entre elas. Para resolução de identidade entre contas, o WeChat fornece um UnionID, o que exige que suas contas estejam vinculadas na Open Platform. --- 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 aplicação de rede e uma revisão de conformidade. Acerte essas quatro coisas 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 captive 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 convidados recorrentes, snsapi_userinfo para o primeiro registro com consentimento. Terceiro, confirme se o hardware da sua rede suporta RADIUS CoA ou configure o desvio de MAC como alternativa. Quarto, revise seu aviso de privacidade e fluxo de consentimento em relação aos requisitos da GDPR e da PIPL. Quinto, teste o URI de redirecionamento, a validação do parâmetro de estado e a detecção do navegador interno antes de entrar em produção. 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 estabelecimentos e 440 milhões de logins em 2024 - visite purple.ai ou fale com sua equipe de contas. Obrigado por ouvir. --- FIM DO ROTEIRO