---
type: how-to
title: Keycloak
summary: "Proteja o login, a redefinição de senha e o registro do Keycloak com o Caputchin: instale a extensão, escolha um modo de render e verifique o token no lado do servidor."
---

O Keycloak é um servidor, não uma página onde você embuta um script, então o Caputchin vem como uma **extensão** do Keycloak: um JAR de provider que você solta dentro do Keycloak. Ele renderiza o widget do Caputchin nas páginas de login, redefinição de senha e registro, e verifica o token de dentro do Keycloak antes de o fluxo prosseguir. Tanto o widget de checkbox quanto o jogo funcionam.

A extensão é de código aberto. A referência completa (cada propriedade de configuração, o JSON de export do realm, o contrato do theme e uma matriz de compatibilidade) vive no repositório: [github.com/Caputchin/caputchin-keycloak](https://github.com/Caputchin/caputchin-keycloak).

<Callout type="info">
Funciona com o Keycloak 26.x (a distribuição Quarkus). Você precisa de acesso ao deployment do Keycloak para adicionar um JAR de provider e rodar `kc.sh build`; isto não é um app de marketplace hospedado.
</Callout>

## 1. Instale a extensão

Construa o JAR de provider e coloque-o no Keycloak, depois reconstrua:

```bash
# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package

cp target/caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimized
```

`kc.sh build` é necessário para o Keycloak descobrir os providers.

## 2. Escolha como o widget renderiza

Há dois jeitos, e você escolhe por realm.

### Pronto para usar: o theme embutido (sem theme próprio)

O JAR traz um theme de login `caputchin`. Defina-o em **Realm Settings → Themes → Login theme: `caputchin`**, e o widget renderiza nas páginas de login, redefinição e registro sem editar templates. Este é o caminho mais rápido se você usa um login de Keycloak padrão.

### Headless: seu próprio theme renderiza o widget

Se você entrega um theme de login próprio (por exemplo um theme React de Keycloakify), mantenha seu theme e rode a extensão em headless. Ela expõe a configuração do widget ao contexto da página e valida o token; seu theme renderiza o elemento `<caputchin-widget>` (ou `<caputchin-game>`) e o estiliza com seus design tokens. O campo do token é `caputchin-token`. O contrato de atributos completo e um exemplo de Keycloakify estão no [guia do theme do repositório](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).

## 3. Vincule-a aos seus fluxos

Em **Authentication → Flows**, duplique o fluxo que você quer proteger e troque a execução:

| Fluxo | Defina a execução como |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | adicione o Caputchin ao formulário de registro |

Os desafios de login e redefinição renderizam na mesma página que as credenciais, não como um passo à parte. Abra a configuração de cada execução (a engrenagem) para definir suas chaves. Não adicione um desafio ao fluxo de direct grant: ali não há navegador, então quebraria as requisições de token por API.

## 4. Configure as chaves

Na configuração da execução, defina:

- **Chave de site**: sua chave pública (`cpt_pub_...`). O único valor enviado ao navegador.
- **Chave secreta**: seu segredo (`cpt_sec_...`). Você pode guardá-la como literal, apontar para uma variável de ambiente (para que ela nunca caia no seu export do realm), ou usar uma referência `${vault.*}`.
- **Modo do widget**: `checkbox`, `invisible` ou `game`. Mais o tamanho, o locale (por padrão segue o locale do realm) e o skin.
- **Falha fechada**: ligada por padrão, então uma queda da verificação bloqueia em vez de deixar os bots passarem.

O visual mais rico (qual jogo, skins, marca) é definido uma única vez no [painel do Caputchin](https://caputchin.com) na própria chave de site, então você não o repete aqui.

## 5. Permita o widget na sua Content Security Policy

A CSP de login padrão do Keycloak é mais estrita do que o widget precisa. Em **Realm Settings → Security Defenses → Content Security Policy**, permita o script do carregador, o host de verificação e WebAssembly. O valor exato está no [guia de CSP do repositório](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).

<Callout type="info">
A verificação no lado do servidor (do Keycloak ao host de verificação) é uma chamada de servidor para servidor e não é afetada pela CSP do navegador. Só o tráfego do widget no lado do navegador é.
</Callout>

## Experimente localmente

O repositório inclui um Keycloak local de um comando só (`e2e/`) ligado a um stack local do Caputchin, para você clicar pelos três fluxos protegidos antes de implantar. Veja o [README do repositório](https://github.com/Caputchin/caputchin-keycloak).