Integrando a Autenticação WeChat WiFi: Integração de Captive Portal para Clientes APAC

O WeChat possui 1,41 bilhão de usuários ativos mensais, tornando-se a principal identidade digital para os consumidores chineses globalmente. Este guia explica como integrar a autenticação WeChat OAuth 2.0 em captive portals corporativos para locais na APAC, cobrindo o registro da plataforma, seleção de escopo, aplicação de RADIUS Change of Authorisation e conformidade de estrutura dupla com o GDPR e a PIPL da China. É destinado a gerentes de TI, arquitetos de rede e diretores de operações de locais que precisam agir neste trimestre.

📖 9 min de leitura📝 2,481 palavras🔧 2 exemplos práticos❓ 4 questões práticas📚 10 definições principais

Video overview

Ouça este guia

Ver transcrição do podcast

COMO CONFIGURAR A AUTENTICAÇÃO OAUTH DO 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 a visitantes chineses, este briefing é para você.

O WeChat tem 1,41 bilhão de usuários ativos mensais em 2025, de acordo com os próprios dados da Tencent. A grande maioria está na China, mas a plataforma também possui uma presença internacional expressiva. A Malásia tem 12 milhões de usuários do WeChat. O Japão tem 5,5 milhões. A Coreia do Sul, 5 milhões. E os números estão crescendo em todo o Sudeste Asiático, Oriente Médio e Europa.

Quando um visitante chinês se conecta ao seu WiFi e visualiza uma página de login contendo apenas e-mail, Facebook ou um código de voucher, ele enfrenta uma fricção imediata. Ele pode não ter um endereço de e-mail local configurado naquele dispositivo. Ele quase certamente possui 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 um modo que gere dados primários que você possa realmente utilizar.

Isso é o que vamos cobrir 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 imposição do lado da rede e as considerações de conformidade que importam em 2026.

IMERSÃO TÉCNICA (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, você 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, passando o 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 integrado do aplicativo WeChat, a experiência pode ser silenciosa com o escopo snsapi base, o que significa que não haverá solicitação 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 a API do WeChat. 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 gerencia aplicativos de sites e aplicativos móveis. A WeChat Official Accounts Platform gerencia contas públicas, que é 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 Conta de Serviço na Official Accounts Platform. Uma Conta de Assinatura 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, como o Chrome no Android ou o Safari no iOS, você precisa de um Aplicativo de Site registrado na Open Platform. Isso utiliza o escopo de login snsapi e apresenta um código QR que o usuário escaneia com o aplicativo WeChat.

Na prática, a maioria das implantações em locais utiliza ambos. Um convidado em um hotel pode abrir o portal no Chrome, ver um código QR, escaneá-lo com o WeChat e autenticar-se. Ou ele pode seguir um link no próprio WeChat, cair no navegador interno e autenticar-se silenciosamente com o snsapi base.

Vamos falar sobre a seleção de escopo, pois este é um ponto de decisão real.

O escopo snsapi base retorna apenas o OpenID. Este é um identificador exclusivo para aquele usuário dentro da sua Conta Oficial. 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 sobre os quais você já possui perfil, ou para locais onde você deseja atrito zero ao custo de nenhum dado novo.

O escopo snsapi userinfo retorna o OpenID mais o apelido do WeChat, foto de perfil, gênero, configuração de idioma e cidade do usuário. Ele requer uma tela de consentimento explícito. O usuário vê uma mensagem perguntando se 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 registro de um convidado pela primeira vez, 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 portal. Para um convidado recorrente que já consentiu e cujo perfil você já possui, use o snsapi base para reautenticação silenciosa.

Agora, a parte de 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 autorização bem-sucedida em acesso à rede.

As duas abordagens padrão são o RADIUS Change of Authorisation, definido na RFC 3576, e o bypass de endereço MAC. Com o RADIUS CoA, o servidor do seu portal envia uma solicitação 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, Ubiquiti UniFi, Cambium, Extreme e Fortinet.Com o bypass de MAC, o servidor do portal registra o endereço MAC do dispositivo como um cliente autorizado, e a controladora o permite. O bypass de MAC é mais simples de implementar, mas menos seguro, porque os endereços MAC podem ser forjados, e os smartphones modernos usam cada vez mais a randomização de endereços MAC, o que quebra o mecanismo na reconexão.

A plataforma de WiFi para visitantes da Purple gerencia ambos os mecanismos. Após a conclusão do OAuth do WeChat, a sobreposição em nuvem da Purple envia o sinal apropriado para o hardware subjacente. 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 com que as implementações de Captive Portal com OAuth do WeChat falhem.

Primeiro: a divergência no URI de redirecionamento. O WeChat valida o URI de redirecionamento em relação ao domínio autorizado que você registrou na plataforma. Se o seu servidor de portal usar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo do OAuth falhará com o erro 40029, o que significa 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 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. Pule esta etapa e você terá uma vulnerabilidade real.

Quarto: a lacuna de detecção do navegador integrado. O navegador integrado 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, os usuários terão uma experiência instável ou um erro.

Quinto: alinhamento com GDPR e PIPL. Se você atende a visitantes europeus, a GDPR se aplica aos dados coletados por meio do OAuth do WeChat. Se você atende a visitantes chineses, a Lei de Proteção de Informações Pessoais da China, conhecida como PIPL, se aplica à forma 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 escopo base snsapi é 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 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 portal que também oferece login por e-mail e SMS?
Sim. A maioria das plataformas de portal corporativo, 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 de rastreamento de aplicativos da Apple não afeta os fluxos OAuth do lado do servidor. O login do WeChat no Safari no iOS funciona através do fluxo de código QR ou fluxo de redirecionamento. O próprio aplicativo WeChat gerencia a autenticação.
autenticação.Pergunta: O que acontece se a API do WeChat estiver indisponível?
Seu portal deve implementar um plano de contingência. 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 portais cativos é um exercício de registro em duas plataformas, uma decisão de escopo, uma integração de imposiçã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 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. Use snsapi base para visitantes que retornam e 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 uma 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 WeChat OAuth como parte de uma plataforma mais ampla de Guest WiFi 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.

Principais conclusões

✓O WeChat tem 1,41 bilhão de usuários ativos mensais (Tencent, 2025), o que o torna a principal identidade digital para os consumidores chineses. Os locais que atendem a convidados da região APAC não podem se dar ao luxo de omiti-lo de suas opções de login no Captive Portal.
✓São necessários dois registros de plataforma: uma Conta de Serviço (Service Account) na Official Accounts Platform para acesso via navegador interno do aplicativo, e um Aplicativo Web (Website Application) na Open Platform para acesso via navegadores padrão. Usar o tipo de registro errado é a falha de implementação mais comum.
✓A seleção do escopo (scope) é uma decisão de arquitetura real. Use snsapi_base para autenticação silenciosa e sem atrito, que retorna apenas um OpenID. Use snsapi_userinfo para coletar dados demográficos, aceitando o atrito de uma tela de consentimento.
✓O OAuth comprova a identidade, mas não libera a rede. O RADIUS Change of Authorisation (RFC 3576) é o mecanismo que traduz uma troca de token bem-sucedida em promoção de VLAN. Sem ele, os convidados autenticados permanecem bloqueados.
✓O AppSecret deve ser armazenado exclusivamente no lado do servidor. A exposição no código do lado do cliente permite a personificação do seu aplicativo e o acesso não autorizado à API do WeChat.
✓A GDPR e a PIPL se aplicam aos dados coletados via WeChat OAuth. Documente sua base legal, implemente a minimização de dados e garanta que sua camada de consentimento esteja em conformidade antes de entrar em operação.
✓Para implantações em múltiplas propriedades, implemente o UnionID do WeChat desde o início. Os OpenIDs diferem por Conta Oficial; o UnionID fornece uma identidade consistente do convidado em todas as contas vinculadas.

📚 Parte da nossa série principal: Guia de Captive Portal →

Resumo executivo

Para estabelecimentos corporativos que operam em toda a região APAC, ou que atendem a turistas chineses globalmente, a autenticação WeChat WiFi não é mais opcional. Com 1,41 bilhão de usuários ativos mensais em 2025 (fonte: Tencent), o WeChat é a principal identidade digital dos consumidores chineses. Um visitante que se conecta ao seu SSID e vê apenas opções de login por e-mail ou Facebook enfrenta atrito imediato. Eles quase certamente têm WeChat. Eles quase certamente não têm um endereço de e-mail local configurado naquele dispositivo.

Este guia detalha como integrar o WeChat OAuth 2.0 a um Captive Portal. Cobrimos os dois registros de plataforma distintos que a Tencent exige, a decisão de escopo que determina quais dados de primeira parte você coleta e o mecanismo de RADIUS Change of Authorisation (CoA) que traduz uma troca de OAuth bem-sucedida em acesso real à rede. Também abordamos os requisitos de conformidade sobrepostos do GDPR e da Lei de Proteção de Informações Pessoais (PIPL) da China.

A plataforma Guest WiFi da Purple automatiza a camada de aplicação de rede nos hardwares Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet. A Purple opera em mais de 80.000 locais ativos e registrou 440 milhões de logins em 2024 (dados internos da Purple).

Detalhamento técnico

O fluxo OAuth 2.0

Um Captive Portal (um gateway de autenticação baseado na web que intercepta o tráfego HTTP de dispositivos não autenticados) redireciona os visitantes para uma página de login hospedada em um servidor de portal, localmente ou na nuvem. A adição do WeChat OAuth insere a infraestrutura de identidade da Tencent nesse fluxo.

A sequência funciona da seguinte forma. O visitante se associa ao SSID. O controlador sem fio detecta a ausência de uma sessão autenticada e redireciona todo o tráfego HTTP para a URL do Captive Portal. A página do portal é carregada e apresenta as opções de login, incluindo o WeChat. O visitante seleciona o WeChat. O servidor do portal cria um redirecionamento para o endpoint de autorização do WeChat em open.weixin.qq.com, transmitindo quatro parâmetros: o AppID, a URI de redirecionamento, o tipo de resposta definido como code e o escopo solicitado.

O WeChat autentica o usuário inteiramente em sua própria infraestrutura. Se o visitante já estiver conectado por meio do navegador interno do WeChat, o escopo snsapi_base permite a autenticação silenciosa sem nenhuma solicitação visível. O WeChat redireciona de volta para a URI de redirecionamento registrada do portal com um código de autorização de curta duração. O servidor do portal troca esse código por um token de acesso chamando api.weixin.qq.com/sns/oauth2/access_token com o AppID, AppSecret, código e tipo de concessão. O WeChat retorna um token de acesso, um token de atualização, o OpenID do usuário e o escopo concedido. Se o snsapi_userinfo foi solicitado, uma segunda chamada de API para api.weixin.qq.com/sns/userinfo recupera o apelido, a imagem de perfil, o gênero e a cidade do usuário.

Registro na plataforma: a decisão que atrapalha a maioria das implantações

A Tencent opera duas plataformas de desenvolvedores distintas, e selecionar a errada é a causa mais comum de falhas nas implementações.

Contexto de acesso	Registro obrigatório	URL da plataforma	Escopos suportados
Navegador interno do WeChat	Conta de Serviço (Official Accounts Platform)	mp.weixin.qq.com	snsapi_base, snsapi_userinfo
Navegador móvel padrão (Chrome, Safari)	Aplicativo Web (Open Platform)	open.weixin.qq.com	snsapi_login (fluxo de código QR)

Uma Conta de Assinatura na Official Accounts Platform não funcionará. Ela não possui as permissões de autorização de página web OAuth. Apenas uma Conta de Serviço possui essas permissões.

A maioria das implantações corporativas em Hospitalidade e Varejo implementa ambos os registros. Um hóspede de um hotel pode abrir o portal no Chrome, ler um código QR com o WeChat e se autenticar por meio do fluxo da Open Platform. Ou ele pode seguir um link dentro do próprio WeChat, cair no navegador interno e se autenticar silenciosamente por meio do fluxo da Official Accounts. Ambos os caminhos devem ser tratados.

Seleção de escopo e coleta de dados

O escopo OAuth é uma decisão arquitetônica real, não um mero detalhe de configuração. Ele determina a fricção que o usuário experimenta e os dados que sua plataforma de WiFi Analytics recebe.

snsapi_base retorna apenas o OpenID - um identificador exclusivo e estável para aquele usuário em sua Conta Oficial. Não requer solicitação de consentimento do usuário. A autenticação é invisível. Use isso para visitantes frequentes cujos perfis você já possui, ou para ambientes de alto fluxo, como estádios e hubs de transporte, onde a velocidade de conexão é a prioridade.snsapi_userinfo retorna o OpenID mais apelido, imagem de perfil, gênero, configuração de idioma e cidade. Ele aciona uma tela de consentimento explícito. Use isso para o primeiro registro do visitante para criar um perfil de dados primários (first-party data), combinado com uma camada de consentimento em conformidade com a PIPL e GDPR na página do portal.

A regra prática: use snsapi_base para velocidade, snsapi_userinfo para dados. Você pode implementar ambos verificando se o OpenID do usuário já existe em seu banco de dados. Se existir, solicite snsapi_base. Se não existir, solicite snsapi_userinfo.

Aplicação de rede: RADIUS CoA e desvio de MAC

Um token OAuth comprova a identidade. Ele não abre a rede. Um mecanismo separado deve traduzir a autenticação bem-sucedida em uma alteração de política de rede.

O RADIUS Change of Authorisation (CoA), definido no RFC 3576, é a abordagem padrão. Depois que o servidor do portal recebe um token OAuth válido, ele envia uma solicitação de CoA para a controladora sem fio. A controladora atualiza a sessão, movendo o dispositivo da VLAN de walled garden (um segmento de rede restrito que permite apenas o tráfego do portal) para a VLAN de visitantes completa. Isso funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.

O desvio de endereço MAC registra o endereço MAC do dispositivo como um cliente autorizado após o OAuth bem-sucedido. A controladora então permite o tráfego daquele endereço sem contestação adicional. É mais simples de implementar, mas traz dois riscos: endereços MAC podem ser falsificados, e o iOS 14 e o Android 10 em diante usam a randomização de endereços MAC por padrão, o que quebra o mecanismo na reconexão.

Para qualquer implantação onde a segurança seja importante, o RADIUS CoA é a escolha correta. Para saber mais sobre como proteger redes de visitantes, consulte What Is Secure WiFi: Essential Guide for Business 2026 e Enterprise WiFi Security: A Complete Guide for 2026 .

Guia de implantação

Lista de verificação pré-implantação

Antes de escrever uma linha de configuração, conclua estas cinco etapas.

Primeiro, determine o contexto de acesso. Avalie seu local e identifique se os visitantes encontrarão o portal dentro do navegador do aplicativo WeChat, em um navegador móvel padrão ou em ambos. A resposta determina os requisitos de registro da sua plataforma.

Segundo, registre-se na plataforma correta. Para acesso pelo navegador do aplicativo, crie uma Conta de Serviço na WeChat Official Accounts Platform. Para acesso por navegador padrão, registre um Website Application na WeChat Open Platform. Anote seu AppID e AppSecret para cada um.

Terceiro, configure suas URIs de redirecionamento. Registre cada domínio e subdomínio que seu portal utiliza, incluindo ambientes de teste. O WeChat exige validação de correspondência exata. Uma divergência retorna o erro 40029.

Quarto, implemente a troca de tokens no lado do servidor. O AppSecret nunca deve aparecer no código do lado do cliente. Crie um endpoint no lado do servidor que aceite o código de autorização, troque-o por um token e retorne apenas os dados que seu portal precisa.

Em quinto lugar, implemente o parâmetro state para proteção contra CSRF. Gere um valor criptograficamente aleatório, armazene-o na sessão do usuário, passe-o na solicitação de OAuth e valide-o no retorno.

Passos de configuração para Ruckus SmartZone

Para locais que executam o Ruckus SmartZone, a configuração do portal WeChat fica em Services and Profiles, depois em Hotspots and Portals e, em seguida, na aba WeChat. Você configura a URL de Autenticação (o endpoint de callback do WeChat do seu servidor de portal), o Destino DNAT (o servidor que lida com redirecionamentos de clientes não autenticados) e o Período de Carência (a janela durante a qual um usuário desconectado recentemente pode se reconectar sem se reautenticar, cujo padrão é 60 minutos). Você também configura a whitelist do walled garden para permitir o tráfego para os endpoints da API do WeChat durante a fase de autenticação. Consulte também o Guia Passo a Passo: Configurando Controladoras Sem Fio Ruijie para Captive Portals de WiFi para Visitantes para padrões de configuração de controladoras semelhantes.

Detecção de navegador in-app

O navegador in-app do WeChat define uma string de user agent contendo MicroMessenger. Seu portal deve detectar essa string e fornecer o fluxo de OAuth apropriado. Se MicroMessenger estiver presente, use o fluxo de Contas Oficiais. Se estiver ausente, use o fluxo de código QR da Open Platform. A falha em detectar isso corretamente gera experiências com falhas ou erros de autenticação.

Boas práticas

Minimização de dados e conformidade com estrutura dupla

O GDPR (aplicável a visitantes europeus) e a PIPL (aplicável a cidadãos chineses) exigem uma base legal para o processamento de dados pessoais, limitação clara de finalidade e minimização de dados. O escopo snsapi_base é mais fácil de justificar sob os princípios de minimização de dados do que o snsapi_userinfo. Ao coletar dados demográficos via snsapi_userinfo, documente sua base legal, seu período de retenção e seu contrato de processamento de dados com a Tencent.

A PILP, em vigor desde novembro de 2021, exige consentimento explícito para informações pessoais confidenciais e exige que os processadores de dados fora da China implementem padrões de proteção equivalentes. Se o servidor do seu portal estiver localizado fora da China continental, você deverá avaliar se as regras de transferência internacional de dados se aplicam ao OpenID do WeChat e aos dados de perfil que você recebe.

UnionID para implantações em múltiplas propriedades

O OpenID é exclusivo por usuário por Conta Oficial. Se você opera várias Contas Oficiais em diferentes propriedades, o mesmo visitante terá OpenIDs diferentes em cada uma delas. O WeChat fornece um UnionID que permanece consistente em todas as contas vinculadas ao mesmo registro da Open Platform. Para redes hoteleiras, grupos de varejo ou operadoras de aeroportos que gerenciam vários locais, implemente a resolução de identidade baseada em UnionID desde o início.

Reforço de segurança

Armazene o AppSecret em uma variável de ambiente ou gerenciador de segredos, nunca no código-fonte. Rotacione-o imediatamente se suspeitar de exposição. Implemente limitação de taxa em seu endpoint de troca de token para evitar abusos. Registre todos os erros de OAuth, especialmente 40029 (código inválido) e 40163 (código expirado), pois estes indicam configuração incorreta ou sondagem ativa.

Para uma visão mais ampla da arquitetura de segurança de redes de visitantes, consulte Why Consumer WiFi Gear Doesn't Belong on Your Guest Network .

Estudos de caso

Rede de hotéis de luxo, Singapura

Um hotel de luxo de 350 quartos em Singapura que atende predominantemente a um segmento de viajantes de negócios chineses implementou a autenticação do WeChat WiFi juntamente com a opção de login por e-mail existente. Antes da implementação, a equipe da recepção relatava uma média de 15 reclamações de hóspedes por dia sobre dificuldades de login no WiFi. Os hóspedes chineses tentavam usar endereços de e-mail que não haviam configurado em seus dispositivos de viagem.

O hotel registrou uma Conta de Serviço na WeChat Official Accounts Platform e um Aplicativo de Website na Open Platform. Eles configuraram o snsapi_userinfo para conexões de primeira viagem e o snsapi_base para hóspedes recorrentes identificados pelo endereço MAC. O controlador HPE Aruba foi configurado para RADIUS CoA para gerenciar a promoção de sessão.

Em 30 dias, as reclamações de login de hóspedes no WiFi caíram para menos de duas por dia. O banco de dados de WiFi Analytics do hotel cresceu 4.200 perfis primários verificados no primeiro mês, com dados demográficos em nível de cidade permitindo comunicações direcionadas pós-estadia.

Shopping center internacional, Kuala Lumpur

Um shopping center premium em Kuala Lumpur, com 12 milhões de usuários do WeChat apenas na Malásia, precisava de uma experiência de integração de WiFi que correspondesse às expectativas digitais de sua base de compradores. O shopping operava pontos de acesso Cisco Meraki em 180.000 metros quadrados de área de varejo.

A implantação utilizou a plataforma de Guest WiFi da Purple como sobreposição de nuvem, com o WeChat OAuth como método de autenticação principal e SMS OTP como alternativa de segurança. A arquitetura agnóstica de hardware da Purple gerenciou a integração de RADIUS CoA com a Cisco Meraki sem exigir desenvolvimento personalizado.

O shopping registrou um aumento de 34% no início de sessões de WiFi no primeiro trimestre pós-implantação, atribuído à redução do atrito de integração para usuários do WeChat. Os dados primários coletados por meio dos fluxos de consentimento de snsapi_userinfo permitiram que a equipe de marketing do shopping segmentasse os compradores por cidade de origem para a entrega de campanhas direcionadas.

Solução de problemas e mitigação de riscos

Erro	Causa	Resolução
40029 código inválido	Incompatibilidade de URI de redirecionamento ou reutilização de código	Verifique se as URIs registradas correspondem exatamente; os códigos são de uso único
Tela em branco após autenticação	RADIUS CoA não configurado ou falhando	Verifique as configurações de CoA do controlador e as regras de firewall na porta UDP 3799
A randomização de MAC interrompe o fluxo de visitantes recorrentes	Randomização de MAC do iOS/Android	Migre para o rastreamento de sessão baseado em OpenID; evite a identificação apenas por MAC
snsapi_userinfo retorna campos vazios	O usuário configurou restrições de privacidade no WeChat	Trate campos nulos com suavidade; não exija dados de perfil para acesso

ROI e impacto nos negócios

O caso de negócios para a autenticação de WiFi via WeChat baseia-se em três resultados mensuráveis.

Aquisição de dados primários. Cada autenticação snsapi_userinfo gera um perfil de visitante verificado com dados demográficos. Para um hotel de 200 quartos operando com 70% de ocupação e 40% de hóspedes chineses, isso representa aproximadamente 20.000 novos perfis verificados por ano, cada um vinculado a uma identidade do WeChat que oferece suporte ao engajamento contínuo.

Redução da carga de suporte. O atrito no login é o principal causador de chamadas de suporte de WiFi de visitantes. Os estabelecimentos que adicionam a autenticação do WeChat ao lado das opções existentes relatam consistentemente uma redução nas consultas de recepção relacionadas ao WiFi, liberando tempo da equipe para interações de maior valor.

Alcance de marketing. As contas oficiais do WeChat permitem que os estabelecimentos enviem notificações aos seguidores. Um visitante que se autentica por meio de sua conta oficial pode ser incentivado a segui-la, criando um canal de comunicação direto que opera dentro do ecossistema do WeChat, onde os consumidores chineses passam em média 82 minutos por dia (fonte: Walk the Chat).

O plano Engage da Purple expande ainda mais esse recurso, permitindo o envio de mensagens automatizadas pós-visita, gatilhos de fidelidade e campanhas segmentadas criadas com base nos dados primários coletados no momento da autenticação do WiFi.

Definições principais

Captive Portal

Um gateway de autenticação baseado na web que intercepta o tráfego HTTP de um dispositivo não autenticado e o redireciona para uma página de login antes de conceder acesso à rede.

O mecanismo pelo qual a autenticação de WiFi de visitantes é apresentada aos usuários. O WeChat OAuth é um dos vários métodos de autenticação que um Captive Portal pode oferecer.

OAuth 2.0

Um protocolo de autorização padrão de mercado que permite que um aplicativo de terceiros (o Captive Portal) obtenha acesso limitado a um serviço de internet (WeChat) em nome de um usuário, sem que o usuário precise compartilhar sua senha com terceiros.

A estrutura subjacente que viabiliza o login do WeChat. O portal nunca visualiza as credenciais de WeChat do usuário; ele apenas recebe um token confirmando que o WeChat os autenticou.

RADIUS CoA

Change of Authorisation. Um mecanismo definido na RFC 3576 que permite que um servidor RADIUS modifique dinamicamente os atributos de autorização de sessão de um cliente de rede ativo, como alterar a atribuição de VLAN.

O mecanismo de aplicação de rede que traduz uma troca de WeChat OAuth bem-sucedida em acesso real à rede. Sem o CoA, o visitante se autentica, mas a controladora não sabe que deve abrir a rede.

OpenID

Um identificador exclusivo atribuído pelo WeChat a um usuário específico para uma Conta Oficial ou Aplicativo de Site específico. Ele é estável entre sessões, mas difere entre contas.

A chave primária usada para identificar um visitante em seu banco de dados de análise de WiFi. Use UnionID em vez disso se você opera múltiplas Contas Oficiais e precisa de resolução de identidade entre contas.

snsapi_base

Um escopo do WeChat OAuth que permite autenticação silenciosa, retornando apenas o OpenID do usuário sem exibir uma solicitação de consentimento.

Use para visitantes recorrentes ou ambientes de alto rendimento onde a velocidade de conexão é a prioridade. Não retorna dados demográficos além do OpenID.

snsapi_userinfo

Um escopo do WeChat OAuth que retorna o OpenID do usuário, apelido, imagem de perfil, gênero, idioma e cidade, exigindo uma tela de consentimento explícito do usuário.

Use para o primeiro registro de visitantes para construir um perfil de dados próprios. Deve ser emparelhado com uma camada de consentimento em conformidade com o GDPR e a PIPL.

PIPL

Personal Information Protection Law. A legislação abrangente de privacidade de dados da China, em vigor desde novembro de 2021, que rege como os dados pessoais de cidadãos chineses devem ser coletados, processados e transferidos.

Aplica-se a qualquer local que colete dados de cidadãos chineses por meio do WeChat OAuth, independentemente de onde o local esteja situado. Exige consentimento explícito, limitação de finalidade e minimização de dados.

AppSecret

Uma chave criptográfica confidencial emitida pelo WeChat que autentica seu aplicativo quando ele chama a API de troca de token do WeChat.

Deve ser armazenado apenas no lado do servidor. A exposição no código do lado do cliente permite que qualquer parte se passe pelo seu aplicativo e faça chamadas de API não autorizadas para o WeChat.

VLAN

Virtual Local Area Network. Um segmento lógico de rede que isola o tráfego na camada de enlace de dados, permitindo que uma única rede física transporte múltiplos fluxos de tráfego isolados.

Usado em implantações de Captive Portal para separar dispositivos não autenticados (VLAN de walled garden) de visitantes autenticados (VLAN de visitantes). O RADIUS CoA move um dispositivo entre VLANs após a autenticação bem-sucedida.

UnionID

Um identificador do WeChat que permanece consistente para um determinado usuário em todas as Contas Oficiais e Aplicativos de Site vinculados ao mesmo registro de Plataforma Aberta.

Essencial para redes de hotéis, grupos de varejo e operadores de múltiplos locais que precisam reconhecer o mesmo visitante em várias propriedades, cada uma com sua própria Conta Oficial.

Exemplos práticos

Um hotel de luxo com 200 quartos em Singapura usa controladores HPE Aruba e atende a um grande volume de viajantes de negócios chineses. Eles desejam coletar dados demográficos de hóspedes de primeira viagem e garantir que os hóspedes recorrentes se conectem automaticamente sem ver o portal novamente. Como eles devem configurar a integração do WeChat OAuth?

Etapa 1: Registre uma Conta de Serviço na WeChat Official Accounts Platform (mp.weixin.qq.com) para gerenciar o acesso dos hóspedes ao portal dentro do navegador integrado do WeChat. Registre um Aplicativo de Website na WeChat Open Platform (open.weixin.qq.com) para hóspedes em navegadores móveis padrão.

Etapa 2: Configure o Captive Portal para detectar a string do user agent MicroMessenger. Ofereça o fluxo OAuth da Official Accounts para usuários de navegadores integrados e o fluxo de código QR da Open Platform para usuários de navegadores padrão.

Etapa 3: Para conexões de primeira viagem (sem OpenID existente no banco de dados), solicite o escopo snsapi_userinfo. Apresente uma tela de consentimento em conformidade com a PIPL antes do redirecionamento OAuth. Armazene o OpenID retornado, apelido, cidade e gênero no banco de dados de perfis de hóspedes.

Etapa 4: Para hóspedes recorrentes (OpenID existente no banco de dados), solicite o escopo snsapi_base. Isso autentica silenciosamente sem nenhum prompt visível para o usuário.

Etapa 5: Configure o controlador HPE Aruba para RADIUS CoA na porta UDP 3799. Após o OAuth bem-sucedido, o servidor do portal envia uma solicitação de CoA para promover o dispositivo do VLAN de walled garden para o VLAN de convidados.

Etapa 6: Implemente o registro de endereço MAC junto com o OpenID para lidar com a detecção de hóspedes recorrentes. Observe que a randomização de MAC exige o OpenID como o identificador primário, e não apenas o endereço MAC.

Comentário do examinador: Esta abordagem separa corretamente os dois registros de plataforma por contexto de acesso, usa a seleção de escopo para equilibrar a fricção com a coleta de dados e implementa o RADIUS CoA para aplicação segura de rede. O uso do OpenID como o identificador primário de hóspedes recorrentes é a resposta correta para a randomização de MAC. A camada de consentimento da PIPL é inegociável para dados de cidadãos chineses.

A equipe de TI de uma rede de varejo relata uma alta taxa de falhas para logins de WeChat WiFi em três locais de shopping. Os usuários se autenticam no WeChat, mas retornam à página do portal com um erro. Os logs do portal mostram o erro 40029. Qual é a causa provável e como resolver isso?

O erro 40029 significa que o WeChat rejeitou o código de autorização durante a troca de token. As duas causas mais comuns são a incompatibilidade de URI de redirecionamento e a reutilização de código.

Etapa 1: Faça login no console do desenvolvedor do WeChat tanto para a Official Accounts Platform quanto para a Open Platform. Navegue até as configurações de OAuth e liste todos os URIs de redirecionamento registrados.

Etapa 2: Compare-os com os URIs de redirecionamento reais que o seu servidor de portal usa em produção nos três locais. Verifique se há diferenças de subdomínio (portal.brand.com vs brand.com), diferenças de protocolo (HTTP vs HTTPS) e diferenças de caminho (/callback vs /wechat/callback).

Etapa 3: Registre cada variante no console do WeChat. O WeChat realiza validação de correspondência exata, não correspondência de prefixo.

Etapa 4: Se os URIs corresponderem, investigue se o servidor do seu portal está tentando reutilizar códigos de autorização. Os códigos do WeChat são de uso único e expiram após cinco minutos. Se o seu servidor tentar novamente a troca de token com o mesmo código, ele receberá o erro 40029 na segunda tentativa.

Etapa 5: Implemente idempotência no endpoint de troca de token para evitar solicitações duplicadas.

Comentário do examinador: O erro 40029 é o mais comum em implantações de WeChat OAuth e quase sempre é causado por uma incompatibilidade de URI de redirecionamento. Implantações em múltiplos locais são particularmente vulneráveis porque cada local pode usar um subdomínio ou endereço de balanceador de carga diferente. A causa secundária, reutilização de código, é menos comum, mas vale a pena verificar se a confirmação do registro do URI estiver correta.

Questões práticas

Q1. Você está implantando um Captive Portal para um estádio com capacidade para 60.000 pessoas que sedia eventos internacionais com uma base significativa de torcedores chineses. A prioridade é colocar todos os participantes online nos primeiros 15 minutos de abertura dos portões para reduzir o congestionamento de celular. A coleta de dados de marketing é um objetivo secundário. Qual escopo de OAuth do WeChat você deve configurar e por quê?

Dica: Considere o impacto de uma tela de consentimento exibida para 15.000 usuários simultâneos em um servidor de portal.

Ver resposta modelo

Configure o escopo snsapi_base. Isso permite a autenticação silenciosa sem solicitação de consentimento do usuário, proporcionando a experiência de integração mais rápida possível. Na escala de um estádio, uma tela de consentimento adiciona fricção que se multiplica em milhares de conexões simultâneas e pode causar picos de carga no servidor do portal. O snsapi_base retorna apenas o OpenID, o que é suficiente para registrar a sessão e identificar os torcedores que retornam. Para torcedores de primeira viagem dos quais você deseja dados demográficos, você pode solicitar o preenchimento do perfil por meio de uma pesquisa pós-conexão, em vez de fazer isso no portal de autenticação.

Q2. Um arquiteto de rede da sua equipe sugere armazenar o AppSecret do WeChat no JavaScript do lado do cliente do Captive Portal para reduzir as idas e vindas ao servidor, fazendo a chamada de troca de token diretamente do navegador. Explique por que essa abordagem é uma falha de segurança crítica e qual é a arquitetura correta.

Dica: Considere quem pode visualizar o código do lado do cliente e o que o AppSecret permite que eles façam.

Ver resposta modelo

Armazenar o AppSecret no JavaScript do lado do cliente o expõe a qualquer pessoa que visualize o código-fonte da página ou intercepte o tráfego de rede. O AppSecret autentica seu aplicativo na API do WeChat. Com ele, um ator mal-intencionado pode se passar pelo seu aplicativo, chamar o endpoint de troca de token do WeChat com qualquer código de autorização válido, recuperar OpenIDs e dados de perfil de usuários e, potencialmente, esgotar seus limites de taxa de API. A arquitetura correta é um endpoint de troca de token no lado do servidor. O navegador recebe o código de autorização do WeChat e o passa para o seu servidor. Seu servidor, usando o AppSecret armazenado em uma variável de ambiente ou gerenciador de segredos, troca o código por um token e retorna apenas os dados de que o portal precisa. O AppSecret nunca sai do seu servidor.

Q3. Seu estabelecimento opera três propriedades hoteleiras em cidades diferentes, cada uma com sua própria conta oficial do WeChat. Um membro do programa de fidelidade que se autenticou nas três propriedades possui três OpenIDs diferentes no seu banco de dados. Como você resolve isso em uma única identidade de hóspede?

Dica: O WeChat fornece um mecanismo para resolução de identidade entre contas que requer uma configuração específica de plataforma.

Ver resposta modelo

Implemente o mecanismo UnionID do WeChat. Vincule todas as três contas oficiais ao mesmo registro de Plataforma Aberta em open.weixin.qq.com. Uma vez vinculado, o WeChat retorna um UnionID junto com o OpenID na resposta snsapi_userinfo. O UnionID é consistente para um determinado usuário em todas as contas vinculadas ao mesmo registro de Plataforma Aberta. Migre seu banco de dados para usar o UnionID como o identificador principal de hóspedes para registros entre propriedades, retendo o OpenID por conta para chamadas de API específicas de cada conta. Para hóspedes que se autenticaram antes da implementação do UnionID, acione uma nova autenticação com snsapi_userinfo na próxima visita para capturar o UnionID.

Q4. Após implantar a autenticação de WiFi do WeChat em um estabelecimento de varejo que opera pontos de acesso Cisco Meraki, os hóspedes relatam que concluem o login do WeChat com sucesso, mas retornam à página do portal e não conseguem navegar na internet. Os logs do servidor do portal mostram a recuperação bem-sucedida do token. Qual é a causa mais provável e como você a diagnostica?

Dica: O portal verificou a identidade. O que ainda não aconteceu?

Ver resposta modelo

O RADIUS Change of Authorisation (CoA) não está sendo concluído. O servidor de portal verificou a identidade do visitante via WeChat OAuth, mas não instruiu com sucesso o controlador Cisco Meraki a mover o dispositivo da VLAN de walled garden para a VLAN de convidados. Diagnostique verificando: (1) se o controlador Meraki possui o RADIUS CoA ativado e se o IP do servidor de portal está listado como um cliente CoA autorizado; (2) se a porta UDP 3799 está aberta entre o servidor de portal e o controlador; (3) os logs do servidor de portal em busca de erros ou expiração de tempo (timeout) nas requisições CoA; e (4) se o segredo compartilhado configurado em ambos os lados coincide. Se o CoA não for compatível com a sua licença Meraki, o bypass de endereço MAC é a alternativa de fallback, embora traga o risco de randomização de MAC mencionado no guia.

Continue a ler esta série

Captive Portal para Ruijie: configure-o com o WiFi de convidados Purple

Como o WiFi de convidados em nuvem da Purple se integra aos pontos de acesso Ruijie RG Series usando autenticação web e RADIUS, configurados a partir da linha de comando, e onde encontrar as etapas de configuração exatas.

Projetando Captive Portals B2B: Coletando Nome Registrado e Dados da Empresa

Este guia fornece aos gerentes de TI e operadores de locais uma estrutura técnica neutra em relação a fornecedores para projetar Captive Portals B2B. Ele detalha como estruturar campos de registro para capturar dados de nome registrado e empresa, garantindo altas taxas de conclusão enquanto mantém a conformidade com o GDPR e constrói inteligência no nível da conta.

Arquitetura de Captive Portal: Segurança, Redirecionamento e Melhores Práticas

Uma referência técnica definitiva sobre a arquitetura de captive portal corporativo. Este guia detalha o isolamento de rede, redirecionamento de DNS, autenticação RADIUS e conformidade de segurança para líderes de TI que implantam redes WiFi de visitantes seguras e ricas em dados.