--- name: azion-proteja-uma-rota-com-um-desafio-altcha description: >- Execute o desafio ALTCHA em um firewall e adicione a regra da aplicação que envia as requisições não verificadas para ele. --- # Proteja uma rota com um desafio ALTCHA ALTCHA é uma alternativa de CAPTCHA *open-source* que mantém bots e spam fora de uma rota protegida. Ele responde a uma requisição com um desafio de prova de trabalho e é executado como uma função em um firewall. Uma regra na aplicação envia as requisições não verificadas para o desafio. Todos os passos são executados em Azion Console. A função adiciona dois endpoints à aplicação. O endpoint `/az-request-verify` retorna a página do desafio e o endpoint `/az-request-captcha` valida a solução. Um navegador que resolve o desafio recebe um cookie de sessão, então as requisições seguintes passam sem um novo desafio. ALTCHA é executado dentro da infraestrutura da Azion e não chama nenhum serviço de terceiros. Ele não coleta dados pessoais e o widget funciona com leitores de tela e outras tecnologias assistivas. Para executar ALTCHA como destino de redirecionamento de Bot Manager, consulte [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas/#bot-manager). --- ## Pré-requisitos - Uma conta Azion. Para criar uma, consulte [Como criar uma conta na Azion](/pt-br/documentacao/fundamentos/criar-uma-conta/). - A função ALTCHA na sua conta. ALTCHA é uma integração do Azion Marketplace. Para instalá-la, consulte [Como instalar uma integração](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/integracoes/instalar-uma-integracao/). - A permissão **Edit Firewall** na conta. Ela concede permissão para visualizar, criar, editar e remover um firewall, e também requer a permissão **View Firewall**. - A permissão **Edit Applications** na conta. A regra de redirecionamento altera uma aplicação, e essa permissão também requer a permissão **View Applications**. Consulte [Teams Permissions](/pt-br/documentacao/fundamentos/teams-permissions/). - Uma aplicação e a rota que o desafio protege. Os exemplos usam `/form` como essa rota. > **Atenção** > > O tempo de computação e as invocações de funções geram custos de uso. Para as tarifas, consulte [Preços](/pt-br/documentacao/fundamentos/precos/). --- ## Crie o firewall ALTCHA é executado em um firewall com o módulo **Functions** ativado. Para criar o firewall: 1. **Abra a página Firewall** Acesse [Azion Console](https://console.azion.com/) > **Firewall**. 2. **Selecione + Firewall** 3. **Nomeie o firewall** Digite um nome para o firewall. Por exemplo: `altcha firewall`. 4. **Ative o módulo Functions** 5. **Selecione Save** O firewall é salvo e as abas **Functions Instances** e **Rules Engine** ficam disponíveis na mesma página. > **nota** > > Para usar um firewall que já existe, abra-o e ative o módulo **Functions** na aba **Main Settings**. --- ## Instancie a função ALTCHA Uma instância de função vincula ALTCHA a um firewall e carrega a configuração dele. Para criar a instância: 1. **Vá para a aba Functions Instances** No firewall que você criou, vá para a aba **Functions Instances**. 2. **Selecione + Function Instance** 3. **Nomeie a instância** Digite um nome para a instância. Por exemplo: `altcha instance`. 4. **Selecione a função ALTCHA** Na lista de funções, selecione **ALTCHA**. A aba **Arguments** é carregada. 5. **Digite os argumentos** (Opcional) Na aba **Arguments**, digite a configuração em JSON. Todos os parâmetros são opcionais e a função usa o valor padrão de cada parâmetro que você omitir. Por exemplo: ```json { "cookie_max_age": 1800, "captcha_localization": { "label": "Verifique que você é humano" }, "captcha_colors": { "base": "#f8f9fa", "border": "#dee2e6", "text": "#495057" } } ``` Para cada parâmetro que a função aceita, consulte [Parâmetros de configuração](#parametros-de-configuracao). 6. **Selecione Save** A instância aparece na aba **Functions Instances**. Ela não é executada até que uma regra do Rules Engine a selecione. --- ## Adicione a regra do firewall que executa ALTCHA Uma regra do [Rules Engine](/pt-br/documentacao/plataforma/firewall/rules-engine/) define quando o firewall executa ALTCHA. Os critérios cobrem a rota protegida e os dois endpoints de ALTCHA. Para adicionar a regra: 1. **Vá para a aba Rules Engine** No mesmo firewall, vá para a aba **Rules Engine**. 2. **Selecione + Rules Engine** 3. **Nomeie a regra** Digite um nome único e descritivo. Por exemplo: `Run ALTCHA`. 4. **Defina os critérios** Na seção **Criteria**, compare a **Request URI** com `/form`, `/az-request-verify` e `/az-request-captcha`. Substitua `/form` pela rota que o desafio protege, como `/api/submit`. 5. **Selecione o comportamento** Na seção **Behavior**, selecione **Run Function** e, em seguida, a instância de ALTCHA. 6. **Mantenha Status como Active** 7. **Selecione Save** O firewall executa ALTCHA em toda requisição cuja URI corresponde aos critérios. As alterações podem levar alguns minutos para se propagar. --- ## Adicione a regra da aplicação que inicia o desafio A aplicação inicia o fluxo. Uma requisição para a rota protegida sem o header `X-Azcaptcha-Success` vai para `/az-request-verify`. Para adicionar a regra no [Rules Engine](/pt-br/documentacao/plataforma/applications/rules-engine/) da aplicação: 1. **Abra a aplicação** Em Azion Console, vá para **Applications** e selecione a aplicação que o desafio protege. 2. **Vá para a aba Rules Engine** 3. **Selecione + Rule** 4. **Nomeie a regra** Digite um nome único e descritivo. Por exemplo: `Start ALTCHA challenge`. 5. **Selecione a fase de request** Defina **Phase** como *Request*. 6. **Adicione o primeiro critério** Na seção **Criteria**, selecione a variável `${http_X_Azcaptcha_Success}` e o operador `does not exist`. 7. **Adicione o segundo critério** Selecione a variável `${uri}`, o operador `is equal` e `/form` como valor. 8. **Defina o comportamento de redirecionamento** Na seção **Behavior**, selecione **Redirect To (302 Found)** e digite `/az-request-verify` como destino. 9. **Mantenha Status como Active** 10. **Selecione Save** Uma requisição para `/form` sem um cookie de sessão válido agora vai para a página do desafio ALTCHA. O fluxo de verificação começa ali. --- ## Personalize a página do desafio Por padrão, ALTCHA entrega uma página branca que contém o widget. Três parâmetros alteram essa página: `custom_html` substitui a página, `captcha_colors` define as cores do widget e `captcha_localization` define o texto dele. Para substituir a página, defina `custom_html` na aba **Arguments** da instância: ```json { "custom_html": "Verificação

Complete o desafio

{/* azion_captcha */}" } ``` > **dica** > > Inclua o marcador `{/* azion_captcha */}` no HTML. Ele define onde a função insere o widget ALTCHA. Sem o marcador, o widget vai para o final do corpo do HTML. Para exibir as mensagens do widget no idioma dos seus usuários, defina `captcha_localization`: ```json { "captcha_localization": { "error": "Erro na verificação. Tente novamente.", "label": "Verifique que você é humano", "verifying": "Verificando...", "verified": "Verificado com sucesso!" } } ``` --- ## Parâmetros de configuração A aba **Arguments** da instância recebe um objeto JSON. Todos os parâmetros são opcionais: ```json { "allowed_domains": ["my-website.azion.app", "third-party.azion.app"], "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" } ``` Cada parâmetro, o tipo dele e o valor padrão: | Parâmetro | Tipo | Valor padrão | Descrição | | -------------------------------- | ---------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowed_domains` | Array de strings | `${host}` | Define para quais domínios a função permite redirecionamentos. O host da aplicação e os redirecionamentos relativos são sempre permitidos. Em um valor inválido, a função ignora o parâmetro e registra um aviso em [Real-Time Events](/pt-br/documentacao/plataforma/real-time-events/) | | `captcha_colors` | Objeto | Nenhum | Define as cores do widget ALTCHA | | `captcha_colors.base` | String | Definido por ALTCHA | Cor base do widget ALTCHA, no formato de tripleto hexadecimal | | `captcha_colors.border` | String | Definido por ALTCHA | Cor da borda do widget ALTCHA, no formato de tripleto hexadecimal | | `captcha_colors.border_focus` | String | Definido por ALTCHA | Cor da borda do widget ALTCHA enquanto ele está em foco, no formato de tripleto hexadecimal | | `captcha_colors.error_text` | String | Definido por ALTCHA | Cor das mensagens de erro do widget ALTCHA, no formato de tripleto hexadecimal | | `captcha_colors.text` | String | Definido por ALTCHA | Cor do texto do widget ALTCHA, no formato de tripleto hexadecimal | | `captcha_localization` | Objeto | Nenhum | Define as strings que o widget ALTCHA exibe | | `captcha_localization.error` | String | Definido por ALTCHA | Mensagem exibida quando ocorre um erro enquanto o usuário resolve o desafio | | `captcha_localization.label` | String | Definido por ALTCHA | Mensagem exibida ao lado da caixa de seleção que o usuário marca | | `captcha_localization.verified` | String | Definido por ALTCHA | Mensagem exibida depois que o widget identifica uma solução correta. O script redireciona o usuário quando a solução está correta, então a maioria dos usuários nunca a vê | | `captcha_localization.verifying` | String | Definido por ALTCHA | Mensagem exibida enquanto o script verifica a solução | | `cookie_max_age` | Integer | `86400` | Define a idade máxima do cookie de sessão. Um valor curto gera desafios frequentes e um valor longo reduz a segurança | | `cookie_secret` | String | `@z10N!${FUNCTION_VERSION}` | Chave secreta que assina o cookie de sessão | | `custom_html` | String | Uma página branca que contém o widget ALTCHA | Substitui o layout da página do desafio. A função insere o widget na tag `{/* azion_captcha */}` ou no final do corpo do HTML quando a tag não existe | | `status_code` | Integer | `200` | Define o código de status da resposta da página do desafio. Em um valor inválido, ou em um código de status que não permite corpo de resposta como 101, 204, 205 ou 304, a função usa `200` | > **Atenção** > > Configure `allowed_domains` em toda instância de ALTCHA Redirect. O parâmetro define para quais domínios a função permite redirecionamentos e protege os usuários contra open redirects. Para a versão que introduziu o parâmetro, consulte [Release notes](/pt-br/documentacao/changelog/). --- ## Headers de controle e cookies de sessão ALTCHA define headers HTTP que carregam o estado da verificação. Use esses headers para depurar o fluxo e para orientar a lógica da sua aplicação. | Header | Descrição | | ----------------------------- | --------------------------------------------------- | | `X-Azcaptcha-Success: true` | O usuário resolveu o desafio | | `X-Azcaptcha-Violation: true` | A função detectou uma tentativa de burlar o desafio | ALTCHA também define dois cookies que guardam o estado da sessão de verificação. | Cookie | Descrição | | --------------------------------------- | ----------------------------------------------------------------------------------- | | `az_${FUNCTION_VERSION}_verify_payload` | Os dados brutos da solução do desafio | | `az_${FUNCTION_VERSION}_verify_session` | O cookie de sessão assinado que valida as requisições seguintes sem um novo desafio | Monitore os logs da função em [Real-Time Events](/pt-br/documentacao/plataforma/real-time-events/) para identificar tentativas de burlar o desafio e ajuste a configuração conforme os logs mostram. --- ## Limitações - **HTTPS**: ALTCHA usa a Web Crypto API e essa API funciona apenas sobre HTTPS. - **URLs completas**: um parâmetro de redirecionamento carrega o esquema e o hostname. - **Endpoints reservados**: `/az-request-verify` e `/az-request-captcha` atendem apenas ALTCHA. A aplicação não deve usar uma URL que carregue qualquer um desses termos. --- ## Próximos passos - [Execute uma função em um firewall](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/functions-e-runtime/firewall.md): Escreva a sua própria função de firewall, instancie-a e adicione a regra que a aciona. - [Instancie uma função em um firewall](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/instanciar-functions.md): Crie a mesma instância pela Azion API e passe os Args dela em JSON. - [Rules Engine para Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine.md): Todas as variáveis de critério, operadores de comparação e comportamentos que uma regra de firewall aceita. - [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas.md#bot-manager): Envie o tráfego classificado como suspeito para a página do desafio ALTCHA. - [Bloquear account takeover em fluxos de login e checkout](/pt-br/documentacao/casos-de-uso/proteger-aplicacoes-e-redes/bloquear-account-takeover-em-fluxos-de-login-e-checkout.md): Um design em que o Bot Manager envia a este desafio os clientes sinalizados no login e no cadastro.