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. 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

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, 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
• Releases (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Issues / pedidos de funcionalidade: abertos no repositório acima
• Relacionados: SDK Web · Referência da API