---
title: Keycloak
---

# Keycloak

Plugin oficial da CaptchaLa para Keycloak. Adiciona um desafio CAPTCHA às telas nativas de login, cadastro e redefinição de senha do Keycloak, com verificação no lado do servidor, sem escrever nenhum código. É entregue como um único JAR de provider que você coloca no Keycloak.

## O que ele cobre

Cada fluxo abaixo é conectado como uma etapa de autenticação separada — você protege apenas as telas que deseja.

- Login no navegador (o formulário de usuário / senha)
- Auto-cadastro
- Redefinição de senha (a tela de "esqueci a senha")

O desafio é renderizado como um widget flutuante por padrão (`float`), ou como um modal clicável (`popup`).

## Instalação

### 1. Obtenha o JAR

O plugin é open source em
[**github.com/Captcha-La/captchala-keycloak**](https://github.com/Captcha-La/captchala-keycloak). Duas opções:

- **Baixe a release** (recomendado) — pegue `keycloak-captchala-<version>.jar` na página de Releases do repositório.
- **Compile do código-fonte** — faça `git clone` do repositório e rode `mvn clean package`; o JAR é gerado em `target/`.

O plugin tem como alvo Keycloak ≥ 26 (Quarkus) e Java 17.

### 2. Faça o deploy

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# reinicie o Keycloak
```

Em seguida, defina o tema de login: **Configurações do Realm → Temas → Tema de login → `captchala`**.

### 3. Obtenha suas chaves

Cadastre-se em [`dash.captcha.la`](https://dash.captcha.la), crie uma aplicação e então copie:

- **App Key** — pública, embarcada na página
- **App Secret** — apenas do lado do servidor, usada pelo Keycloak para gerar um token de uso único e chamar `/v1/validate`

### 4. Configure os fluxos

No console de administração, adicione a execução correspondente a cada fluxo que deseja proteger e clique no ícone de engrenagem para colar sua **App Key** e seu **App Secret**:

- **Login no navegador** — duplique o fluxo *browser*, substitua **Username Password Form** por **Captchala Username Password Form** (REQUIRED) e vincule como o fluxo browser do realm.
- **Cadastro** — duplique o fluxo *registration*, adicione **Captchala Registration** (REQUIRED) ao sub-fluxo do formulário de cadastro e vincule como o fluxo de cadastro do realm.
- **Redefinição de senha** — duplique o fluxo *reset credentials*, substitua **Choose User** por **Captchala Reset Credential (choose user)** (REQUIRED) e vincule como o fluxo de reset de credenciais do realm.

Abra uma das telas protegidas em uma janela anônima para confirmar que o desafio é renderizado.

## Configuração

Cada execução é configurada de forma independente pelo seu ícone de engrenagem. Os valores padrão funcionam imediatamente após as chaves serem definidas.

| Configuração | Chave | Padrão | Descrição |
| --- | --- | --- | --- |
| App Key | `app.key` | — | Chave pública do painel da CaptchaLa. Obrigatória. |
| App Secret | `app.secret` | — | Segredo do servidor. Obrigatório. Armazenado mascarado, nunca exposto ao navegador. |
| URL base da API | `api.base` | `https://apiv1.captcha.la` | Base da API da CaptchaLa. |
| URL do script do widget | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | De onde o JS do widget é carregado. |
| URL do CSS do widget | `css.url` | `https://api.captcha.la/sdk/jslib/captchala.css` | De onde o CSS do widget é carregado. |
| Modo de renderização | `product` | `float` | `float` (widget flutuante) ou `popup` (modal). |
| Rótulo de action | `action` | por fluxo | O `action` enviado na validação (`login`, `register`, `reset`). |
| Idioma | `language` | locale do realm | Idioma do widget; em branco segue o locale do Keycloak. |
| Falhar fechado | `fail.closed` | `true` | Quando a API da CaptchaLa estiver inacessível, rejeita o envio. Desative para falhar em modo aberto. |
| Usar token do servidor | `use.server.token` | `true` | Gera um token de uso único no servidor na renderização para maior proteção contra replay. |

## FAQ

**O plugin é gratuito?**

Sim. O plugin para Keycloak é gratuito e open source. O plano gratuito da CaptchaLa cobre 10.000 verificações por mês — planos pagos só se aplicam se você precisar de mais volume.

**Quais versões do Keycloak são suportadas?**

Keycloak 26+ na distribuição Quarkus, compilado contra a versão 26.5.6 com Java 17. Coloque o JAR em `providers/`, rode `kc.sh build` e reinicie.

**Quais telas ele pode proteger?**

Login no navegador, auto-cadastro e redefinição de senha. Cada uma é adicionada ao seu fluxo de forma independente, então você pode proteger uma, duas ou todas as três.

**O App Secret é alguma vez exposto ao navegador?**

Não. O segredo é armazenado mascarado e é enviado apenas no cabeçalho `X-App-Secret` do Keycloak para a API da CaptchaLa. Ele nunca aparece em nenhuma página, template ou log. Cada desafio é verificado com um token de uso único, então um token resolvido não pode ser repetido.

**O que acontece se a API da CaptchaLa estiver inacessível?**

Por padrão o plugin falha fechado (o envio é rejeitado). Defina `fail.closed` como desativado em qualquer execução para falhar em modo aberto — útil para rollout faseado, não recomendado para produção.

## Código-fonte

- Repositório do plugin: [`github.com/Captcha-La/captchala-keycloak`](https://github.com/Captcha-La/captchala-keycloak)
- Releases (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- Issues / pedidos de funcionalidade: abertos no repositório acima
- Relacionados: [SDK Web](/pt-BR/web-sdk) · [Referência da API](/pt-BR/api-reference)