Integrating WeChat WiFi Authentication: Captive Portal Onboarding for APAC Customers

O WeChat conta com 1,41 mil milhões de utilizadores ativos mensais, tornando-se a principal identidade digital para os consumidores chineses a nível global. Este guia explica como integrar a autenticação WeChat OAuth 2.0 em Captive Portals empresariais para recintos na região APAC, abrangendo o registo na plataforma, seleção de âmbito, aplicação de RADIUS Change of Authorisation e conformidade de dupla estrutura com o GDPR e a PIPL da China. Destina-se a gestores de TI, arquitetos de rede e diretores de operações de recintos que necessitam de agir este trimestre.

📖 9 min de leitura📝 2,130 palavras🔧 2 exemplos práticos❓ 4 perguntas de prática📚 10 definições principais

Ouça este guia

Ver transcrição do podcast

COMO CONFIGURAR A AUTENTICAÇÃO OAUTH DO WECHAT PARA CAPTIVE PORTALS
Uma Breve 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,41 mil milhões de utilizadores ativos mensais em 2025, de acordo com os dados da própria Tencent. A esmagadora maioria está na China, mas a plataforma também tem uma presença internacional significativa. A Malásia tem 12 milhões de utilizadores de WeChat. O Japão tem 5,5 milhões. A Coreia do Sul, 5 milhões. E os números estão a crescer em todo o Sudeste Asiático, Médio Oriente e Europa.

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. Têm quase de certeza o WeChat. Por isso, a questão não é se deve disponibilizar o login com 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 do OAuth 2.0, os dois registos de plataforma de que necessita, a decisão de âmbito (scope) que determina que dados recolhe, o mecanismo de imposição do lado da rede e as considerações de conformidade que importam em 2026.

APROFUNDAMENTO TÉCNICO (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, quer seja localmente (on-premises) ou na cloud. 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 servidor do seu portal redireciona o browser para o endpoint de autorização do WeChat, transmitindo o seu AppID, o URI de redirecionamento, o tipo de resposta (code) e o âmbito (scope).

O WeChat processa 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 snsapi base, o que significa que não haverá 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 chamando a API do WeChat. O WeChat devolve um token de acesso, um token de atualização, o OpenID do utilizador e o âmbito concedido. Se tiver solicitado o âmbito snsapi userinfo, poderá então efetuar uma segunda chamada de API para obter o pseudónimo, avatar, género e 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 gere aplicações web e apps móveis. A WeChat Official Accounts Platform gere contas públicas, que é o que a maioria dos espaços realmente necessita.

Para um Captive Portal que serve os visitantes dentro do browser integrado do WeChat, necessita de uma Service Account na Official Accounts Platform. Uma Subscription Account não irá funcionar. Esta não possui permissões de autorização de página web OAuth. Uma Service Account possui-as e suporta tanto o escopo snsapi base como o snsapi userinfo.

Para um Captive Portal acedido a partir de um browser móvel padrão fora do WeChat, como o Chrome no Android ou o Safari no iOS, necessita de uma Website Application registada na Open Platform. Esta utiliza o escopo snsapi login e apresenta um código QR que o utilizador lê com a sua app WeChat.

Na prática, a maioria das implementações em espaços físicos utiliza ambos. Um visitante num 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, ir parar ao browser integrado e autenticar-se de forma silenciosa com o snsapi base.

Falemos sobre a seleção do escopo, porque este é um verdadeiro ponto de decisão.

O escopo snsapi base devolve apenas o OpenID. Este é um identificador único para esse utilizador dentro da sua Official Account. Não requer qualquer solicitação de consentimento do utilizador. A autenticação é invisível para o utilizador. Isto é ideal para visitantes frequentes cujo perfil já criou, ou para espaços onde deseja fricção zero à custa de zero novos dados.

O escopo snsapi userinfo devolve o OpenID e ainda o nome de utilizador do WeChat, 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 fricção.

A escolha certa depende do seu caso de uso. Para o primeiro registo de um visitante em que 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 visitante frequente que já deu o seu consentimento 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 a rede automaticamente. 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 MAC address bypass. 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 la VLAN de visitantes. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.

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, e os smartphones modernos utilizam cada vez mais a randomização de endereços MAC, o que quebra o mecanismo ao restabelecer a ligação.

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. 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 do 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, que significa 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. O seu lugar é no seu 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 de estado (state) no pedido de OAuth existe especificamente para prevenir 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. Se ignorar isto, terá uma vulnerabilidade real.

Quarto: a falha na deteção do browser integrado na aplicação. O browser integrado 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 apresentar 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, o GDPR aplica-se aos dados que recolhe via WeChat OAuth. Se serve visitantes chineses, a Lei de Proteção de Informações Pessoais da China, conhecida como 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 âmbito base 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 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 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 de portal. O WeChat aparece como uma opção ao lado de outras.

Pergunta: O WeChat OAuth funciona em iOS?
Sim, mas com uma nuance. O framework de Transparência do Rastreio de Aplicações (App Tracking Transparency) da Apple não afeta os fluxos de OAuth do lado do servidor. O início de sessão do WeChat no Safari em iOS funciona através do fluxo de código QR ou do fluxo de redirecionamento. A própria aplicação do WeChat trata da autenticação.
Pergunta: O que acontece se a API do WeChat estiver indisponível?
O seu portal deve implementar uma alternativa (fallback). Se a chamada da API do WeChat expirar ou retornar 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 Conta Oficial, sim. O OpenID é estável para um determinado utilizador e uma determinada Conta Oficial. Se tiver várias Contas Oficiais, o mesmo utilizador terá OpenIDs diferentes em cada uma delas. Para a resolução de identidade entre contas, o WeChat fornece um UnionID, o que exige que as suas contas estejam associadas na Open Platform.

RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto)

Em resumo. 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 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 qual o registo de plataforma de que necessita. Segundo, decida sobre o âmbito (scope). Utilize o snsapi base para visitantes frequentes e o 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 fluxo de consentimento em relação aos requisitos do GDPR e do PIPL. Quinto, teste o URI de redirecionamento, a validação do parâmetro de estado (state) e a deteção do navegador interno antes de entrar em produção.

Se deseja ver como a Purple lida com o WeChat OAuth como parte de uma plataforma mais ampla de Guest WiFi 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 pela vossa atenção.

Principais Conclusões

✓O WeChat tem 1,41 mil milhões de utilizadores ativos mensais (Tencent, 2025), tornando-se a principal identidade digital para os consumidores chineses. Os espaços que servem clientes da região APAC não se podem dar ao luxo de o omitir das suas opções de login do Captive Portal.
✓São necessários dois registos de plataforma: uma Conta de Serviço (Service Account) na Official Accounts Platform para acesso através do browser integrado na app, e uma Aplicação Web (Website Application) na Open Platform para acesso através de browsers padrão. Utilizar o tipo de registo incorreto é a falha de implementação mais comum.
✓A seleção do âmbito (Scope) é uma decisão arquitetural real. Utilize snsapi_base para uma autenticação silenciosa e sem fricção que devolve apenas um OpenID. Utilize snsapi_userinfo para recolher dados demográficos, aceitando a fricção de um ecrã de consentimento.
✓O OAuth comprova a identidade mas não abre a rede. O RADIUS Change of Authorisation (RFC 3576) é o mecanismo que traduz uma troca de token bem-sucedida numa promoção de VLAN. Sem ele, os clientes 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 usurpação de identidade da sua aplicação e o acesso não autorizado à API do WeChat.
✓O GDPR e a PIPL aplicam-se ambos aos dados recolhidos através do WeChat OAuth. Documente a sua base legal, implemente a minimização de dados e garanta que a sua camada de consentimento está em conformidade antes de entrar em produção.
✓Para implementações multi-propriedade, implemente o UnionID do WeChat desde o início. Os OpenIDs diferem por Conta Oficial; o UnionID fornece uma identidade de cliente consistente em todas as contas associadas.

Resumo Executivo

Para locais empresariais a operar na região APAC, ou que servem turistas chineses globalmente, a autenticação WeChat WiFi já não é opcional. Com 1,41 mil milhões de utilizadores ativos mensais em 2025 (fonte: Tencent), o WeChat é a principal identidade digital para os consumidores chineses. Um convidado que se liga ao seu SSID e vê apenas opções de início de sessão por e-mail ou Facebook enfrenta fricção imediata. Quase de certeza que tem WeChat. Quase de certeza que não tem um endereço de e-mail local configurado nesse dispositivo.

Este guia detalha como integrar o WeChat OAuth 2.0 num Captive Portal. Cobrimos os dois registos de plataforma distintos que a Tencent exige, a decisão de âmbito que determina quais os dados primários que recolhe, e o mecanismo RADIUS Change of Authorisation (CoA) que traduz uma troca 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 imposição de rede em hardware Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet. A Purple opera em mais de 80.000 locais ativos e registou 440 milhões de inícios de sessão em 2024 (dados internos da Purple).

Aprofundamento 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 convidados para uma página de início de sessão alojada num servidor de portal, localmente ou na cloud. A adição do WeChat OAuth insere a infraestrutura de identidade da Tencent nesse fluxo.

A sequência decorre da seguinte forma. O convidado associa-se ao SSID. O controlador sem fios deteta a ausência de uma sessão autenticada e redireciona todo o tráfego HTTP para o URL do Captive Portal. A página do portal carrega e apresenta as opções de início de sessão, incluindo o WeChat. O convidado seleciona o WeChat. O servidor do portal cria um redirecionamento para o endpoint de autorização do WeChat em open.weixin.qq.com, passando quatro parâmetros: o AppID, o URI de redirecionamento, o tipo de resposta definido como code e o âmbito solicitado.

O WeChat autentica o utilizador inteiramente na sua própria infraestrutura. Se o convidado já tiver sessão iniciada através do navegador interno do WeChat, o escopo snsapi_base permite uma autenticação silenciosa sem qualquer aviso visível. O WeChat redireciona de volta para o URI de redirecionamento registado do portal com um código de autorização de curta duração. O servidor do portal troca este código por um token de acesso ao chamar api.weixin.qq.com/sns/oauth2/access_token com o AppID, AppSecret, o código e o tipo de concessão (grant type). O WeChat devolve um token de acesso, um token de atualização (refresh token), o OpenID do utilizador e o escopo concedido. Se o snsapi_userinfo tiver sido solicitado, uma segunda chamada de API para api.weixin.qq.com/sns/userinfo recupera a alcunha do utilizador, a imagem de perfil, o género e a cidade.

Registo na plataforma: a decisão que compromete a maioria das implementações

A Tencent opera duas plataformas de programadores distintas, e selecionar a errada é a causa mais comum de falhas na implementação.

Contexto de acesso	Registo obrigatório	URL da plataforma	Escopos suportados
Navegador interno do WeChat	Conta de Serviço (Plataforma de Contas Oficiais)	mp.weixin.qq.com	snsapi_base, snsapi_userinfo
Navegador móvel padrão (Chrome, Safari)	Aplicação Web (Plataforma Aberta)	open.weixin.qq.com	snsapi_login (fluxo de código QR)

Uma Conta de Subscrição na Plataforma de Contas Oficiais não irá funcionar. Esta carece de permissões de autorização de páginas web OAuth. Apenas uma Conta de Serviço detém essas permissões.

A maioria das implementações empresariais em Hotelaria e Retalho implementa ambos os registos. Um convidado num hotel pode abrir o Captive Portal no Chrome, ler um código QR com o WeChat e autenticar-se através do fluxo da Plataforma Aberta. Ou pode seguir uma ligação dentro do próprio WeChat, aceder ao navegador interno e autenticar-se silenciosamente através do fluxo de Contas Oficiais. Ambos os caminhos devem ser geridos.

Seleção de escopo e recolha de dados

O escopo OAuth é uma decisão arquitetural real, não um mero detalhe de configuração. Este determina a fricção que o utilizador experiencia e os dados que a sua plataforma de WiFi Analytics recebe.

snsapi_base devolve apenas o OpenID - um identificador estável e único para esse utilizador dentro da sua Conta Oficial. Não requer qualquer pedido de consentimento ao utilizador. A autenticação é invisível. Utilize esta opção para convidados frequentes cujos perfis já possui, ou para ambientes de elevado fluxo de pessoas, tais como estádios e centros de transporte, onde a velocidade de ligação é a prioridade.

snsapi_userinfo devolve o OpenID e ainda o pseudónimo, imagem de perfil, género, definição de idioma e cidade. Isto aciona um ecrã de consentimento explícito. Utilize esta opção para o primeiro registo de convidados para criar um perfil de dados primários, emparelhado com uma camada de consentimento em conformidade com o PIPL e o GDPR na página do portal.

A regra prática: utilize snsapi_base para maior rapidez, snsapi_userinfo para obter dados. Pode implementar ambos verificando se o OpenID do utilizador já existe na sua base de dados. Se existir, solicite snsapi_base. Se não existir, solicite snsapi_userinfo.

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

Um token OAuth prova a identidade. Não abre a rede. Um mecanismo separado deve traduzir a autenticação bem-sucedida numa alteração da política de rede.

O RADIUS Change of Authorisation (CoA), definido no RFC 3576, é a abordagem padrão. Após o servidor do portal receber um token OAuth válido, envia um pedido de CoA para o controlador de rede sem fios. O controlador atualiza a sessão, movendo o dispositivo da VLAN do walled garden (um segmento de rede restrito que permite apenas tráfego do portal) para a VLAN de convidados completa. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.

O desvio de endereço MAC (MAC address bypass) regista o endereço MAC do dispositivo como um cliente autorizado após o sucesso do OAuth. O controlador permite então o tráfego desse endereço sem qualquer outro desafio. É mais simples de implementar, mas acarreta dois riscos: os endereços MAC podem ser falsificados e, a partir do iOS 14 e Android 10, é utilizada a aleatorização de endereços MAC por predefinição, o que quebra o mecanismo ao restabelecer a ligação.

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

Guia de implementação

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

Antes de escrever uma única linha de configuração, conclua estes cinco passos.

Primeiro, determine o contexto de acesso. Analise o seu espaço e identifique se os convidados vão encontrar o portal dentro do browser da aplicação WeChat, num browser móvel padrão ou em ambos. A resposta determina os seus requisitos de registo na plataforma.

Segundo, registe-se na plataforma correta. Para acesso através do browser da aplicação, crie uma Conta de Serviço na Plataforma de Contas Oficiais do WeChat. Para acesso através de um browser padrão, registe uma Aplicação Web na Plataforma Aberta do WeChat. Anote o seu AppID e AppSecret para cada uma.

Terceiro, configure os seus URIs de redirecionamento. Registe todos os domínios e subdomínios que o seu portal utiliza, incluindo ambientes de teste. O WeChat aplica uma validação de correspondência exata. Uma correspondência incorreta devolve o erro 40029.

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

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 utilizador, passe-o no pedido OAuth e valide-o no retorno.

Passos de configuração para o Ruckus SmartZone

Para locais que utilizam o Ruckus SmartZone, a configuração do portal WeChat encontra-se em Services and Profiles, depois em Hotspots and Portals, e de seguida no separador WeChat. Deve configurar o Authentication URL (o endpoint de callback do WeChat do seu servidor de portal), o DNAT Destination (o servidor que lida com redirecionamentos de clientes não autenticados) e o Grace Period (o período durante o qual um utilizador recentemente desligado se pode voltar a ligar sem nova autenticação, cujo valor predefinido é 60 minutos). Também deve configurar 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 Step-by-Step Guide: Configuring Ruijie Wireless Controllers for Guest WiFi Captive Portals para padrões de configuração de controladores comparáveis.

Deteção do browser integrado na aplicação

O browser integrado na aplicação do WeChat define uma string de user agent que contém MicroMessenger. O seu portal deve detetar esta string e apresentar o fluxo OAuth adequado. Se o MicroMessenger estiver presente, utilize o fluxo de Official Accounts. Se estiver ausente, utilize o fluxo de código QR da Open Platform. A falha na deteção correta desta string resulta em experiências com falhas ou erros de autenticação.

Melhores práticas

Minimização de dados e conformidade com duplo enquadramento legal

O GDPR (aplicável a visitantes europeus) e a PIPL (aplicável a cidadãos chineses) exigem uma base legal para o tratamento de dados pessoais, limitação clara da finalidade e minimização de dados. O âmbito snsapi_base é mais fácil de justificar sob os princípios de minimização de dados do que o snsapi_userinfo. Quando recolher dados demográficos através de snsapi_userinfo, documente a sua base legal, o período de retenção e o seu acordo de tratamento de dados com a Tencent.

A PIPL, em vigor desde novembro de 2021, exige consentimento explícito para informações pessoais sensíveis e determina que os processadores de dados fora da China implementem padrões de proteção equivalentes. Se o seu servidor de portal estiver localizado fora da China continental, deve avaliar se as regras de transferência transfronteiriça de dados se aplicam ao WeChat OpenID e aos dados de perfil que recebe.

UnionID para implementações multi-propriedade

O OpenID é único por utilizador e por Official Account. Se gere várias Official Accounts 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 associadas ao mesmo registo na Open Platform. Para cadeias hoteleiras, grupos de retalho ou operadores aeroportuários que gerem vários locais, implemente a resolução de identidade baseada em UnionID desde o início.

Reforço da segurança

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

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

Casos de estudo

Cadeia de hotéis de luxo, Singapura

Um hotel de luxo de 350 quartos em Singapura, que serve predominantemente um segmento de viagens de negócios chinês, implementou a autenticação WeChat WiFi a par da sua opção de login por e-mail existente. Antes da implementação, o pessoal da receção reportava uma média de 15 reclamações de hóspedes por dia sobre dificuldades de login no WiFi. Os hóspedes chineses tentavam utilizar endereços de e-mail que não tinham configurado nos seus dispositivos de viagem.

O hotel registou uma Service Account na WeChat Official Accounts Platform e uma Website Application na Open Platform. Configuraram o snsapi_userinfo para as primeiras ligações e o snsapi_base para os hóspedes recorrentes identificados pelo endereço MAC. O controlador HPE Aruba foi configurado para RADIUS CoA para gerir a promoção da sessão.

Em 30 dias, as reclamações de login de WiFi dos hóspedes caíram para menos de duas por dia. A base de dados de WiFi Analytics do hotel cresceu 4.200 perfis de primeira entidade verificados no primeiro mês, com dados demográficos ao nível da cidade a permitir comunicações direcionadas pós-estadia.

Centro comercial internacional, Kuala Lumpur

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

A implementação utilizou a plataforma Guest WiFi da Purple como sobreposição na nuvem, com o WeChat OAuth como método de autenticação principal e SMS OTP como alternativa de recurso. A arquitetura independente de hardware da Purple tratou da integração do RADIUS CoA com a Cisco Meraki sem necessidade de desenvolvimento personalizado.

O centro comercial registou um aumento de 34% no início de sessões WiFi no primeiro trimestre pós-implementação, atribuído à redução do atrito de integração para os utilizadores do WeChat. Os dados de primeira entidade recolhidos através de fluxos de consentimento snsapi_userinfo permitiram à equipa de marketing do centro comercial segmentar os compradores por cidade de origem para a entrega de campanhas direcionadas.

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

Erro	Causa	Resolução
40029 invalid code	Incompatibilidade de URI de redirecionamento ou reutilização de código	Verifique se os URIs registados coincidem exatamente; os códigos são de utilização única
40163 código expirado	Troca de token atrasada além de 5 minutos	Reduzir o tempo de processamento no lado do servidor; implementar lógica de repetição
Ecrã em branco após a autenticação	RADIUS CoA não configurado ou a falhar	Verificar as definições de CoA do controlador e as regras de firewall na porta UDP 3799
A aleatorização de MAC interrompe o fluxo de visitante recorrente	Aleatorização de MAC em iOS/Android	Migrar para rastreio de sessão baseado em OpenID; evitar identificação baseada apenas em MAC
snsapi_userinfo devolve campos vazios	O utilizador definiu restrições de privacidade no WeChat	Tratar campos nulos de forma adequada; não exigir dados de perfil para o acesso

ROI e impacto empresarial

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

Aquisição de dados primários (first-party). Cada autenticação snsapi_userinfo gera um perfil de visitante verificado com dados demográficos. Para um hotel de 200 quartos com 70% de ocupação e 40% de hóspedes chineses, isto representa aproximadamente 20 000 novos perfis verificados por ano, cada um associado a uma identidade WeChat que suporta a reiteração contínua de interações.

Redução da carga de suporte. O atrito no login é o principal fator que motiva as chamadas de suporte de WiFi de visitantes. Os locais que adicionam a autenticação WeChat juntamente com as opções existentes reportam consistentemente uma redução nas consultas de receção relacionadas com WiFi, libertando tempo da equipa para interações de maior valor.

Alcance de marketing. As Contas Oficiais do WeChat permitem que os locais enviem notificações para os seguidores. Um visitante que se autentique através da sua Conta Oficial pode ser convidado a segui-la, criando um canal de comunicação direto que funciona 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 isto ainda mais, permitindo mensagens automatizadas pós-visita, gatilhos de fidelidade e campanhas segmentadas criadas com base nos dados primários recolhidos no momento da autenticação de WiFi.

Definições Principais

Captive Portal

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

O mecanismo através do qual a autenticação de WiFi de convidados é apresentada aos utilizadores. 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 do setor que permite a uma aplicação de terceiros (o Captive Portal) obter acesso limitado a um serviço web (WeChat) em nome de um utilizador, sem que este partilhe a sua palavra-passe com terceiros.

A estrutura subjacente que torna possível o início de sessão do WeChat. O portal nunca vê as credenciais de WeChat do utilizador; apenas recebe um token que confirma que o WeChat os autenticou.

RADIUS CoA

Change of Authorisation (Alteração de Autorização). Um mecanismo definido no RFC 3576 que permite a um servidor RADIUS modificar 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 a CoA, o convidado autentica-se, mas o controlador não sabe que deve abrir a rede.

OpenID

Um identificador exclusivo atribuído pelo WeChat a um utilizador específico para uma Conta Oficial ou Aplicação Web específica. É estável entre sessões, mas difere entre contas.

A chave primária utilizada para identificar um convidado na sua base de dados de análise de WiFi. Utilize o UnionID em alternativa se gerir várias Contas Oficiais e necessitar de resolução de identidade entre contas.

snsapi_base

Um âmbito de WeChat OAuth que permite a autenticação silenciosa, devolvendo apenas o OpenID do utilizador sem apresentar um pedido de consentimento.

Utilize para convidados que regressam ou ambientes de alto rendimento onde a velocidade de ligação é a prioridade. Não devolve quaisquer dados demográficos além do OpenID.

snsapi_userinfo

Um âmbito de WeChat OAuth que devolve o OpenID do utilizador, alcunha, imagem de perfil, género, idioma e cidade, exigindo um ecrã de consentimento explícito do utilizador.

Utilize para o registo de convidados estreantes para criar um perfil de dados primários (first-party). Deve ser emparelhado com uma camada de consentimento em conformidade com o GDPR e a PIPL.

PIPL

Personal Information Protection Law (Lei de Proteção de Informações Pessoais). A legislação abrangente de privacidade de dados da China, em vigor desde novembro de 2021, que rege a forma como os dados pessoais de cidadãos chineses devem ser recolhidos, processados e transferidos.

Aplica-se a qualquer local que recolha dados de cidadãos chineses através do WeChat OAuth, independentemente de onde o local estiver 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 a sua aplicação quando esta chama a API de troca de tokens 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 pela sua aplicação e faça chamadas de API não autorizadas ao WeChat.

VLAN

Virtual Local Area Network (Rede Local Virtual). Um segmento de rede lógico que isola o tráfego na camada de ligação de dados, permitindo que uma única rede física transporte vários fluxos de tráfego isolados.

Utilizada em implementações de Captive Portal para separar dispositivos não autenticados (VLAN de jardim vedado) de convidados autenticados (VLAN de convidados). O RADIUS CoA move um dispositivo entre VLANs após uma autenticação bem-sucedida.

UnionID

Um identificador do WeChat que permanece consistente para um determinado utilizador em todas as Contas Oficiais e Aplicações Web associadas ao mesmo registo na Open Platform.

Essencial para cadeias hoteleiras, grupos de retalho e operadores de vários locais que necessitam de reconhecer o mesmo convidado em várias propriedades, cada uma com a sua própria Conta Oficial.

Exemplos Práticos

Um hotel de luxo de 200 quartos em Singapura utiliza controladores HPE Aruba e serve um volume elevado de viajantes de negócios chineses. Querem recolher dados demográficos de hóspedes que os visitam pela primeira vez e garantir que os hóspedes que regressam se ligam automaticamente sem verem o Captive Portal novamente. Como devem configurar a integração de WeChat OAuth?

Passo 1: Registar uma Conta de Serviço na Plataforma de Contas Oficiais do WeChat (mp.weixin.qq.com) para gerir os hóspedes que acedem ao Captive Portal dentro do browser in-app do WeChat. Registar uma Aplicação Web na Plataforma Aberta do WeChat (open.weixin.qq.com) para hóspedes em browsers móveis padrão.

Passo 2: Configurar o Captive Portal para detetar a string de user agent do MicroMessenger. Disponibilizar o fluxo de OAuth de Contas Oficiais para utilizadores de browsers in-app e o fluxo de código QR de Plataforma Aberta para utilizadores de browsers padrão.

Passo 3: Para ligações de primeira vez (sem OpenID existente na base de dados), solicitar o escopo snsapi_userinfo. Apresentar um ecrã de consentimento em conformidade com a PIPL antes do redirecionamento de OAuth. Armazenar o OpenID retornado, alcunha, cidade e género na base de dados de perfis de hóspedes.

Passo 4: Para hóspedes que regressam (o OpenID existe na base de dados), solicitar o escopo snsapi_base. Isto autentica silenciosamente sem qualquer aviso visível para o utilizador.

Passo 5: Configurar o controlador HPE Aruba para RADIUS CoA na porta UDP 3799. Após o OAuth bem-sucedido, o servidor do Captive Portal envia um pedido de CoA para promover o dispositivo da VLAN de walled garden para a VLAN de hóspedes.

Passo 6: Implementar o registo de endereços MAC juntamente com o OpenID para gerir a deteção de hóspedes que regressam. Note que a aleatorização de MAC exige o OpenID como identificador primário, e não apenas o endereço MAC.

Comentário do Examinador: Esta abordagem separa corretamente os dois registos de plataforma por contexto de acesso, utiliza a seleção de escopo para equilibrar a fricção com a recolha de dados, e implementa RADIUS CoA para aplicação segura de rede. A utilização do OpenID como o identificador primário de hóspedes que regressam é a resposta correta à aleatorização de MAC. A camada de consentimento PIPL é não negociável para dados de cidadãos chineses.

A equipa de TI de uma cadeia de retalho reporta uma elevada taxa de falha para logins de WeChat WiFi em três localizações de centros comerciais. Os utilizadores autenticam-se no WeChat mas são devolvidos à página do Captive Portal com um erro. Os registos do Captive Portal mostram o erro 40029. Qual é a causa provável e como se resolve?

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

Passo 1: Iniciar sessão na consola de programador do WeChat tanto para a Plataforma de Contas Oficiais como para a Plataforma Aberta. Navegar até às definições de OAuth e listar todos os URIs de redirecionamento registados.

Passo 2: Comparar estes URIs com os URIs de redirecionamento reais que o servidor do seu Captive Portal utiliza em produção nas três localizações. Verificar diferenças de subdomínios (portal.brand.com vs brand.com), diferenças de protocolo (HTTP vs HTTPS) e diferenças de caminho (/callback vs /wechat/callback).

Passo 3: Registar cada variante na consola do WeChat. O WeChat realiza uma validação de correspondência exata, não de correspondência de prefixo.

Passo 4: Se os URIs coincidirem, investigar se o servidor do seu Captive Portal está a tentar reutilizar códigos de autorização. Os códigos do WeChat são de utilização única e expiram após cinco minutos. Se o seu servidor tentar novamente a troca de tokens com o mesmo código, receberá o erro 40029 na segunda tentativa.

Passo 5: Implementar idempotência no endpoint de troca de tokens para evitar pedidos duplicados.

Comentário do Examinador: O erro 40029 é o erro mais comum em implementações de WeChat OAuth e é quase sempre causado por uma incompatibilidade do URI de redirecionamento. As implementações em várias localizações são particularmente vulneráveis porque cada localização pode utilizar 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 o registo do URI for confirmado como correto.

Perguntas de Prática

Q1. Está a implementar um Captive Portal para um estádio com capacidade para 60.000 pessoas que acolhe eventos internacionais com uma base significativa de adeptos chineses. A prioridade é colocar todos os participantes online nos primeiros 15 minutos após a abertura das portas para reduzir o congestionamento da rede móvel. A recolha de dados de marketing é um objetivo secundário. Qual o âmbito do WeChat OAuth que deve configurar e porquê?

Dica: Considere o impacto de um ecrã de consentimento apresentado a 15.000 utilizadores simultâneos num servidor de portal.

Ver resposta modelo

Configure o âmbito snsapi_base. Isto permite a autenticação silenciosa sem qualquer pedido de consentimento do utilizador, proporcionando a experiência de adesão mais rápida possível. À escala de um estádio, um ecrã de consentimento adiciona fricção que se multiplica por milhares de ligações simultâneas e pode causar picos de carga no servidor do portal. O snsapi_base devolve apenas o OpenID, o que é suficiente para registar a sessão e identificar os adeptos que regressam. Para os adeptos que o visitam pela primeira vez e dos quais deseja obter dados demográficos, pode solicitar o preenchimento do perfil através de um inquérito pós-ligação, em vez de o fazer na barreira de autenticação.

Q2. Um arquiteto de rede da sua equipa propõe guardar o WeChat AppSecret no JavaScript do lado do cliente do Captive Portal para reduzir as comunicações de ida e volta ao servidor, efetuando a chamada de troca de token diretamente do navegador. Explique por que razão esta 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 lhes permite fazer.

Ver resposta modelo

Guardar o AppSecret no JavaScript do lado do cliente expõe-no a qualquer pessoa que visualize o código-fonte da página ou intersete o tráfego de rede. O AppSecret autentica a sua aplicação perante a API do WeChat. Com ele, um ator malicioso pode personificar a sua aplicação, chamar o ponto de extremidade de troca de token do WeChat com qualquer código de autorização válido, recuperar os OpenIDs e dados de perfil dos utilizadores e, potencialmente, esgotar os limites de taxa da sua API. A arquitetura correta é um ponto de extremidade de troca de token no lado do servidor. O navegador recebe o código de autorização do WeChat e envia-o para o seu servidor. O seu servidor, utilizando o AppSecret armazenado numa variável de ambiente ou num gestor de segredos, troca o código por um token e devolve apenas os dados de que o portal necessita. O AppSecret nunca sai do seu servidor.

Q3. O seu espaço gere três unidades hoteleiras em cidades diferentes, cada uma com a sua própria Conta Oficial do WeChat. Um membro do programa de fidelização que se autenticou nas três propriedades tem três OpenIDs diferentes na sua base de dados. Como resolve isto numa única identidade de hóspede?

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

Ver resposta modelo

Implemente o mecanismo UnionID do WeChat. Associe as três Contas Oficiais ao mesmo registo de Plataforma Aberta em open.weixin.qq.com. Uma vez associadas, o WeChat devolve um UnionID juntamente com o OpenID na resposta snsapi_userinfo. O UnionID é consistente para um determinado utilizador em todas as contas associadas ao mesmo registo de Plataforma Aberta. Migre a sua base de dados para utilizar o UnionID como o identificador principal de hóspede para registos entre propriedades, mantendo o OpenID por conta para chamadas de API específicas de cada conta. Para os hóspedes que se autenticaram antes da implementação do UnionID, acione uma nova autenticação com snsapi_userinfo na sua próxima visita para capturar o UnionID.

Q4. Após a implementação da autenticação WeChat WiFi num espaço comercial que utiliza pontos de acesso Cisco Meraki, os hóspedes reportam que concluem o início de sessão do WeChat com sucesso, mas são devolvidos à página do portal e não conseguem navegar na Internet. Os registos do servidor do portal mostram a recuperação de token bem-sucedida. Qual é a causa mais provável e como a diagnostica?

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

Ver resposta modelo

A Alteração de Autorização RADIUS (CoA) não está a ser concluída. O servidor do portal verificou a identidade do hóspede através do WeChat OAuth, mas não instruiu com sucesso o controlador Cisco Meraki a mover o dispositivo da VLAN do portal cativo para la VLAN de convidados. Diagnostique verificando: (1) se o controlador Meraki tem o RADIUS CoA ativado e se o IP do servidor do portal está listado como um cliente CoA autorizado; (2) se a porta UDP 3799 está aberta entre o servidor do portal e o controlador; (3) os registos do servidor do portal quanto a erros de pedido de CoA ou tempos limite excedidos; e (4) se o segredo partilhado configurado em ambos os lados coincide. Se a CoA não for suportada no seu nível de licença Meraki, o desvio por endereço MAC é a alternativa, embora comporte o risco de aleatorização de MAC mencionado no guia.

Continue a ler esta série

How to Set Up a Captive Portal on Starlink: A Guide for Remote & Maritime Venues

Este guia detalha como contornar o hardware nativo da Starlink e integrar um Captive Portal gerido na nuvem utilizando equipamento de encaminhamento empresarial. Irá aprender a ultrapassar a limitação de CGNAT, impor a segmentação de VLAN, gerir as restrições de largura de banda de satélite e garantir a conformidade regulamentar.

Captive Portal Best Practices: Designing for High Conversion and Compliance

Este guia técnico oferece aos gestores de TI, arquitetos de rede e diretores de operações de espaços comerciais um plano completo para implementar portais cativos que equilibram a segurança de rede com uma elevada conversão de utilizadores. Abrange toda a arquitetura, desde a segmentação de VLAN e autenticação RADIUS até ao design de consentimento em conformidade com o GDPR e à seleção do método de autenticação. Com base na experiência operacional da Purple em mais de 80.000 locais e 440 milhões de inícios de sessão em 2024, cada recomendação é fundamentada em dados reais de implementação.

Como Otimizar Captive Portals para a Máxima Segurança de Rede e Conversão de Utilizadores

Este guia fornece um plano técnico completo para otimizar captive portals em locais empresariais, abrangendo a arquitetura de segmentação de rede, a seleção do método de autenticação, o design de consentimento em conformidade com o GDPR e a otimização da conversão. Foi escrito para gestores de TI, arquitetos de rede e CTOs em hotéis, cadeias de retalho, estádios e organizações do setor público que precisam de equilibrar a segurança de rede com a captura de dados primários (first-party). A Purple opera infraestruturas de captive portal em mais de 80.000 locais com 440 milhões de inícios de sessão em 2024, e as estruturas aqui apresentadas refletem essa experiência operacional.