Integrar a Autenticação WiFi do WeChat: Integração de Captive Portal para Clientes da APAC

O WeChat tem 1,41 mil milhões de utilizadores ativos mensais, tornando-se a identidade digital primária 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 locais na APAC, abrangendo o registo na plataforma, a seleção de âmbito, a aplicação de RADIUS Change of Authorisation e a 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 locais que precisam de agir este trimestre.

📖 9 min de leitura📝 2,524 palavras🔧 2 exemplos práticos❓ 4 perguntas de prática📚 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
Uma Sessão Técnica da Purple - Aproximadamente 10 Minutos

INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto)

Bem-vindo. Se é responsável pelo WiFi de convidados num hotel, cadeia de lojas, estádio ou centro de conferências que serve visitantes chineses, esta sessã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 tem também uma presença internacional significativa. A Malásia tem 12 milhões de utilizadores do 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 barreira imediata. Podem 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 o WeChat. É sim como o configurar corretamente, de forma segura e de modo a gerar dados primários que possa realmente utilizar.

É isso que vamos cobrir hoje. Vamos analisar o fluxo OAuth 2.0, os dois registos de plataforma que necessita, a decisão de âmbito (scope) que determina quais os dados que recolhe, o mecanismo de imposição do lado da rede e as considerações de conformidade que importam em 2026.

ANÁLISE TÉCNICA DETALHADA (aproximadamente 5 minutos)

Comecemos pela arquitetura. Um Captive Portal 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 é alojada num servidor de portal, seja local ou na nuvem. Quando adiciona o WeChat OAuth, está a inserir um fornecedor de identidade de terceiros nesse fluxo.

Eis a sequência. O convidado liga-se ao seu SSID. O ponto de acesso ou controlador sem fios deteta que o dispositivo não tem uma sessão autenticada e redireciona todo o tráfego HTTP para o URL do seu Captive Portal. A página do portal carrega e apresenta as opções de login, incluindo o WeChat. O convidado toca no login do WeChat. O seu servidor de portal redireciona o navegador para o endpoint de autorização do WeChat, passando o seu AppID, o URI de redirecionamento, o tipo de resposta (response type) do código e o âmbito (scope).

O WeChat lida com a autenticação inteiramente nos seus próprios servidores. Se o convidado já tiver sessão iniciada no WeChat no seu navegador, verá um ecrã de consentimento. Se estiver a utilizar o navegador interno da aplicação WeChat, a experiência pode ser silenciosa com o âmbito snsapi base, o que significa que não há qualquer pedido de consentimento. O WeChat redireciona então de volta para o URI de redirecionamento do seu portal com um código de autorização temporário. O seu servidor de portal troca esse código por um token de acesso ao chamar a API do WeChat. O WeChat devolve um token de acesso, um token de atualização (refresh token), o OpenID do utilizador e o âmbito concedido. Se tiver solicitado o âmbito snsapi userinfo, pode então fazer uma segunda chamada de API para obter o nome de utilizador (nickname), 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 programadores separadas. A WeChat Open Platform gere aplicações web e aplicações móveis. A WeChat Official Accounts Platform gere contas públicas, que é o que a maioria dos espaços realmente precisa.

Para um Captive Portal que sirva os convidados dentro do navegador integrado do WeChat, precisa de uma Service Account na Official Accounts Platform. Uma Subscription Account não irá funcionar. Esta não tem permissões de autorização de páginas web OAuth. Uma Service Account tem, e suporta tanto o escopo snsapi base como o snsapi userinfo.

Para um Captive Portal acedido a partir de um navegador móvel padrão fora do WeChat, como o Chrome no Android ou o Safari no iOS, precisa 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 aplicação WeChat.

Na prática, a maioria das implementações em espaços utiliza ambos. Um convidado 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, aterrar no navegador integrado e autenticar-se silenciosamente com o snsapi base.

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

O escopo snsapi base devolve apenas o OpenID. Este é um identificador exclusivo para esse utilizador dentro da sua Official Account. Não requer qualquer confirmação de consentimento do utilizador. A autenticação é invisível para o utilizador. Isto é ideal para convidados que regressam e dos quais já tem um perfil, ou para espaços onde deseja fricção zero à custa de zero novos dados.

O escopo snsapi userinfo devolve o OpenID mais o nome de utilizador do WeChat, a imagem de perfil, o género, a definição de idioma e a cidade. Requer um ecrã de consentimento explícito. O utilizador vê 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 utilização. Para o primeiro registo de um convidado onde deseja criar um perfil, utilize o snsapi userinfo e combine-o com uma camada de consentimento em conformidade com o GDPR na página do seu portal. Para um convidado que regressa, que já deu o seu consentimento e cujo perfil já possui, utilize o snsapi base para uma nova autenticação silenciosa.

Agora, a parte da aplicação na rede. Obter um token OAuth prova a identidade, mas não abre automaticamente a rede. 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 desvio de endereço MAC. Com o RADIUS CoA, o servidor do seu portal envia um pedido de CoA para o controlador de rede após o sucesso do OAuth, e o controlador move o dispositivo da VLAN não autenticada para a VLAN de convidados. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme Networks e Fortinet.

\nCom o bypass de MAC, o servidor do portal regista o endereço MAC do dispositivo como um cliente autorizado e o controlador permite a ligação. O bypass de MAC é mais simples de implementar mas menos seguro, porque os endereços MAC podem ser falsificados, e os smartphones modernos usam cada vez mais a aleatorização de endereços MAC, o que quebra o mecanismo ao voltar a ligar.

A plataforma de Guest WiFi da Purple lida com ambos os mecanismos. Após a conclusão do OAuth do WeChat, a sobreposição de nuvem da Purple envia o sinal apropriado para o hardware subjacente. O operador do espaço não precisa de gerir essa tradução manualmente.

RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS (aproximadamente 2 minutos)

Deixe-me apresentar-lhe as cinco coisas que fazem com que as implementações de portal cativo com OAuth do WeChat falhem.

Primeiro: a incompatibilidade de 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 testes.

Segundo: o AppSecret do lado do cliente. O seu AppSecret nunca deve aparecer no JavaScript do lado do cliente ou num binário de aplicação móvel. Pertence ao seu servidor. Se for exposto, qualquer pessoa pode fingir ser a sua aplicação e chamar as APIs do WeChat em seu nome.

Terceiro: falta de proteção CSRF. O parâmetro de estado no pedido de OAuth existe especificamente para prevenir falsificação de pedidos entre sites. Gere um valor de estado criptograficamente aleatório, armazene-o na sessão do utilizador e valide-o quando o WeChat redirecionar de volta. Ignore isto e terá uma vulnerabilidade real.

Quarto: a falha de deteção do navegador integrado na aplicação. O navegador integrado na aplicação do WeChat define uma cadeia de agente do utilizador específica contendo 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: alinhamento com o GDPR e a PIPL. Se serve visitantes europeus, o GDPR aplica-se aos dados que recolhe através do OAuth do WeChat. 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 de 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 legal 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 portais empresariais, 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 OAuth do WeChat funciona em iOS?
Sim, mas com uma nuance. A estrutura de Transparência do Rastreio de Aplicações 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 WeChat trata da autenticação.
Pergunta: O que acontece se a API do WeChat estiver indisponível?
O seu portal deve implementar uma alternativa. Se a chamada da API do WeChat expirar ou devolver 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 entre elas. Para a resolução de identidade entre contas, o WeChat fornece um UnionID, que exige que as suas contas estejam associadas na Plataforma Aberta.

RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto)

Em resumo. A autenticação WeChat OAuth para portais cativos é um exercício de registo em duas plataformas, uma decisão de âmbito, uma integração de aplicaçã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 potenciais visitantes sem qualquer 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 browser integrado do WeChat ou num browser móvel padrão. Isso determina qual o registo de plataforma de que necessita. Segundo, decida o âmbito. Utilize o snsapi base para visitantes recorrentes e o snsapi userinfo para o primeiro registo com consentimento. Terceiro, confirme se o hardware da sua rede suporta RADIUS CoA ou configure o desvio de MAC como alternativa. Quarto, reveja o seu aviso de privacidade e o fluxo de consentimento face aos requisitos do GDPR e da PIPL. Quinto, teste o URI de redirecionamento, a validação do parâmetro de estado e a deteção do browser integrado antes de entrar em direto.

Se quiser ver como a Purple gere o WeChat OAuth como parte de uma plataforma mais ampla de WiFi para convidados e análise de dados, 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 por ouvir.

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 locais que servem convidados da região APAC não se podem dar ao luxo de o omitir das suas opções de início de sessão do Captive Portal.
✓São necessários dois registos de plataforma: uma Service Account na Official Accounts Platform para acesso através do navegador na aplicação, e uma Website Application na Open Platform para acesso através de um navegador padrão. Utilizar o tipo de registo incorreto é a falha de implementação mais comum.
✓A seleção do âmbito é uma decisão de arquitetura 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 este, 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 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 de WeChat OAuth. Documente a sua base jurídica, 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 em múltiplas propriedades, implemente o UnionID do WeChat desde o início. Os OpenIDs diferem por Official Account; o UnionID fornece uma identidade de convidado consistente em todas as contas associadas.

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

Integrar a Autenticação WiFi do WeChat: Integração de Captive Portal para Clientes da APAC

Resumo executivo

Para espaços empresariais que operam 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 dos 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 depara-se com uma fricção imediata. Quase de certeza que tem o 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. Abordamos os dois registos de plataforma distintos que a Tencent exige, a decisão de âmbito (scope) que determina quais os dados primários que recolhe e o mecanismo 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 da China (PIPL).

A plataforma Guest WiFi da Purple automatiza a camada de aplicaçã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 espaços ativos e registou 440 milhões de inícios de sessão em 2024 (dados internos da Purple).

Análise técnica aprofundada

O fluxo OAuth 2.0

Um Captive Portal (um gateway de autenticação baseado na web que interseta 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, no local ou na nuvem. 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 ponto de extremidade (endpoint) de autorização do WeChat em open.weixin.qq.com, transmitindo quatro parâmetros: o AppID, o URI de redirecionamento, o tipo de resposta definido como code e o âmbito (scope) solicitado.

O WeChat autentica o utilizador inteiramente na sua própria infraestrutura. Se o visitante já tiver sessão iniciada através do navegador interno do WeChat, o escopo snsapi_base permite a 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, código e tipo de concessão. O WeChat devolve um token de acesso, um token de atualização, 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 obtém a alcunha do utilizador, a imagem de perfil, o género e a cidade.

Integrar a Autenticação WiFi do WeChat: Integração de Captive Portal para Clientes da APAC - architecture overview

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

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

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 funcionará. Esta carece de permissões de autorização de página web OAuth. Apenas uma Conta de Serviço possui essas permissões.

A maioria das implementações empresariais em Hospitality e Retail implementa ambos os registos. Um visitante num hotel pode abrir o 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 hiperligaçã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. Determina a fricção que o utilizador experimenta e os dados que a sua plataforma de WiFi Analytics recebe.

snsapi_base devolve apenas o OpenID - um identificador estável e exclusivo para esse utilizador dentro da sua Conta Oficial. Não requer nenhum aviso de consentimento do utilizador. A autenticação é invisível. Utilize esta opção para visitantes recorrentes cujos perfis já possui, ou para ambientes de elevado fluxo, como estádios e centros de transporte, onde a velocidade de ligação é a prioridade.

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

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

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

Um token OAuth comprova 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 sem fios. O controlador atualiza a sessão, movendo o dispositivo da VLAN de portal cativo (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 regista o endereço MAC do dispositivo como um cliente autorizado após o OAuth bem-sucedido. O controlador permite então o tráfego desse endereço sem qualquer outra validação. É mais simples de implementar, mas acarreta dois riscos: os endereços MAC podem ser falsificados e o iOS 14 e o Android 10 em diante utilizam 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 irão encontrar o portal dentro do browser integrado do 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 integrado, crie uma Conta de Serviço na WeChat Official Accounts Platform. Para acesso através de browser padrão, registe uma Website Application na WeChat Open Platform. 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 incompatibilidade 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 de 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 de OAuth e valide-o no retorno.

Passos de configuração para Ruckus SmartZone

Para locais que executam Ruckus SmartZone, a configuração do portal WeChat encontra-se em Services and Profiles, depois Hotspots and Portals e, finalmente, no separador WeChat. Configure o URL de Autenticação (o endpoint de callback do WeChat do seu servidor de portal), o Destino DNAT (o servidor que lida com os redirecionamentos de clientes não autenticados) e o Período de Tolerância (a janela durante a qual um utilizador recentemente desligado se pode voltar a ligar sem nova autenticação, cujo valor predefinido é de 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 de navegador na aplicação

O navegador interno da aplicação WeChat define uma string de user agent que contém MicroMessenger. O seu portal deve detetar esta string e apresentar o fluxo de OAuth adequado. Se o MicroMessenger estiver presente, utilize o fluxo de Contas Oficiais. Se estiver ausente, utilize o fluxo de código QR da Plataforma Aberta. A falha em detetar isto corretamente resulta em experiências interrompidas ou erros de autenticação.

Melhores práticas

Minimização de dados e conformidade com duplo enquadramento

O GDPR (aplicável a visitantes europeus) e a PIPL (aplicável a cidadãos chineses) exigem uma base jurídica para o processamento de dados pessoais, uma limitação clara da finalidade e a minimização dos dados. O âmbito snsapi_base é mais fácil de justificar ao abrigo dos 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 jurídica, o seu período de retenção e o seu acordo de processamento 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 aos dados de OpenID e de perfil do WeChat que recebe.

UnionID para implementações multipropriedade

O OpenID é único por utilizador e por Conta Oficial. Se 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 associadas ao mesmo registo da Plataforma Aberta. 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 de segurança

Guarde o AppSecret numa variável de ambiente ou num gestor de segredos, nunca no código-fonte. Rode-o imediatamente se suspeitar de exposição. Implemente a 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 Por que Equipamento de WiFi de Consumo Não Deve Estar na Sua Rede de Convidados .

Casos de estudo

Cadeia de hotéis de luxo, Singapura

Um hotel de luxo com 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 opção de início de sessão por e-mail já existente. Antes da implementação, a equipa da receção reportava uma média de 15 reclamações de hóspedes por dia sobre dificuldades de início de sessão 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 snsapi_userinfo para as primeiras ligações e 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 de sessões.

Em 30 dias, as reclamações de início de sessão no WiFi de convidados caíram para menos de duas por dia. A base de dados de WiFi Analytics do hotel cresceu 4200 perfis verificados em nome próprio 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 WeChat apenas na Malásia, necessitava de uma experiência de integração de WiFi que correspondesse às expectativas digitais da sua base de clientes. O centro comercial operava pontos de acesso Cisco Meraki em 180 000 metros quadrados de área comercial.

A implementação utilizou a plataforma de Guest WiFi da Purple como a 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 geriu a integração de 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 de WiFi no primeiro trimestre após a implementação, atribuído à redução da fricção na integração para utilizadores WeChat. Os dados em nome próprio recolhidos através dos fluxos de consentimento snsapi_userinfo permitiram à equipa de marketing do centro comercial segmentar os compradores pela cidade de origem para a entrega de campanhas direcionadas.

Integrar a Autenticação WiFi do WeChat: Integração de Captive Portal para Clientes da APAC - retail venue wechat wifi

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 correspondem exatamente; os códigos são de utilização única
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 randomização de MAC quebra o fluxo de visitante frequente	Randomização de MAC em iOS/Android	Migrar para a monitorização de sessão baseada em OpenID; evitar a identificação apenas por MAC
snsapi_userinfo devolve campos vazios	O utilizador definiu restrições de privacidade no WeChat	Tratar campos nulos graciosamente; não exigir dados de perfil para o acesso

Retorno do investimento e impacto empresarial

O caso de negócio para a autenticação de WiFi via WeChat assenta 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 com uma taxa de ocupação de 70% e 40% de hóspedes chineses, isso representa aproximadamente 20.000 novos perfis verificados por ano, cada um associado a uma identidade WeChat que suporta a reinteração contínua.

Redução da carga de suporte. O atrito no login é o principal fator que origina chamadas de suporte de WiFi de visitantes. Os locais que adicionam a autenticação WeChat em conjunto com as opções existentes relatam 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 incentivado 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 Purple Engage expande isto ainda mais, permitindo mensagens automatizadas pós-visita, acionadores de fidelização e campanhas segmentadas criadas com base nos dados primários recolhidos no momento da autenticação de WiFi.

Definições Principais

Captive Portal

Uma gateway de autenticação baseada na web que intercepta 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 OAuth do WeChat é 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 da indústria 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 o início de sessão do WeChat possível. O portal nunca vê as credenciais do WeChat do utilizador; apenas recebe um token a confirmar que o WeChat o autenticou.

RADIUS CoA

Change of Authorisation. 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 bem-sucedida de OAuth do WeChat em acesso real à rede. Sem 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 vez disso caso opere múltiplas Contas Oficiais e necessite de resolução de identidade entre contas.

snsapi_base

Um âmbito de OAuth do WeChat que permite a autenticação silenciosa, devolvendo apenas o OpenID do utilizador sem exibir uma solicitação de consentimento.

Utilize para convidados recorrentes 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 OAuth do WeChat que devolve o OpenID, o pseudónimo, a imagem de perfil, o género, o idioma e a cidade do utilizador, exigindo um ecrã de consentimento explícito do utilizador.

Utilize para o registo de convidados pela primeira vez para criar um perfil de dados próprio. 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 regula a forma como os dados pessoais dos cidadãos chineses devem ser recolhidos, processados e transferidos.

Aplica-se a qualquer local que recolha dados de cidadãos chineses através do OAuth do WeChat, independentemente de onde o local esteja situado. Requer consentimento explícito, limitação da 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 para o WeChat.

VLAN

Virtual Local Area Network. 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 múltiplos fluxos de tráfego isolados.

Utilizado em implementações de Captive Portal para separar dispositivos não autenticados (VLAN de walled garden) de convidados autenticados (VLAN de convidados). 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 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 múltiplos 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 com 200 quartos em Singapura utiliza controladores HPE Aruba e serve um elevado volume de viajantes de negócios chineses. Querem recolher dados demográficos de hóspedes frequentes na primeira visita e garantir que os hóspedes que regressam se ligam automaticamente sem verem o portal novamente. Como devem configurar a integração do 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 portal dentro do browser integrado 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 MicroMessenger. Disponibilizar o fluxo OAuth de Contas Oficiais para utilizadores do browser integrado e o fluxo de código QR da Plataforma Aberta para utilizadores de browsers padrão.

Passo 3: Para as ligações pela primeira vez (sem OpenID existente na base de dados), solicitar o âmbito snsapi_userinfo. Apresentar um ecrã de consentimento em conformidade com a PIPL antes do redirecionamento do OAuth. Guardar o OpenID, o pseudónimo, a cidade e o género devolvidos na base de dados de perfis de hóspedes.

Passo 4: Para os hóspedes que regressam (o OpenID existe na base de dados), solicitar o âmbito 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 portal envia um pedido de CoA para promover o dispositivo do VLAN de walled garden para o 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 o identificador primário, e não apenas o endereço MAC isolado.

Comentário do Examinador: Esta abordagem separa corretamente os dois registos de plataforma por contexto de acesso, utiliza a seleção de âmbito para equilibrar a fricção com a recolha de dados e implementa RADIUS CoA para uma aplicação de rede segura. A utilização do OpenID como o identificador primário para 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 taxa de falha elevada para inícios de sessão WiFi do WeChat em três localizações de centros comerciais. Os utilizadores autenticam-se no WeChat, mas regressam à página do portal com um erro. Os registos do 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 a 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 com os URIs de redirecionamento reais que o seu servidor do portal utiliza em produção nas três localizações. Verificar se existem 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).

Passo 3: Registar todas as variantes 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 corresponderem, investigar se o seu servidor do 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 a 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 OAuth do WeChat e é quase sempre causado por uma incompatibilidade do URI de redirecionamento. As implementaçõ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 configuração do registo do URI estiver confirmada como correta.

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 de 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 exibido a 15 000 utilizadores simultâneos num servidor de portal.

Ver resposta modelo

Configure o âmbito snsapi_base. Isto permite uma autenticação silenciosa sem pedido de consentimento ao utilizador, proporcionando a experiência de integraçã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 se ligam 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 no portal de autenticação.

Q2. Um arquiteto de rede da sua equipa propõe armazenar 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 a partir do browser. 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

Armazenar 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 utilizador malicioso pode fazer-se passar pela sua aplicação, chamar o endpoint de troca de token do WeChat com qualquer código de autorização válido, obter os OpenIDs e dados de perfil dos utilizadores e, potencialmente, esgotar os limites de taxa da sua API. A arquitetura correta é um endpoint de troca de token do lado do servidor. O browser 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 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 opera três propriedades 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 cliente?

Dica: O WeChat fornece um mecanismo de resolução de identidade entre várias 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 associado, 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 do cliente para registos entre propriedades, mantendo o OpenID por conta para chamadas de API específicas de cada conta. Para os clientes 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 implementar a autenticação WeChat WiFi num espaço comercial equipado com pontos de acesso Cisco Meraki, os clientes relatam que concluem o início de sessão do WeChat com sucesso, mas regressam à página do portal e não conseguem navegar na internet. Os registos do servidor do portal mostram que a obtenção do token foi 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

O RADIUS Change of Authorisation (CoA) não está a ser concluído. O servidor do portal verificou a identidade do convidado através de WeChat OAuth, mas não instruiu com sucesso o controlador Cisco Meraki a mover o dispositivo do VLAN de walled garden para o 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 para erros ou tempos de espera excedidos (timeouts) no pedido CoA; e (4) se o segredo partilhado configurado em ambos os lados coincide. Se o CoA não for suportado no seu nível de licença Meraki, o desvio por endereço MAC (MAC address bypass) é a alternativa, embora comporte o risco de aleatoriedade de MAC indicado no guia.

Continue a ler esta série

Captive Portal para Ruijie: configure-o com o Purple guest WiFi

Como o cloud guest WiFi da Purple funciona sobre os pontos de acesso Ruijie RG Series utilizando autenticação web e RADIUS, configurado a partir da linha de comandos, e onde encontrar os passos exatos de configuração.

Conceber Captive Portals B2B: Recolha de Nome Registado e Dados da Empresa

Este guia fornece aos gestores de TI e operadores de espaços uma estrutura técnica independente de fornecedor para conceber Captive Portals B2B. Detalha como estruturar os campos de registo para capturar o nome registado e os dados da empresa, garantindo elevadas taxas de conclusão, mantendo a conformidade com o GDPR e construindo inteligência ao nível da conta.

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

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