Saltar para o conteúdo principal

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

Este guia explica como integrar a autenticação WeChat OAuth 2.0 em Captive Portals de Wi-Fi de convidados empresariais. Aborda os requisitos de registo em dupla plataforma, a seleção de âmbito (scope) para a recolha de dados primários (first-party), a imposição de rede via RADIUS Change of Authorization e a conformidade com o GDPR e a PIPL da China. Os operadores de espaços nos setores da hotelaria, retalho e eventos encontrarão passos concretos de implementação, estudos de caso reais e orientações de reforço de segurança para implementar o início de sessão WeChat em Wi-Fi de convidados em grande escala.

📖 8 min de leitura📝 1,966 palavras🔧 2 exemplos práticos4 perguntas de prática📚 9 definições principais

Ouça este guia

Ver transcrição do podcast
COMO CONFIGURAR A AUTENTICAÇÃO WECHAT OAUTH PARA CAPTIVE PORTALS Uma Apresentação Técnica da Purple - Aproximadamente 10 Minutos --- INTRODUÇÃO E CONTEXTO (aproximadamente 1 minuto) Bem-vindo. Se é responsável pelo Wi-Fi de convidados num hotel, cadeia de retalho, estádio ou centro de conferências que serve visitantes chineses, esta apresentação é para si. O WeChat tem 1,38 mil milhões de utilizadores ativos mensais, de acordo com os dados de 2024 da Tencent. A esmagadora maioria está na China, mas a plataforma tem também uma pegada internacional significativa – quatro milhões de utilizadores nos Estados Unidos, 12 milhões na Malásia e números crescentes no Sudeste Asiático, Europa e Médio Oriente. Quando um convidado chinês se liga ao seu Wi-Fi e vê uma página de início de sessão apenas com e-mail, Facebook ou um código de voucher, depara-se com um atrito imediato. É muito provável que não tenha um endereço de e-mail local configurado nesse dispositivo. Mas tem quase de certeza o WeChat. Portanto, a questão não é se deve oferecer o início de sessão com o WeChat – é como configurá-lo corretamente, de forma segura e de modo a gerar dados primários (first-party) que possa realmente utilizar. É isso que vamos abordar hoje. Vamos percorrer o fluxo do OAuth 2.0, os dois registos de plataforma de que necessita, a decisão sobre o âmbito (scope) que determina quais os dados que recolhe, o mecanismo de imposição do lado da rede e as considerações de conformidade que importam em 2026. --- ANÁLISE TÉCNICA DETALHADA (aproximadamente 5 minutos) Comecemos pela arquitetura. Um Captive Portal interpeta o tráfego HTTP de um dispositivo não autenticado e redireciona-o para uma página de início de sessão. Essa página de início de sessão é alojada num servidor de portal – localmente ou na nuvem. Quando adiciona o WeChat OAuth, está a inserir um fornecedor de identidade de terceiros nesse fluxo. Eis a sequência. O convidado liga-se ao seu SSID. O ponto de acesso ou controlador sem fios deteta que o dispositivo não tem uma sessão autenticada e redireciona todo o tráfego HTTP para o URL do seu Captive Portal. A página do portal carrega e apresenta as opções de início de sessão – incluindo o WeChat. O convidado toca no início de sessão do WeChat. O servidor do seu portal redireciona o navegador para o endpoint de autorização do WeChat, transmitindo o seu App ID, o URI de redirecionamento, o tipo de resposta 'code' e o âmbito (scope). O WeChat trata da autenticação inteiramente nos seus próprios servidores. Se o convidado já tiver sessão iniciada no WeChat no seu navegador, verá um ecrã de consentimento. Se estiver a utilizar o navegador na aplicação (in-app) do WeChat, a experiência pode ser silenciosa com o âmbito snsapi base – sem qualquer pedido de consentimento. O WeChat redireciona então de volta para o URI de redirecionamento do seu portal com um código de autorização temporário. O servidor do seu portal troca esse código por um token de acesso, transmitindo o seu App ID, App Secret, o código e o tipo de concessão 'authorization_code'. O WeChat devolve um token de acesso, um token de atualização, o Open ID do utilizador e o âmbito concedido. Se tiver solicitado o âmbito snsapi userinfo, pode então fazer uma segunda chamada de API para obter o pseudónimo, o avatar, o género e a cidade do utilizador. Agora, os dois registos de plataforma. É aqui que a maioria das implementações falha. O WeChat tem duas plataformas de programadores distintas. A WeChat Open Platform lida com aplicações web e aplicações móveis. A WeChat Official Accounts Platform lida com contas públicas – o que a maioria dos espaços realmente necessita. Para um Captive Portal que serve convidados dentro do navegador na aplicação (in-app) do WeChat, necessita de uma Conta de Serviço (Service Account) na Official Accounts Platform. Uma Conta de Subscrição (Subscription Account) não funcionará – não tem permissões de autorização de páginas web OAuth. Uma Conta de Serviço tem, e suporta os âmbitos snsapi base e snsapi userinfo. Para um Captive Portal acedido a partir de um navegador móvel padrão fora do WeChat – Chrome no Android, Safari no iOS – necessita de uma Aplicação Web (Website Application) registada na Open Platform. Esta utiliza o âmbito snsapi login e apresenta um código QR que o utilizador digitaliza com a sua aplicação WeChat. Na prática, a maioria das implementações em espaços utiliza ambos. Um convidado no Wi-Fi de um hotel pode abrir o portal no Chrome, ver um código QR, digitalizá-lo com o WeChat e autenticar-se. Ou pode seguir uma ligação no próprio WeChat, aceder ao navegador na aplicação (in-app) e autenticar-se silenciosamente com o snsapi base. Falemos sobre a seleção do âmbito (scope), porque este é um verdadeiro ponto de decisão. O snsapi base devolve apenas o Open ID – um identificador exclusivo para esse utilizador dentro da sua Conta Oficial (Official Account). Não requer qualquer pedido de consentimento do utilizador. A autenticação é invisível para o utilizador. Isto é ideal para convidados frequentes dos quais já tem o perfil criado, ou para espaços onde deseja zero atrito. O snsapi userinfo devolve o Open ID mais o pseudónimo do WeChat, a imagem de perfil, o género, a definição de idioma e a cidade do utilizador. Requer um ecrã de consentimento explícito. A maioria dos utilizadores aceita, mas existe atrito. A escolha certa depende do seu caso de utilização. Para o registo de um convidado pela primeira vez, onde deseja criar um perfil, utilize o snsapi userinfo e combine-o com uma camada de consentimento em conformidade com o GDPR na página do seu portal. Para um convidado frequente que já deu o seu consentimento e cujo perfil já possui, utilize o snsapi base para uma reautenticação silenciosa. Agora, o lado da imposição de rede. Obter um token OAuth prova a identidade, mas não abre automaticamente a rede. Necessita de um mecanismo para traduzir uma autenticação bem-sucedida em acesso à rede. As duas abordagens padrão são o RADIUS Change of Authorization, definido no RFC 3576, e o bypass de endereço MAC. Com o RADIUS CoA, o servidor do seu portal envia um pedido de CoA para o controlador de rede após o OAuth bem-sucedido, e o controlador move o dispositivo da VLAN não autenticada para a VLAN de convidados. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist e a maioria dos controladores de nível empresarial. Com o bypass de MAC, o servidor do portal regista o endereço MAC do dispositivo como um cliente autorizado, e o controlador permite-o. O bypass de MAC é mais simples de implementar, mas menos seguro, porque os endereços MAC podem ser falsificados. A plataforma de Wi-Fi de convidados da Purple lida com ambos os mecanismos. Após a conclusão do WeChat OAuth, a sobreposição na nuvem da Purple envia o sinal apropriado para o hardware subjacente – seja Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme ou Fortinet. O operador do espaço não necessita de gerir essa tradução manualmente. --- RECOMENDAÇÕES DE IMPLEMENTAÇÃO E ERROS COMUNS (aproximadamente 2 minutos) Deixe-me apresentar-lhe as cinco coisas que fazem falhar as implementações de Captive Portal com WeChat OAuth. Primeiro: a incompatibilidade do URI de redirecionamento. O WeChat valida o URI de redirecionamento face ao domínio autorizado que registou na plataforma. Se o servidor do seu portal utilizar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, o fluxo de OAuth falha com o erro 40029 – código inválido. Registe todas as variantes de domínio que utiliza, incluindo ambientes de teste (staging). Segundo: o App Secret no lado do cliente. O seu App Secret nunca deve aparecer no JavaScript do lado do cliente. O seu lugar é no servidor. Se for exposto, qualquer pessoa pode personificar a sua aplicação e fazer chamadas para as APIs do WeChat em seu nome. Terceiro: a falta de proteção CSRF. O parâmetro state no pedido de OAuth existe especificamente para evitar a falsificação de pedidos entre sites (cross-site request forgery). Gere um valor de state criptograficamente aleatório, armazene-o na sessão do utilizador e valide-o quando o WeChat redirecionar de volta. Ignore isto e terá uma vulnerabilidade real. Quarto: a falha na deteção do navegador na aplicação (in-app). O navegador na aplicação do WeChat define uma string de user agent específica que contém 'MicroMessenger'. Se o seu portal não detetar isto e não disponibilizar o fluxo de OAuth correto, os utilizadores terão uma experiência com falhas ou um erro. Quinto: o alinhamento com o GDPR e a PIPL. Se serve visitantes europeus, aplica-se o GDPR. Se serve visitantes chineses, aplica-se a Lei de Proteção de Informações Pessoais da China – PIPL. Ambas exigem uma base jurídica para o tratamento, limitação clara da finalidade e minimização de dados. O snsapi base é mais fácil de justificar ao abrigo dos princípios de minimização de dados do que o snsapi userinfo. Independentemente do que recolher, documente a sua base jurídica e o seu período de retenção. --- PERGUNTAS E RESPOSTAS RÁPIDAS (aproximadamente 1 minuto) Posso utilizar o início de sessão do WeChat num portal que também oferece início de sessão por e-mail e SMS? Sim. A maioria das plataformas de portal empresarial, incluindo a Purple, suporta múltiplos métodos de autenticação na mesma página do portal. O WeChat OAuth funciona no iOS? Sim. O início de sessão do WeChat no Safari no iOS funciona através do fluxo de código QR ou do fluxo de redirecionamento. A própria aplicação WeChat trata da autenticação. O que acontece se a API do WeChat estiver indisponível? Implemente uma alternativa (fallback). Se a chamada de API do WeChat expirar ou devolver um erro, redirecione o utilizador para um método de início de sessão alternativo. Posso utilizar o Open ID como um identificador de cliente persistente? Dentro da sua Conta Oficial (Official Account), sim. Para a resolução de identidade entre contas em múltiplas propriedades, utilize o UnionID em vez disso. --- RESUMO E PRÓXIMOS PASSOS (aproximadamente 1 minuto) Para resumir. A autenticação WeChat OAuth para Captive Portals é um exercício de registo em duas plataformas, uma decisão de âmbito (scope), uma integração de imposição de rede e uma revisão de conformidade. Acerte nestas quatro coisas e terá um método de início de sessão que serve mais de mil milhões de potenciais visitantes com zero atrito de palavra-passe. Os próximos passos práticos: determine se os seus visitantes encontram o portal dentro do navegador na aplicação (in-app) do WeChat ou num navegador móvel padrão. Decida sobre o âmbito – snsapi base para convidados frequentes, snsapi userinfo para o registo pela primeira vez com consentimento. Confirme que o seu hardware de rede suporta RADIUS CoA. Reveja o seu aviso de privacidade face ao GDPR e à PIPL. Teste o URI de redirecionamento, a validação do parâmetro state e a deteção do navegador na aplicação antes de avançar para o ambiente de produção (go-live). Se deseja ver como a Purple lida com o WeChat OAuth como parte de uma plataforma mais ampla de Wi-Fi de convidados e análise – em 80 000 espaços e 440 milhões de inícios de sessão em 2024 – visite purple.ai ou fale com a sua equipa de conta. Obrigado por ouvir. --- FIM DA APRESENTAÇÃO

header_image.png

Resumo executivo

Quando um visitante chinês se liga à sua rede empresarial e encontra um Captive Portal que oferece apenas e-mail, Facebook ou um código de voucher, introduz um atrito imediato. O WeChat tem 1,38 mil milhões de utilizadores ativos mensais, de acordo com os dados de 2024 da Tencent. Integrar capacidades de Wi-Fi de convidados com início de sessão WeChat não é uma conveniência de hotelaria – é um requisito técnico para recolher dados primários (first-party) deste grupo demográfico sem atrito.

Este guia detalha a arquitetura técnica para integrar a autenticação WeChat OAuth 2.0 em Captive Portals. Explica o registo em dupla plataforma necessário para suportar tanto os navegadores móveis padrão como o navegador na aplicação (in-app) do WeChat, avalia os compromissos entre os âmbitos (scopes) snsapi_base e snsapi_userinfo para a recolha de dados, e descreve como impor o acesso à rede utilizando RADIUS Change of Authorization (CoA) ou bypass de autenticação MAC. Também aborda as configurações de segurança e os mandatos de conformidade – GDPR e a PIPL da China – necessários para implementar isto em grande escala nas infraestruturas Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.


Análise técnica detalhada: arquitetura WeChat OAuth 2.0

Um Captive Portal interpeta o tráfego HTTP de um dispositivo não autenticado e redireciona-o para uma página de início de sessão alojada num servidor de portal. Adicionar a autenticação WeChat insere um fornecedor de identidade de terceiros neste fluxo utilizando o protocolo OAuth 2.0 – o mesmo padrão utilizado pela Google, Microsoft Entra ID e Okta para identidade federada.

oauth_flow_diagram.png

A sequência de autenticação funciona da seguinte forma. O convidado liga-se ao SSID. O ponto de acesso ou controlador sem fios deteta a sessão não autenticada e redireciona o tráfego HTTP para o URL do Captive Portal. O convidado seleciona o início de sessão do WeChat na página do portal. O servidor do portal redireciona o navegador para o endpoint de autorização do WeChat em open.weixin.qq.com, transmitindo o AppID, o URI de redirecionamento, o tipo de resposta code e o âmbito (scope) solicitado. O WeChat trata da autenticação nos seus próprios servidores. Se o convidado utilizar o navegador na aplicação (in-app) do WeChat com o âmbito snsapi_base, a autenticação é silenciosa – não surge qualquer pedido de consentimento. Se utilizar o snsapi_userinfo, o WeChat apresenta um ecrã de consentimento. O WeChat redireciona então de volta para o URI de redirecionamento do portal com um código de autorização temporário. O servidor do portal troca este código por um token de acesso chamando api.weixin.qq.com/sns/oauth2/access_token, transmitindo o AppID, AppSecret, o código e um tipo de concessão de authorization_code. O WeChat devolve um token de acesso, um token de atualização, o OpenID do utilizador e o âmbito concedido. Se o snsapi_userinfo tiver sido concedido, o servidor faz uma segunda chamada de API para obter o pseudónimo, o avatar, o género e a cidade do utilizador.

O requisito de registo em dupla plataforma

A maioria das implementações falha na fase de registo. O WeChat opera duas plataformas de programadores distintas e as implementações empresariais normalmente requerem ambas.

Plataforma URL Tipo de conta necessário Âmbito suportado Contexto do navegador
Official Accounts Platform mp.weixin.qq.com Conta de Serviço snsapi_base, snsapi_userinfo Navegador na aplicação do WeChat
Open Platform open.weixin.qq.com Aplicação Web snsapi_login Navegador móvel padrão

Para os convidados que acedem ao portal dentro do navegador na aplicação (in-app) do WeChat, necessita de uma Conta de Serviço (Service Account) na Official Accounts Platform. Uma Conta de Subscrição (Subscription Account) não funcionará – carece de permissões de autorização de páginas web OAuth. Para os convidados que acedem ao portal a partir do Chrome no Android ou Safari no iOS, necessita de uma Aplicação Web (Website Application) na Open Platform, que utiliza o âmbito snsapi_login e apresenta um código QR para o utilizador digitalizar.

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, digitalizá-lo com o WeChat e autenticar-se. Ou pode seguir uma ligação no próprio WeChat, aceder ao navegador na aplicação (in-app) e autenticar-se silenciosamente com o snsapi_base.

Seleção do âmbito (scope): recolha de dados vs. atrito

scope_comparison.png

O âmbito que solicita determina quais os dados que recolhe e o atrito que o convidado experimenta. Este é um verdadeiro ponto de decisão com implicações de conformidade.

snsapi_base devolve apenas o OpenID – um identificador exclusivo para esse utilizador dentro da sua Conta Oficial (Official Account). Não requer qualquer pedido de consentimento do utilizador. A autenticação é invisível para o convidado. Utilize isto para convidados frequentes cujos perfis já possui, ou quando prioriza o acesso sem atrito. Ao abrigo dos princípios de minimização de dados do GDPR e da PIPL, o snsapi_base é mais fácil de justificar.

snsapi_userinfo devolve o OpenID mais o pseudónimo, a imagem de perfil, o género e a cidade do utilizador. Requer um ecrã de consentimento explícito. Utilize isto para o registo de convidados pela primeira vez, quando necessita de criar um perfil, combinado com uma camada de consentimento em conformidade na página do seu portal.

UnionID para implementações em múltiplas propriedades

O OpenID é exclusivo da combinação de um utilizador e de uma Conta Oficial específica. Um grupo hoteleiro com 20 propriedades, cada uma com a sua própria Conta Oficial, verá 20 OpenIDs diferentes para o mesmo convidado. O UnionID resolve isto. É um identificador único que representa um utilizador em todas as Contas Oficiais e aplicações associadas à mesma conta da Open Platform. Associe as suas Contas Oficiais à sua conta da Open Platform e o UnionID será devolvido na resposta de OAuth. Esta é a base do crreconhecimento de hóspedes multi-propriedade.


Guia de implementação

Mecanismos de aplicação de rede

A obtenção de um token OAuth comprova a identidade. Não abre a rede. Deve sinalizar o controlador para permitir o tráfego.

RADIUS Change of Authorization (CoA), definido no RFC 3576, é a abordagem empresarial recomendada. Após um OAuth bem-sucedido, o servidor do portal envia um pedido de CoA para o controlador de rede. O controlador move o dispositivo da VLAN de pré-autenticação para a VLAN de convidados. Isto funciona com Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.

MAC Authentication Bypass (MAB) regista o endereço MAC do dispositivo como um cliente autorizado na base de dados RADIUS. O controlador permite o acesso com base nesse MAC. O MAB é mais simples de implementar, mas pouco fiável: os dispositivos iOS e Android modernos randomizam os endereços MAC por predefinição, quebrando a associação da sessão ao voltar a ligar.

A plataforma Guest WiFi da Purple automatiza esta tradução. Após a conclusão do OAuth do WeChat, a sobreposição de nuvem da Purple envia o sinal CoA ou MAB adequado para o hardware subjacente, eliminando a configuração manual de VLAN.

Configuração de segurança

Três configurações são não negociáveis.

  1. Proteger o AppSecret. O AppSecret nunca deve aparecer no JavaScript do lado do cliente. Deve permanecer no seu servidor. Se for exposto, os atacantes podem fazer-se passar pela sua aplicação e chamar as APIs do WeChat em seu nome.
  2. Implementar proteção CSRF. Gere um valor state criptograficamente aleatório, armazene-o na sessão do utilizador e valide-o quando o WeChat redirecionar de volta. Isto evita ataques de falsificação de pedidos entre sites (CSRF), conforme definido no RFC 6749.
  3. Registar todas as variantes de URI de redirecionamento. O WeChat valida o URI de redirecionamento em relação ao seu domínio registado. Registe todas as variantes de subdomínio e caminho que utiliza, incluindo ambientes de staging, para evitar o erro 40029 (código inválido).

Deteção de browser in-app

O browser in-app do WeChat define uma string de user agent que contém MicroMessenger. O seu portal deve detetar esta string e encaminhar em conformidade: fluxo de Conta Oficial para browser in-app, fluxo de código QR de Plataforma Aberta para browsers padrão. A falha na deteção disto resulta em experiências corrompidas ou erros de autenticação.

hotel_wechat_wifi.png


Melhores práticas e conformidade

Conformidade com o GDPR

Se serve visitantes europeus ou opera na Europa, o GDPR aplica-se aos dados que recolhe através do OAuth do WeChat. Deve estabelecer uma base legal para o processamento – normalmente consentimento ou interesses legítimos. Deve fornecer um aviso de privacidade claro no Captive Portal antes da autenticação. Deve respeitar os pedidos de acesso e de eliminação dos titulares dos dados. Para obter um enquadramento detalhado de conformidade, consulte O Manual de Conformidade: GDPR e Privacidade de Dados de Guest WiFi .

Conformidade com a PIPL

A Lei de Proteção de Informações Pessoais da China (PIPL) aplica-se quando processa dados pessoais de cidadãos chineses. Tal como o GDPR, a PIPL exige uma limitação clara da finalidade, minimização de dados e uma base legal documentada. O snsapi_base é mais fácil de justificar sob a minimização de dados do que o snsapi_userinfo. Independentemente do que recolher, documente a sua base legal e o período de retenção antes do lançamento.

Segmentação de rede

Isole o tráfego de Wi-Fi de convidados da sua rede corporativa utilizando a segmentação de VLAN. Os convidados autenticados através do WeChat devem aceder a uma VLAN de convidados dedicada apenas com acesso à Internet – sem acesso aos sistemas internos. Isto alinha-se com os requisitos do PCI DSS para isolamento do ambiente de dados de titulares de cartões e com as práticas gerais de segurança empresarial. Para saber mais sobre a arquitetura de segmentação, consulte Gestão de Largura de Banda: Um Guia Prático para 2026 .

Autenticação de recurso

Se a API do WeChat estiver indisponível, o seu portal deve redirecionar para um método de início de sessão alternativo. Não deixe os convidados com um ecrã em branco. Um recurso (fallback) para e-mail ou SMS garante a continuidade. Isto é particularmente importante para locais em ambientes de Transportes e Saúde onde a conectividade é uma obrigação de serviço.


Casos de estudo reais

Hotelaria: grupo de hotéis de luxo

Um hotel de luxo de 400 quartos em Londres serve uma proporção significativa de hóspedes da China continental. O seu Captive Portal existente exigia um endereço de e-mail e verificação por SMS. Os números de telemóvel chineses falham frequentemente na receção de SMS de fornecedores europeus, e muitos hóspedes não têm um e-mail local configurado no seu dispositivo. O resultado foi uma taxa de abandono de 60% no portal.

O hotel registou uma Conta de Serviço na Plataforma de Contas Oficiais e uma Aplicação Web na Plataforma Aberta. O portal deteta o user agent MicroMessenger e aciona o snsapi_base para utilizadores de browsers in-app – ligando-os em menos de três segundos sem ecrã de consentimento. Os hóspedes que chegam através do Chrome ou Safari veem um código QR. Em estadias subsequentes, o mesmo OpenID é reconhecido e o hóspede é autenticado novamente de forma silenciosa. O CRM do hotel regista a visita de retorno, permitindo comunicações direcionadas antes da chegada. Para saber mais sobre a implementação de WiFi em ambientes de hotelaria, consulte Hotelaria .

Retalho: análise de centros comerciais

Um grande centro comercial pretende recolher dados demográficos de compradores chineses para informar o mix de lojistas e as decisões de marketing. Precisam da cidade de origem, género e frequência de visitas. O snsapi_base é insuficiente – precisam do snsapi_userinfo. O portal solicita o âmbito completo de userinfo. O convidado vê um ecrã de consentimento do WeChat e toca em Permitir. A plataforma de analítica do centro comercial, integrada com o WiFi Analytics da Purple, recebe um fluxo de dados demográficos verificados. Aos sábados à tarde, 40% dos utilizadores de WiFi são originários de uma região específica. Esses dados diretamy informa quais as marcas a contactar para eventos pop-up. Para saber mais sobre implementações de WiFi no retalho, consulte Retalho .


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

Os cinco modos de falha mais comuns em implementações de Captive Portal WeChat OAuth são os seguintes.

Incompatibilidade de URI de redirecionamento (erro 40029). O WeChat valida o URI de redirecionamento em relação ao domínio registado. Qualquer incompatibilidade de subdomínio, caminho ou protocolo resulta na falha da troca de código. Registe todas as variantes, incluindo ambientes de staging.

Exposição do AppSecret. Incorporar o AppSecret no código do lado do cliente é o erro de segurança mais grave. Mova toda a lógica de troca de tokens para o servidor.

Falta de proteção CSRF. Omitir a validação do parâmetro state deixa o portal vulnerável a cross-site request forgery. Gere um valor criptograficamente aleatório por sessão e valide-o no callback.

Falha na deteção do browser in-app. Não detetar o MicroMessenger no user agent significa que os utilizadores do browser in-app recebem o fluxo OAuth incorreto, gerando erros.

A aleatorização do endereço MAC quebra as sessões MAB. Os sistemas operativos móveis modernos aleatorizam os endereços MAC. Os convidados que utilizam a aplicação baseada em MAB perderão a sessão ao voltarem a ligar-se. Atualize para RADIUS CoA para uma gestão de sessão fiável. Para obter orientações sobre a configuração segura de WiFi, consulte O que é WiFi Seguro: Guia Essencial para Empresas 2026 .


ROI e impacto no negócio

A implementação da funcionalidade de WiFi para convidados com início de sessão WeChat tem três impactos mensuráveis.

Aumento das taxas de autenticação. A eliminação do ponto de falha de verificação por SMS e do requisito de introdução de e-mail aumenta a percentagem de visitantes chineses que se ligam com sucesso. Uma taxa de abandono de 60% é uma base de referência realista para portais sem suporte para WeChat.

Qualidade dos dados primários (first-party). Os perfis autenticados pelo WeChat incluem um OpenID verificado e, com snsapi_userinfo, atributos demográficos obtidos diretamente da plataforma social. Estes dados alimentam as plataformas de analítica para direcionar o marketing direcionado sem depender de cookies de terceiros.

Redução dos custos de suporte. O início de sessão sem fricção reduz as chamadas de suporte da receção e de TI de convidados internacionais que tentam resolver problemas de ligação.

La Purple opera em mais de 80.000 locais e processou 440 milhões de inícios de sessão em 2024 (dados internos da Purple). A plataforma possui certificação ISO 27001, está em conformidade com o GDPR e CCPA, e mantém um tempo de atividade (uptime) de 99,999%. Para locais em Retalho e Hotelaria , a autenticação WeChat transforma a rede de um centro de custos num canal fiável de aquisição de dados primários.

Definições Principais

Captive portal

Uma página web que interpeta o tráfego HTTP de um dispositivo não autenticado e exige que o utilizador interaja com ela antes que o acesso à rede seja concedido.

A interface principal onde a opção de início de sessão do WeChat é apresentada ao convidado. O servidor do portal aloja esta página e orquestra o fluxo OAuth.

OAuth 2.0

Um protocolo de autorização padrão da indústria (RFC 6749) que permite a uma aplicação de terceiros obter acesso limitado a um serviço HTTP em nome de um utilizador.

O protocolo subjacente que o WeChat utiliza para transmitir tokens de autenticação para o servidor do portal sem expor as credenciais do utilizador. O mesmo protocolo utilizado pelo Microsoft Entra ID, Okta e Google Workspace.

OpenID

Um identificador alfanumérico exclusivo atribuído a um utilizador específico do WeChat para uma Conta Oficial específica.

Utilizado como a chave primária para identificar convidados que regressam na base de dados de análise de WiFi. Altera por Conta Oficial (Official Account) – utilize o UnionID para reconhecimento entre propriedades.

UnionID

Um identificador único do WeChat que representa um utilizador em todas as Contas Oficiais e aplicações associadas à mesma conta da Open Platform.

Essencial para grupos hoteleiros, cadeias de retalho e operadores de estádios com múltiplos espaços que necessitam de reconhecer o mesmo convidado em todo o seu património.

RADIUS CoA (Change of Authorization)

Uma extensão ao protocolo RADIUS (RFC 3576) que permite a um servidor RADIUS alterar dinamicamente os atributos de autorização de uma sessão ativa.

O método seguro utilizado para mover o dispositivo de um convidado de uma VLAN de pré-autenticação isolada para a VLAN de internet ativa após um início de sessão bem-sucedido no WeChat. Suportado por Cisco Meraki, HPE Aruba, Ruckus, Juniper Mist, Ubiquiti UniFi, Cambium, Extreme e Fortinet.

snsapi_base

Um âmbito (scope) de OAuth do WeChat que devolve apenas o OpenID do utilizador e não requer qualquer pedido de consentimento ao utilizador.

O âmbito (scope) recomendado para a reautenticação de convidados frequentes. Mais fácil de justificar ao abrigo dos princípios de minimização de dados do GDPR e da PIPL.

snsapi_userinfo

Um âmbito (scope) de OAuth do WeChat que devolve o OpenID, o pseudónimo, o avatar, o género e a cidade do utilizador, e exige um ecrã de consentimento explícito.

Utilizado para o registo de convidados pela primeira vez, quando são necessários dados demográficos para análise. Requer uma base jurídica documentada ao abrigo do GDPR e da PIPL.

PIPL (Personal Information Protection Law)

A legislação abrangente de privacidade de dados da China, em vigor desde novembro de 2021, que regula o tratamento de informações pessoais de pessoas singulares localizadas na China.

Aplica-se quando os espaços tratam dados de cidadãos chineses através do WeChat OAuth. Exige consentimento claro, limitação da finalidade, minimização de dados e um mecanismo de eliminação.

AppSecret

Uma chave criptográfica confidencial emitida pelo WeChat durante o registo da aplicação, utilizada para autenticar chamadas de API a partir do servidor do portal.

Deve ser armazenado exclusivamente no lado do servidor. A exposição em JavaScript do lado do cliente permite que atacantes personifiquem a aplicação e façam chamadas maliciosas para as APIs do WeChat.

Exemplos Práticos

Um hotel de luxo com 400 quartos em Londres tem uma taxa de abandono do portal de 60% entre os hóspedes da China continental. O portal atual exige verificação por e-mail e SMS. O Diretor de TI precisa de implementar a autenticação WeChat, mantendo a conformidade com o GDPR e a segurança da rede.

Passo 1: Registar uma Conta de Serviço (Service Account) na WeChat Official Accounts Platform (mp.weixin.qq.com) e uma Aplicação Web (Website Application) na WeChat Open Platform (open.weixin.qq.com). Passo 2: Configurar o portal para detetar a string de user agent do MicroMessenger. Se for detetada, acionar o fluxo OAuth snsapi_base para autenticação silenciosa. Se não for detetada, apresentar o fluxo de código QR. Passo 3: Adicionar um aviso de privacidade em conformidade com o GDPR e uma caixa de seleção de consentimento à página do portal antes que o botão de início de sessão do WeChat fique ativo. O aviso deve indicar: dados recolhidos (apenas OpenID), finalidade (acesso ao Wi-Fi de convidados e reconhecimento de visitas de retorno) e período de retenção. Passo 4: Após a troca bem-sucedida do token OAuth, o servidor do portal emite um pedido RADIUS CoA para o controlador Cisco Meraki, movendo o dispositivo do convidado da VLAN de pré-autenticação para a VLAN de convidados segmentada. Passo 5: Armazenar o OpenID associado ao endereço MAC do dispositivo na base de dados de convidados. Nas visitas subsequentes, o OpenID de retorno aciona a reautenticação silenciosa.

Comentário do Examinador: Esta abordagem aborda corretamente os requisitos técnicos e de conformidade. A utilização do snsapi_base alinha-se com os princípios de minimização de dados do GDPR, reduzindo o risco jurídico e eliminando o ponto de falha da verificação por SMS. O RADIUS CoA garante uma segmentação de rede segura e automatizada. A caixa de seleção de consentimento cumpre o requisito do GDPR de uma base jurídica documentada. A decisão fundamental é a escolha do snsapi_base em detrimento do snsapi_userinfo – o hotel não necessita de dados demográficos para este caso de utilização, pelo que a sua recolha introduziria obrigações de conformidade desnecessárias.

Um centro comercial pretende recolher dados de género e cidade de compradores chineses através do Wi-Fi de convidados para alimentar a sua plataforma de análise. Atualmente, utilizam o MAC Authentication Bypass para o seu portal existente, que corre em hardware HPE Aruba.

Passo 1: Registar uma Conta de Serviço na WeChat Official Accounts Platform. Passo 2: Configurar o portal para utilizar o âmbito (scope) snsapi_userinfo para obter o género e a cidade. Passo 3: Adicionar um ecrã de consentimento claro que explique a troca de valor: Wi-Fi gratuito em troca do acesso aos dados do perfil. O consentimento deve ser explícito e granular ao abrigo do GDPR e da PIPL. Passo 4: Após a autenticação, o servidor do portal regista o endereço MAC do dispositivo na base de dados RADIUS. O controlador HPE Aruba permite o acesso via MAB. Passo 5: Documentar a base jurídica (consentimento), a finalidade (análise do espaço e marketing) e o período de retenção (24 meses) num registo de tratamento de dados. Disponibilizar um mecanismo de eliminação de dados.

Comentário do Examinador: O âmbito snsapi_userinfo obtém corretamente os dados demográficos necessários. No entanto, a dependência do MAB introduz um risco operacional significativo: o iOS 14+ e o Android 10+ randomizam os endereços MAC por predefinição, o que significa que os convidados perderão a sua sessão autenticada ao voltarem a ligar-se e serão forçados a reautenticar-se. O centro comercial deve planear a migração para RADIUS CoA em HPE Aruba para resolver este problema. A documentação de conformidade com a PIPL não é opcional – é um requisito legal para o tratamento de dados de cidadãos chineses, independentemente de onde o espaço esteja localizado.

Perguntas de Prática

Q1. Está a implementar um Captive Portal num estádio. Pretende que os detentores de bilhetes de época frequentes que já se tenham autenticado anteriormente se liguem automaticamente sem verem um ecrã de início de sessão nas visitas subsequentes. Qual o âmbito (scope) de OAuth do WeChat que deve implementar para o fluxo de reautenticação e porquê?

Dica: Considere qual o âmbito (scope) que permite a autenticação silenciosa sem solicitar o consentimento do utilizador em cada visita.

Ver resposta modelo

Utilize o snsapi_base. Este âmbito (scope) devolve apenas o OpenID do utilizador e não requer qualquer pedido de consentimento, permitindo a reautenticação silenciosa. Na primeira visita, armazena o OpenID no perfil do adepto. Nas visitas subsequentes, o portal deteta o OpenID de retorno via snsapi_base, confirma a correspondência e emite um RADIUS CoA para conceder o acesso – tudo sem que o adepto veja um ecrã de início de sessão. Isto também se alinha com os princípios de minimização de dados do GDPR, uma vez que não está a recolher dados adicionais para além do necessário para a função de autenticação.

Q2. Durante os testes, o seu portal redireciona com sucesso para o WeChat, o utilizador concede o consentimento e o WeChat redireciona de volta para o seu portal. No entanto, os registos do servidor do portal mostram o erro de OAuth 40029 (código inválido). Qual é o erro de configuração mais provável e como o resolve?

Dica: O WeChat valida rigorosamente o destino para onde envia o código de autorização face a uma lista registada.

Ver resposta modelo

A causa mais provável é uma incompatibilidade do URI de redirecionamento. O WeChat valida o URI de redirecionamento no pedido de OAuth face ao domínio autorizado registado na plataforma. Se o servidor do portal utilizar um subdomínio diferente, um caminho diferente ou HTTP em vez de HTTPS, a troca de código falha com o erro 40029. Resolução: inicie sessão na plataforma de programadores do WeChat, navegue até às definições da sua Conta de Serviço (Service Account) ou Aplicação Web (Website Application) e adicione todas as variantes de URI de redirecionamento que utiliza – incluindo subdomínios de teste (staging), caminhos diferentes e versões HTTPS. Certifique-se de que o parâmetro redirect_uri no seu pedido de OAuth corresponde exatamente a um dos URIs registados, incluindo a codificação de URL.

Q3. Um gestor de TI propõe incorporar o AppSecret do WeChat no JavaScript de front-end do Captive Portal para acelerar o processo de troca de tokens diretamente a partir do navegador do cliente. Por que razão deve rejeitar esta proposta e qual é a arquitetura correta?

Dica: Considere as implicações de segurança de expor chaves criptográficas em código acessível publicamente.

Ver resposta modelo

Rejeite esta proposta. O AppSecret é uma chave criptográfica confidencial. Incorporá-lo em 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. Um atacante pode extrair o AppSecret e personificar a aplicação, fazendo chamadas para as APIs do WeChat em nome do espaço, acedendo aos dados dos utilizadores e potencialmente comprometendo toda a Conta Oficial (Official Account). A arquitetura correta: a página do portal do lado do cliente recebe o código de autorização do WeChat e encaminha-o para o servidor do portal através de uma chamada de API do lado do servidor. O servidor do portal guarda o AppSecret numa variável de ambiente segura e realiza a troca de tokens com a API do WeChat. O AppSecret nunca sai do servidor.

Q4. Um grupo hoteleiro com 15 propriedades na Europa pretende criar um perfil de convidado unificado que reconheça quando o mesmo hóspede chinês fica alojado em propriedades diferentes. Cada propriedade tem a sua própria Conta Oficial (Official Account) do WeChat. Que identificador do WeChat devem utilizar e que configuração é necessária?

Dica: O OpenID é específico da conta. Existe um identificador diferente concebido para o reconhecimento entre contas.

Ver resposta modelo

Utilize o UnionID. O OpenID muda por Conta Oficial (Official Account), pelo que o mesmo convidado terá 15 OpenIDs diferentes em 15 contas. O UnionID é um identificador estável que representa um utilizador em todas as Contas Oficiais e aplicações associadas à mesma conta da Open Platform. Configuração necessária: associar as 15 Contas Oficiais a uma única conta da WeChat Open Platform. Uma vez associadas, o UnionID é devolvido na resposta de OAuth quando o utilizador tiver autorizado pelo menos uma das contas associadas. Utilize o UnionID como chave primária no CRM de convidados para criar perfis entre propriedades e reconhecer convidados frequentes, independentemente da propriedade que visitem.

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 cloud utilizando equipamento de encaminhamento empresarial. Irá aprender a superar 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.

Ler o guia →

Hotel Guest WiFi Management: Integrating PMS, Portals, and Brand Standards

Este guia técnico detalha como arquitetar redes WiFi de hotéis de nível empresarial, focando-se na segmentação de VLAN, integração de PMS para gestão automatizada de sessões e otimização de captive portal para captura de dados em conformidade com o GDPR.

Ler o guia →

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 um plano completo para implementar captive portals que equilibram a segurança da 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. Baseado na experiência operacional da Purple em mais de 80.000 espaços e 440 milhões de inícios de sessão em 2024, cada recomendação é fundamentada em dados reais de implementação.

Ler o guia →
Integrar a Autenticação WeChat com Captive Portals de Wi-Fi de Convidados | Guias Técnicos | Purple