--- name: azion-instale-a-integracao-recaptcha description: >- Instale reCAPTCHA pelo Azion Marketplace e execute o desafio em um firewall, para que bots e spam não cheguem à sua origem. --- # Instale a integração reCAPTCHA Você instala a integração reCAPTCHA pelo Azion Marketplace e a executa em um [Firewall](/pt-br/documentacao/plataforma/firewall/), pelo Azion Console. reCAPTCHA é um serviço de CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart): um teste de desafio e resposta identifica se o usuário é um humano ou uma máquina e, assim, protege seus domínios contra bots e scripts automatizados. Você monitora o tráfego do seu site no painel do Google para reCAPTCHA. O Google mantém e é dono do reCAPTCHA e usa os dados que o reCAPTCHA coleta para melhorar os próprios serviços. Cinco objetos precisam existir antes que uma requisição receba o desafio: a função instalada, um firewall com o módulo **Functions**, uma instância de função com os argumentos, uma regra do Rules Engine com o behavior **Run Function** e um deployment de workload vinculado ao firewall. Cada seção abaixo cria um deles. --- ## Pré-requisitos - Uma conta Azion. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). - Uma aplicação servida por um [workload](/pt-br/documentacao/plataforma/workloads/), cujo deployment você vincula ao firewall na última seção. - Uma conta Google, com uma site key e uma secret key do reCAPTCHA. As próximas seções mostram como obtê-las. - A [Azion CLI](/pt-br/documentacao/devtools/cli/) instalada e autorizada, para a última seção. - Ativar um produto ou um módulo pode gerar custos de uso. Para mais informações, consulte [Preços](/pt-br/documentacao/fundamentos/precos/). --- ## Instale a integração A função é instalada uma vez por conta. Para instalá-la: 1. **Abra Marketplace** Acesse [Azion Console](https://console.azion.com/) > **Marketplace**. 2. **Encontre a integração** Digite `reCAPTCHA` no campo **Search on Marketplace** e selecione o card da integração. Navegar pelos cards e pelas categorias leva à mesma página. 3. **Selecione Install** O card mostra `Successfully installed!` e `Latest version installed!`, e a função aparece na lista **Function** do drawer **Create Instance**. --- ## Obtenha as chaves do reCAPTCHA A integração precisa de duas chaves do Google: sua `secret-key` e sua `site-key`. Você obtém as duas ao registrar seu site no Google. Para registrá-lo: 1. **Abra o painel de administração do reCAPTCHA** Acesse o [painel de administração do Google reCAPTCHA](https://developers.google.com/recaptcha). Se você não tem uma conta Google, o site solicita que você crie uma. Depois do cadastro, o site abre a página de registro do seu site. 2. **Digite um rótulo** Digite um rótulo para o novo site no reCAPTCHA. 3. **Selecione a versão do reCAPTCHA** Selecione *v2* ou *v3*. Se selecionar *v2*, selecione o tipo de teste do seu site: *I'm not a robot checkbox*, *Invisible reCaptcha* ou *reCaptcha Android*. A integração reCAPTCHA da Azion foi projetada para funcionar com a opção v2 invisible. 4. **Adicione o domínio** Digite o domínio que executa o reCAPTCHA, sem `http://` ou `https://`. Se você testa por um hostname da Azion, adicione-o também. Para mais informações, consulte [O reCAPTCHA falha em um hostname da Azion](#o-recaptcha-falha-em-um-hostname-da-azion). 5. **Aceite os termos de serviço** Aceite os termos de serviço do reCAPTCHA. 6. **Escolha os alertas** Escolha se quer receber alertas do Google sobre seu site, como erros de configuração. 7. **Selecione Submit** Seu site está registrado para usar o reCAPTCHA. A próxima tela mostra suas chaves, `Site Key` e `Secret Key`, que a instância de função recebe como argumentos. --- ## Crie o firewall O firewall é onde a função é instanciada e onde fica a regra que a executa. Para criar um: 1. **Abra a página Firewalls** Acesse [Azion Console](https://console.azion.com/) > **Firewalls** e crie um firewall. 2. **Dê um nome ao firewall** Na seção **General**, digite um **Name**. Por exemplo: `recaptcha-firewall`. 3. **Ative o módulo Functions** Na seção **Modules**, ative o switch **Functions**. 4. **Salve o firewall** O firewall mostra a aba **Functions Instances** enquanto o módulo **Functions** estiver ativo. Para usar um firewall existente, ative o módulo **Functions** dele e salve-o. Para todas as configurações deste formulário, consulte [Defina as configurações principais de um firewall](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/firewall-definir-main-settings/). --- ## Crie a instância de função A instância guarda suas chaves do reCAPTCHA e a origem que a função busca depois que o desafio é resolvido. Para criá-la: 1. **Abra a aba Functions Instances** Em **Firewalls**, selecione seu firewall e a aba **Functions Instances**. 2. **Selecione + Function** Um firewall sem nenhuma instância mostra a mesma ação como **Function Instance**. O drawer **Create Instance** é aberto. 3. **Dê um nome à instância** Em **Name**, digite um nome. Por exemplo: `recaptcha`. 4. **Selecione a função instalada** Em **Function**, selecione a função reCAPTCHA. A lista contém apenas as funções que são executadas em um firewall. 5. **Insira os argumentos** Em **Arguments**, o editor vem preenchido com os argumentos padrão da integração em JSON. Insira suas chaves e seus valores, como descreve a próxima seção. 6. **Selecione Save** A instância aparece na aba **Functions Instances**. ### Argumentos A instância recebe as duas chaves que você obteve do Google e suas variáveis: ```json { "site_key": "efdb42c7-10ee-4969-8013-cfcb5f7ad007", "secret_key": "0x11c8eB6e78Bd45f058876aF59ac2fB782nbdswqu", "cookie_secret": "A key to sign the cookies", "expiration_in_seconds": 3600, "origin_address": "https://xxxxxxxx.map.azionedge.net", "origin_headers": { "X-Custom": "value", "X-Another-Custom": "another-value" }, "captcha_args": { "theme": "dark", "size": "compact", "custom_message": "My message", "custom_html": "... .. " } } ``` | Variável | Obrigatória | Descrição | | ----------------------- | ----------- | ------------------------------------------------------------------------------------------------- | | `site_key` | Sim | A site key que você obteve na página do reCAPTCHA | | `secret_key` | Sim | A secret key que você obteve na página do reCAPTCHA | | `expiration_in_seconds` | Sim | O tempo, em segundos, até o reCAPTCHA expirar | | `origin_address` | Sim | Seu domínio, do qual a função busca o conteúdo depois que o usuário resolve o desafio CAPTCHA | | `origin_headers` | Não | Os headers de requisição que a origem exige, quando o acesso a ela precisa de headers específicos | | `captcha_args` | Não | Os argumentos que mudam o layout da caixa do desafio | | `custom_message` | Não | Uma mensagem personalizada para mostrar aos usuários | | `custom_html` | Não | O HTML personalizado que renderiza a caixa do desafio do reCAPTCHA | | `cookie_secret` | Sim | A chave que assina o cookie que a função gera, para que a função não seja executada novamente | > **nota** > > Por causa do algoritmo que a criptografia usa, qualquer string de qualquer tamanho pode ser o `cookie_secret`. --- ## Crie a regra A instância não desafia nada até que uma regra a execute. Uma regra do [Rules Engine for Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine/) seleciona as requisições que chegam à instância, por meio de um behavior **Run Function**. Para criar a regra: 1. **Abra a aba Rules Engine** Em **Firewalls**, selecione seu firewall e a aba **Rules Engine**. 2. **Selecione + Rule** 3. **Dê um nome à regra** Em **Name**, digite um nome. Por exemplo: `Run reCAPTCHA`. 4. **Defina o critério** Na seção **Criteria**, selecione os domínios que executam a integração. Por exemplo: if `Host` *matches* `yourdomain.com`. 5. **Adicione o behavior Run Function** Na seção **Behaviors**, selecione **Run Function** e selecione a instância pelo nome que você deu a ela. 6. **Selecione Save** O firewall executa a instância em toda requisição ao domínio do critério. --- ## Vincule o firewall ao workload O vínculo fica no deployment do workload, então crie um deployment que indique a aplicação e o firewall: ```bash azion create workload-deployment --workload-id --name \ --application-id --firewall-id --strategy-type default \ --active true --current true ``` O comando exibe o id do novo deployment: ```text Created Workload Deployment with ID 123456 ``` As requisições ao domínio do workload chegam ao firewall, e a regra executa a instância de reCAPTCHA em cada uma. > **Atenção** > > As requisições à sua aplicação passam pela infraestrutura da Azion, então o serviço reCAPTCHA do Google valida o domínio que serve o desafio: seu domínio da Azion, como `yourdomain.map.azionedge.net`, ou seu domínio personalizado. Se esse domínio não estiver registrado nas suas configurações do Google reCAPTCHA, o desafio falha. Para corrigir, acesse o [painel de administração do Google reCAPTCHA](https://www.google.com/recaptcha/admin), selecione seu site e adicione seu domínio da Azion à lista **Domains**. O Google passa então a aceitar as validações do reCAPTCHA que vêm da sua aplicação na Azion. Assista a um vídeo sobre como instalar a integração reCAPTCHA pelo Azion Marketplace no canal da Azion no YouTube. [How to Install the reCAPTCHA Integration](https://www.youtube.com/watch?v=X-S1qDdVVbg) reCAPTCHA is an integration to block attacks from bots, SPAM and others. --- ## Solução de problemas ### O reCAPTCHA falha em um hostname da Azion O reCAPTCHA não carrega, ou retorna um erro, quando você acessa sua aplicação por um hostname da Azion, como `xxxx.map.azionedge.net`. O Google reCAPTCHA valida as requisições com base em uma lista de domínios autorizados. Se o hostname da Azion não estiver nas suas configurações do reCAPTCHA, o Google rejeita o desafio e a integração falha. Para adicionar o hostname aos domínios autorizados: 1. **Abra o console de administração do reCAPTCHA** Acesse o [console de administração do Google reCAPTCHA](https://www.google.com/recaptcha/admin). 2. **Selecione seu site** Selecione o site que você registrou para esta integração. 3. **Selecione Add a domain** Em **Domains**, selecione **Add a domain**. 4. **Digite o hostname da Azion** Digite seu hostname da Azion. Por exemplo: `xxxx.map.azionedge.net`. Se você usa um domínio personalizado, adicione esse domínio também. 5. **Selecione Save** O reCAPTCHA aceita as requisições que vêm do hostname da Azion, e a integração funciona. > **dica** > > Durante o desenvolvimento e os testes, adicione seu hostname interno da Azion (`*.map.azionedge.net`) à lista de domínios autorizados. Depois de apontar seu domínio personalizado para a Azion, adicione esse domínio também e remova o hostname interno se não precisar mais dele. --- ## Próximos passos - [Integrações do Marketplace](/pt-br/documentacao/plataforma/marketplace/integracoes.md): Todas as integrações que Azion Marketplace oferece e onde cada uma é executada. - [Rules Engine for Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine.md): Todos os critérios e behaviors que uma regra de firewall aceita. - [Instale a integração hCaptcha](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/integracoes/hcaptcha.md): Execute o desafio hCaptcha em um firewall. - [Atualize uma integração](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/integracoes/atualizar-uma-integracao.md): Leve uma integração instalada para a versão mais recente.