Keycloak

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.

1. Instale a extensão

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

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

3. Vincule-a aos seus fluxos

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

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

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.