# Use a integração reCAPTCHA no Marketplace

**reCaptcha** é uma integração *serverless* disponível no **Marketplace** da Azion. Esse tipo de integração é usado principalmente para proteger domínios contra bots e permite que você monitore o tráfego em seu site usando o Painel do Google para reCAPTCHA.

reCAPTCHA é uma integração CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart, em inglês) projetada para proteger sites de bots e scripts automatizados utilizando um teste de desafio-resposta para determinar se o usuário é um humano ou uma máquina.

O Google é dono e responsável da manutenção do reCAPTCHA e usa os dados coletados pelo reCAPTCHA para melhorar seus serviços.

---

## Obtenha a integração

Para instalar a integração **reCAPTCHA** fornecida pelo **Marketplace** da Azion:

1. Acesse o [Azion Console](/pt-br/documentacao/produtos/guias/como-acessar-o-azion-console/) > **Marketplace**.
2. Na homepage do Marketplace, selecione o card da integração.
3. Quando a página da integração abrir, clique no botão **Install**.

Você receberá uma mensagem indicando que sua integração foi instalada com sucesso.

:::tip
Você pode procurar qualquer integração navegando pelos cards, usando os filtros ou digitando uma palavra-chave na barra de busca.
:::

---

## Obtenha as credenciais no site reCAPTCHA do Google

Para usar a integração **reCAPTCHA** da Azion, você deve fornecer duas chaves: sua `secret-key` e sua `site-key`. Para obter essas credenciais, você terá que se registrar no Google.

Para fazer isso, siga os passos:

1. Acesse o [painel de administração do Google reCAPTCHA](https://developers.google.com/recaptcha).
- Se você não tiver uma Conta do Google, será solicitado que crie uma.
2. Uma vez inscrito, você será redirecionado para a página de registro no site.
3. Nesta página, você deve preencher:
   - Um nome para o seu novo site que usará reCAPTCHA.
   - A versão do reCAPTCHA que você deseja usar (você pode escolher entre v2 ou v3).
      - Se você escolher a v2, será solicitado que escolha o tipo de teste que deseja aplicar em seu site. As opções são: "*I'm not a robot checkbox*", "*Invisible reCaptcha*" e "*reCaptcha Android*".
      - **Importante**: a integração reCAPTCHA da Azion foi concebida para funcionar com a opção v2 invisível.
   - O domínio onde você deseja executar o reCAPTCHA. Lembre-se de ignorar o `http://`ou `https://` para adicionar o nome de domínio. Se você estiver testando por meio de um hostname da Azion, adicione-o aqui também (consulte [Troubleshooting](#recaptcha-nao-funciona-no-dominio-da-azion)).
   - Você precisa aceitar os termos de serviço.
   - Você tem que escolher se deseja receber alertas do Google sobre seu site, como erros de configuração e outros.
4. Depois de preencher todas as informações, clique no botão **Submit**.

Agora você tem seu site registrado para usar o reCAPTCHA. Na próxima tela, você receberá suas chaves: `Site Key` e `Secret Key`.

Essas duas chaves serão usadas para configurar a integração reCAPTCHA da Azion posteriormente.

---

## Configure a integração

### Configure um firewall

Para iniciar a configuração da **reCaptcha**, complete estes passos:

1. No **Products menu**, selecione **Firewall** na seção **SECURE**.
2. Clique no botão **+ Firewall**.
3. Dê um nome fácil de lembrar ao firewall.
4. Habilite o switch **Functions** para habilitar que você rode functions.
5. Clique no botão **Save**.

Pronto. Você instanciou o firewall para sua função.

### Configure uma função no Firewall

Para instanciar a integração hCaptcha, enquanto ainda estiver na página do Firewall:

1. Selecione a aba **Functions Instances**.
2. Clique no botão **+ Function Instance**.
3. Dê um nome fácil de lembrar à sua instância.
4. No menu suspenso, selecione a função **reCAPTCHA**.
   - Esta ação carregará a aba **Arguments**.
5. Na aba **Arguments**, você passará as duas chaves que você obteve no site hCaptcha 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": "<html>... <!-- azion_captcha -->  .. </html>"
  }
}

```

Onde:

| Variável | Obrigatório | Descrição |
| ---- | ----- | ----- |
| `site_key` | Sim | A site key que você obteve na página reCAPTCHA |
| `secret_key` | Sim | A secret key que você obteve na página reCAPTCHA |
| `expiration_in_seconds` | Sim | O tempo *em segundos* até que o reCAPTCHA expire |
| `origin_address` | Sim | Seu domínio a partir do qual a função buscará o conteúdo após o usuário resolver o desafio CAPTCHA |
| `origin_headers` | Não | Sempre que o acesso à origem exigir o uso de cabeçalhos de requisição específicos |
| `captcha_args` | Não | Essas variáveis modificam e personalizam o layout da caixa de desafio |
| `custom_message` | Não | Uma mensagem personalizada que você deseja mostrar aos usuários |
| `custom_html` | Não | O HTML personalizado para renderizar a caixa de desafio do reCaptcha |
| `cookie_secret` | Sim | Este cookie é gerado pela função e usado para que as funções não sejam executadas novamente |

:::note
Devido ao algoritmo usado na criptografia, qualquer string de qualquer comprimento pode ser usada como `cookie_secret`.
:::

6. Clique no botão **Save** para salvar suas configurações.

Pronto. Agora sua instância **reCAPTCHA** está salva.

### Configure o Rules Engine

Para finalizar o processo, é necessário configurar os parâmetros *behavior* (comportamento) e *criteria* (critério) para executar a função.

Ainda na página do **Firewall**:

1. Selecione a aba **Rules Engine**.
2. Clique no botão **+ Rule Engine**.
3. Dê um nome fácil de lembrar à sua nova regra.
4. Selecione um *criteria* (critério) para executar a integração.
  - Exemplo: if `Host` *matches* `yourdomain.com`.
5. Abaixo, selecione um *behavior* (comportamento) para os *criteria* (critérios). Neste caso, será **Run Function**.
   - Selecione a função adequada de acordo com o nome que você deu na etapa de instanciação.
6. Clique no botão **Save**.

Agora, no Console, você deve configurar seu domínio para que ele seja protegido pelo seu firewall.

7. No **Products menu**, selecione **Workloads**.
8. Clique no domínio que você deseja proteger com sua função **reCAPTCHA**.
9. Na seção **Settings**, clique no seletor de `Firewall` e escolha o firewall que você acabou de criar.
10. Clique no botão **Save**.

Pronto. Agora a integração **reCAPTCHA** está em execução para cada requisição feita ao domínio que você indicou.

---

## Troubleshooting

### reCAPTCHA não funciona no domínio da Azion

**Sintoma**: o reCAPTCHA falha ao carregar ou retorna um erro ao acessar sua aplicação por meio de um hostname da Azion (por exemplo, `xxxx.map.azionedge.net`).

**Causa**: o Google reCAPTCHA valida as requisições em relação a uma lista de domínios autorizados. Se o hostname da Azion não estiver registrado nas configurações do reCAPTCHA, o Google rejeitará o desafio, fazendo com que a integração falhe.

**Solução**: adicione seu domínio da Azion à lista de domínios autorizados no painel de administração do Google reCAPTCHA.

1. Acesse o [painel de administração do Google reCAPTCHA](https://www.google.com/recaptcha/admin).
2. Selecione o site que você registrou para esta integração.
3. Em **Domains**, clique em **Add a domain**.
4. Insira seu hostname da Azion. Por exemplo: `xxxx.map.azionedge.net`.
   - Se você estiver usando um domínio personalizado, adicione-o também.
5. Clique em **Save**.

Após salvar, o reCAPTCHA reconhecerá as requisições provenientes do hostname da Azion e a integração funcionará conforme esperado.

:::tip
Durante o desenvolvimento e os testes, adicione seu hostname interno da Azion (`*.map.azionedge.net`) à lista de domínios autorizados. Quando você apontar seu domínio personalizado para a Azion, adicione esse domínio também e remova o hostname interno se ele não for mais necessário.
:::

---