Como utilizar a Edge Function ALTCHA através do Marketplace da Azion

A Edge Function ALTCHA da Azion é uma integração serverless, oferecida através do Marketplace da Azion.

A solução oferece uma camada de segurança avançada, protegendo suas aplicações web contra bots, spam e atividades maliciosas, com baixo impacto na experiência do usuário final.

Diferente dos sistemas CAPTCHA tradicionais, o ALTCHA é uma alternativa gratuita, moderna e open-source, executada diretamente no edge da rede, garantindo performance otimizada e latência mínima, de baixo custo.

As principais características da Edge Function ALTCHA incluem:

• Proteção nativa no edge: A verificação é processada nos data centers distribuídos da Azion, com as ameaças mitigadas o mais próximo possível do usuário.
• Open-source: Sua natureza transparente e auditável oferece maior confiança e flexibilidade para desenvolvedores.
• Sem dependências externas: Funciona independentemente de serviços de terceiros, operando dentro da infraestrutura da Azion.
• Performance otimizada: O processamento distribuído no edge assegura verificação instantânea com consumo mínimo de recursos, e latência ultrabaixa.
• Integração nativa: Como uma Edge Function da Azion, o ALTCHA se integra perfeitamente ao seu fluxo de trabalho e à sua arquitetura de segurança existente no Edge Firewall.

Vantagens sobre CAPTCHAs tradicionais:

• Acessibilidade: É compatível com leitores de tela e outras tecnologias assistivas, para que todos os usuários interajam com suas aplicações.
• Privacidade: Não coleta dados pessoais dos usuários, respeitando a privacidade e as regulamentações de proteção de dados.
• Eficiência: A verificação é instantânea e consome recursos mínimos, otimizando a performance geral da sua aplicação.

Como funciona

O objetivo principal do ALTCHA é assegurar que apenas usuários com comportamento humano legítimo sejam autenticados e consigam acessar suas aplicações, enquanto bots e tráfego malicioso são bloqueados. Isso visa manter um alto nível de segurança digital com impacto mínimo na performance e na usabilidade.

A função ALTCHA cria dois endpoints especiais em sua aplicação para gerenciar o fluxo de verificação:

• /az-request-verify: É o endpoint que exibe o desafio CAPTCHA e para onde os usuários devem ser redirecionados sempre que precisarem resolver um destes desafios. Ao acessá-lo, um novo desafio CAPTCHA será retornado ao usuário para verificação.
• /az-request-captcha: Após o usuário resolver o desafio com sucesso, o script ALTCHA executa automaticamente uma chamada para este endpoint para validar a solução. Se a validação for bem-sucedida, o script ALTCHA define um cookie de sessão no navegador do usuário, permitindo que requisições futuras sejam verificadas automaticamente, sem a necessidade de novos desafios.

Fluxo de funcionamento:

1. O usuário acessa um endpoint protegido em sua aplicação.
2. O sistema de segurança redireciona o usuário para o endpoint /az-request-verify.
3. O desafio CAPTCHA é exibido ao usuário.
4. Após a resolução do desafio, o ALTCHA define cookies de sessão no navegador do usuário.
5. Requisições futuras do mesmo usuário são validadas automaticamente por meio dos cookies de sessão, sem a necessidade de resolver novos desafios.

Configuração do desafio ALTCHA

Configure uma regra dentro do Edge Firewall

ALTCHA é um integração que funciona no Edge Firewall. Para ativá-la, você precisa primeiro criar uma regra no Edge Firewall. Para isso, siga os próximos passos:

1. Acesse o Azion Console > Edge Firewall.
2. Clique no botão + Edge Firewall.
3. Escolha um nome fácil de lembrar para o seu edge firewall.
4. Ative o switch de Edge Functions.
5. Clique no botão Save.

Instancie a integração

Para instanciar a edge function, ainda na página do Edge Firewall:

1. Vá até a aba Functions Instances e siga estes passos:
2. Clique no botão + Function Instance.
3. Escolha um nome fácil de lembrar para a sua instância.
4. No menu suspenso, selecione ALTCHA.

• Esta ação irá carregar a aba Arguments.

5. Na aba Arguments, você passará os parâmetros.
6. Clique no botão Save

Pronto. Agora você tem a sua Edge Function ALTCHA devidamente configurada.

Crie uma regra dentro do Rules Engine

Para finalizar, você deve configurar o Rules Engine para definir o comportamento e os critérios para executar o ALTCHA, via Bot Manager ou independentemente com Edge Firewall.

Bot Manager

1. Em Edge Firewall, selecione Rules Engine.
2. Clique no botão + Rules Engine para criar uma Rule para executar a função ALTCHA.
3. Na seção Name, insira um nome único e descritivo.
4. Na seção Criteria, defina quando apresentar o desafio.

• No JSON Args do Bot Manager, defina a ação de redirecionamento para o endpoint de verificação do ALTCHA para que o tráfego classificado como suspeito seja enviado para a página de desafio do ALTCHA.
• Alinhe os mesmos critérios de triggers das duas funções e use ALTCHA e Bot Manager no Rules Engine. Isso assegura que as duas soluções atuem sobre o mesmo conjunto de requisições e que o ALTCHA esteja sempre pronto para receber o redirecionamento do Bot Manager.

5. Defina a execução do ALTCHA sempre que uma Request Uri usar o endpoint /form, /az-request-verify e /az-request-captcha.
6. Na seção Behavior, selecione Run Function > ALTCHA.
7. Mantenha o botão Status como Active. ​​8. Clique no botão Save.

Independentemente com Edge Firewall

1. Em Edge Firewall, selecione Rules Engine.
2. Clique no botão + Rules Engine para criar uma Rule para executar a função ALTCHA.
3. Na seção Name, insira um nome único e descritivo.
4. Na seção Criteria, defina quando apresentar o desafio.

• O header X-Azcaptcha-Success indica que o desafio ALTCHA foi resolvido corretamente.

5. Defina a execução do ALTCHA sempre que uma Request Uri usar o endpoint /form, /az-request-verify e /az-request-captcha.

• Quando a requisição for para /form e o header X-Azcaptcha-Success não existir, o redirecionamento para /az-request-verify iniciará o fluxo do desafio.

6. Na seção Behavior, selecione Run Function > ALTCHA.
7. Mantenha o botão Status como Active.
8. Clique no botão Save.

JSON Args

A função ALTCHA aceita os seguintes argumentos de configuração no formato JSON.

[{
"cookie_secret": "string",
"cookie_max_age": 86400,
"status_code": 200,
"captcha_localization": {
"error": "Mensagem de erro personalizada",
"label": "Texto do widget",
"verifying": "Verificando...",
"verified": "Verificado!"
},
"captcha_colors": {
"base": "#ffffff",
"border": "#cccccc",
"border_focus": "#007bff",
"text": "#333333",
"error_text": "#dc3545"
},
"custom_html": "HTML personalizado"
}]

Parâmetros de Configuração

A tabela a seguir detalha cada um dos parâmetros de configuração disponíveis para a Edge Function ALTCHA:

Limitações

Ao usar a Edge Function ALTCHA, é importante estar ciente de algumas limitações para garantir a correta implementação e funcionamento:

• HTTPS obrigatório: ALTCHA requer HTTPS devido ao uso da Web Crypto API.
• URLs completas: Parâmetros de redirecionamento devem incluir esquema e hostname.
• Endpoints fixos: Os endpoints /az-request-verify e /az-request-captcha são reservados, ou seja, devem ser usados exclusivamente para o controle de execução da Edge Function do ALTCHA. Isso garante que sua aplicação não utilize urls com estes termos.

Headers de controle

A função ALTCHA define headers HTTP específicos para controlar o fluxo e indicar o status da verificação. Estes headers são úteis para depuração e para a lógica da sua aplicação:

• X-AZCAPTCHA-SUCCESS: true: Indica que o usuário resolveu o desafio corretamente.
• X-AZCAPTCHA-VIOLATION: true: Sinaliza que uma tentativa de burlar o sistema foi detectada.

Cookies de sessão

O sistema ALTCHA utiliza dois cookies para gerenciar o estado da sessão de verificação:

1. az_\${FUNCTION_VERSION}_verify_payload: Contém os dados brutos da resolução do desafio.
2. az_\${FUNCTION_VERSION}_verify_session: É o cookie de sessão assinado, utilizado para validar requisições futuras sem a necessidade de um novo desafio.

Personalização

A Edge Function ALTCHA oferece diversas opções de personalização para que você possa adaptar a experiência do desafio à identidade visual e às necessidades da sua aplicação.

HTML Personalizado

É possível personalizar completamente a página onde o desafio ALTCHA é exibido, utilizando seu próprio código HTML. Isso permite que você mantenha a consistência do design e da marca da sua aplicação.

{
"custom_html": "<!DOCTYPE html><html><head><title>Verificação</title></head><body><h1>Complete o desafio</h1>{/* azion_captcha */}</body></html>"
}

Localização

Para oferecer uma experiência global e acessível, você pode personalizar as mensagens exibidas no widget ALTCHA para diferentes idiomas. Isso é feito através do parâmetro captcha_localization.

{
"captcha_localization": {
"error": "Erro na verificação. Tente novamente.",
"label": "Verificar que você é humano",
"verifying": "Verificando...",
"verified": "Verificado com sucesso!"
}
}

Boas práticas

Para garantir a máxima eficácia e otimizar o uso da Edge Function ALTCHA, siga estas boas práticas:

1. Ordem de execução: Sempre configure o ALTCHA para executar antes do Bot Manager no Rules Engine para que o desafio humano seja resolvido antes que as regras de Bot Manager sejam aplicadas, otimizando o fluxo de segurança.
2. URLs completas: Use URLs completas (incluindo esquema e hostname) nos parâmetros de redirecionamento para evitar problemas de resolução e garantir que os usuários sejam direcionados corretamente.
3. TTL apropriado para cookies: Configure um cookie_max_age (TTL - Time To Live) apropriado para os cookies de sessão, baseado nas necessidades de segurança e usabilidade da sua aplicação. Um TTL muito curto pode gerar desafios frequentes, já um muito longo pode comprometer a segurança.
4. Personalização da experiência: Aproveite as opções de custom_html e captcha_colors para personalizar a página do desafio e o widget ALTCHA com a identidade visual da sua empresa e ter uma experiência de usuário consistente.
5. Monitoramento de logs: Facilita a identificação de tentativas de bypass ou atividades suspeitas para respostas rápidas a novas ameaças e ajustes na configuração.

Exemplo prático

Considere que possuímos uma aplicação em que queremos proteger a rota /api/submit. Para isto, será necessário:

Edge Firewall Rules Engine

Configure as seguintes regras no Rules Engine do seu Edge Firewall:

Rule 1: ALTCHA Setup
- Criteria: Request URI matches `/api/submit` OR Request URI matches `/az-request-verify` OR Request URI matches `/az-request-captcha`
- Behavior: Run Function "ALTCHA"

Rule 2: Bot Manager
- Criteria: Request URI matches `/api/submit`
- Behavior: Run Function "Bot Manager"

ALTCHA JSON Args

Esta configuração garante que todos os acessos ao endpoint /api/submit passam pela verificação ALTCHA antes da análise do Bot Manager, oferecendo múltiplas camadas de proteção.

Configure os parâmetros da sua instância ALTCHA conforme a necessidade. Exemplo:

{
"cookie_max_age": 1800,
"captcha_localization": {
"label": "Verificar que você é humano"
},
"captcha_colors": {
"base": "#f8f9fa",
"border": "#dee2e6",
"text": "#495057"
}
}

ALTCHA Redirect - Versão 1.2.0

Com o objetivo de aprimorar continuamente a postura de segurança e a funcionalidade da Edge Function ALTCHA, lançamos a versão 1.2.0 do ALTCHA Redirect. Leia o Release Notes para saber mais.

Informações importantes para usuários existentes de ALTCHA Redirect

• Atualize suas instâncias da Edge Function ALTCHA redirect e configure o parâmetro de domínios permitidos para proteger seus usuários contra Open Redirect.
• Com o novo parâmetro de JSON Args allowed_domains, é possível definir para quais domínios a função deve permitir redirecionamentos.