--- name: azion-instale-a-integracao-hcaptcha description: >- Instale o hCaptcha pelo Azion Marketplace e execute o desafio dele em um firewall, para que apenas requisições que passam por ele cheguem à sua origem. --- # Instale a integração hCaptcha Você instala a integração hCaptcha pelo Azion Marketplace e a executa em um [Firewall](/pt-br/documentacao/plataforma/firewall/), pelo Azion Console. O hCaptcha é um serviço CAPTCHA: ele mostra um desafio difícil de resolver para bots, web crawlers e outras ferramentas automatizadas, e a integração deixa uma requisição chegar à sua origem apenas depois que o desafio é resolvido. Cinco objetos precisam existir antes de uma requisição receber o desafio: a função instalada, um firewall com o módulo **Functions**, uma instância de função que guarda 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 no hCaptcha, com uma site key e uma secret key. As próximas seções mostram como obtê-las. - O [Azion CLI](/pt-br/documentacao/devtools/cli/) instalado e autorizado, para a última seção. - Ligar 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 o Marketplace** Acesse [Azion Console](https://console.azion.com/) > **Marketplace**. 2. **Encontre a integração** Informe `hCaptcha` no campo **Search on Marketplace** e selecione o card da integração. Navegar pelos cards e pelas categorias alcança a 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 hCaptcha A integração precisa de duas chaves do hCaptcha: sua secret key e sua site key. Você obtém as duas no site do hCaptcha. Para registrar seu site: 1. **Abra o painel do hCaptcha** Acesse o [painel do hCaptcha](https://dashboard.hcaptcha.com/overview). Se você não tem uma conta, [crie uma](https://www.hcaptcha.com/signup-interstitial). Quando você cria a conta, o site fornece sua secret key. Você usa essa chave para configurar a integração, então guarde-a em um lugar seguro. 2. **Selecione Add Site** 3. **(Opcional) Nomeie sua instância do hCaptcha** O nome é opcional, mas recomendado. 4. **Adicione os hostnames** Informe os `hostnames` que mostram o desafio e selecione **Add Domain**. 5. **Selecione o modo de desafio** Selecione um de três modos: - **Always Challenge**: gratuito. Toda requisição carrega um desafio. - **Passive**: pago. Nenhum desafio aparece, e o CAPTCHA é acionado pelo comportamento do usuário. - **99.9% Passive**: pago. O desafio aparece apenas para usuários com alto risco de serem bots. 6. **Selecione o limite de aprovação** Selecione o nível de dificuldade: *auto*, *easy*, *moderate* ou *difficult*. O nível define o quanto as respostas de um usuário precisam ser precisas para passar no teste. 7. **Selecione Save** Seu site está configurado para usar o hCaptcha. Para copiar a site key: 1. **Abra a lista de sites** No menu do painel, selecione **Sites**. 2. **Encontre seu site** Encontre o site que você configurou. A primeira coluna mostra uma string como `efdb42c7-10ee-4969-8013-cfcb5f7ad007`. Essa string é sua site key. 3. **Copie a site key** Passe o cursor sobre a string e selecione-a para copiar sua site key. Você tem a site key e a secret key que a instância de função recebe como argumentos. --- ## Crie o firewall O firewall é onde a função é instanciada e onde vive 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. **Nomeie o firewall** Na seção **General**, informe um **Name**. Por exemplo: `hcaptcha-firewall`. 3. **Ligue o módulo Functions** Na seção **Modules**, ligue o switch **Functions**. 4. **Salve o firewall** O firewall mostra uma aba **Functions Instances** enquanto o módulo **Functions** permanecer ligado. Para usar um firewall existente, ligue o módulo **Functions** dele e salve-o. Para cada configuração 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 hCaptcha e a origem que a função busca depois de um desafio resolvido. Para criá-la: 1. **Abra a aba Functions Instances** Em **Firewalls**, selecione seu firewall e depois selecione a aba **Functions Instances**. 2. **Selecione + Function** Um firewall que não tem instância mostra a mesma ação como **Function Instance**. O drawer **Create Instance** abre. 3. **Nomeie a instância** Em **Name**, informe um nome. Por exemplo: `hcaptcha`. 4. **Selecione a função instalada** Em **Function**, selecione a função hCaptcha. A lista contém apenas as funções que são executadas em um firewall. 5. **Informe os argumentos** Em **Arguments**, o editor vem preenchido com os argumentos padrão da integração em JSON. Informe suas chaves e seus valores, como a próxima seção descreve. 6. **Selecione Save** A instância aparece na aba **Functions Instances**. ### Argumentos A instância recebe as duas chaves e suas variáveis: ```json { "site_key": "", // Substitua por sua site key "secret_key": "", // Substitua por sua secret key "cookie_secret": "A key to sign the cookies", "expiration_in_seconds": 3600, "origin_address": "https://xxxxxxxx.map.azionedge.net", // Substitua por seu domínio "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 hCaptcha | | `secret_key` | Sim | A secret key que você obteve na página do hCaptcha | | `expiration_in_seconds` | Sim | O tempo, em segundos, até o desafio expirar | | `origin_address` | Sim | Seu domínio, de onde a função busca o conteúdo depois que o usuário resolve o desafio | | `origin_headers` | Não | Os cabeçalhos de requisição que a origem exige, quando o acesso a ela precisa de cabeçalhos específicos | | `captcha_args` | Não | Os argumentos que mudam o layout da caixa de desafio | | `custom_message` | Não | Uma mensagem personalizada para mostrar aos usuários | | `custom_html` | Não | O HTML personalizado que renderiza a caixa de desafio | | `cookie_secret` | Sim | A chave que assina o cookie que a função gera, para que a função não seja executada de novo para o mesmo usuário | > **nota** > > Por causa do algoritmo que a criptografia usa, qualquer string de qualquer comprimento 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 para 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 depois selecione a aba **Rules Engine**. 2. **Selecione + Rule** 3. **Nomeie a regra** Em **Name**, informe um nome. Por exemplo: `Run hCaptcha`. 4. **Defina o critério** Na seção **Criteria**, selecione o domínio que executa a integração. Por exemplo: if `Hostname` *is equal* `xxxxxxxxxxxx.map.azionedge.net`. 5. **Adicione o behavior Run Function** Na seção **Behaviors**, selecione **Run Function** e depois 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 nomeie 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 imprime 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 do hCaptcha em cada uma delas. --- ## Marca registrada hCaptcha é uma marca registrada da Intuition Machines, Inc. Assista a um vídeo sobre como instalar a integração hCaptcha® pelo Azion Marketplace no canal da Azion no YouTube. [How to Install the hCaptcha® Integration](https://www.youtube.com/watch?v=HqdX9wAWJDg) hCaptcha is an integration to protect your assets from bot attacks, SPAM, and others. --- ## Próximos passos - [Integrações do Marketplace](/pt-br/documentacao/plataforma/marketplace/integracoes.md): Todas as integrações que o Azion Marketplace oferece, e onde cada uma é executada. - [Rules Engine para Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine.md): Todos os critérios e behaviors que uma regra de firewall aceita. - [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.