Keycloak

O Keycloak é um servidor, não uma página onde você embute um script, então o Caputchin vem como uma extensão do Keycloak: um JAR de provider que você adiciona ao 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) fica no repositório: github.com/Caputchin/caputchin-keycloak. Conte com cerca de 15 minutos de uma conta nova até a primeira sessão verificada no servidor.

1. Crie uma chave de site

Entre em caputchin.com/login (seu primeiro login cria a conta), abra sua equipe Pessoal, clique em Criar chave de site, dê a ela o nome do seu realm do Keycloak e clique em Criar. Copie os dois valores:

• a Chave pública (cpt_pub_...),
• o Segredo (cpt_sec_...). Ele aparece uma única vez.

Crie sua conta e a primeira chave de site percorre as mesmas telas com mais detalhes.

2. Instale a extensão

Baixe caputchin-keycloak.jar da versão mais recente, copie-o para o diretório providers/ do Keycloak e reconstrua:

cp 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. Numa imagem de contêiner, copie o JAR e rode o build dentro da imagem:

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

Para compilar o JAR a partir do código-fonte, veja o guia de instalação do repositório.

3. Entregue o segredo ao Keycloak

Mantenha o segredo fora da configuração do realm: defina-o como variável de ambiente no servidor do Keycloak, por exemplo CAPUTCHIN_SECRET, e reinicie o Keycloak. No passo 5 você informa só o nome da variável. Um segredo literal ou uma referência ${vault.*} também funcionam; veja o guia de configuração do repositório.

4. Escolha como o widget renderiza

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

Pronto para usar: o theme embutido

O JAR traz um theme de login caputchin. No Admin Console, abra seu realm, vá em Realm settings → Themes, defina Login theme como caputchin e clique em Save. 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>). 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.

5. Vincule-a ao fluxo de login

O Keycloak não troca o autenticador de um passo no lugar, então você adiciona o passo do Caputchin a uma cópia do fluxo e remove o passo original.

1. Vá em Authentication. No fluxo browser, abra o menu (⋮), clique em Duplicate, dê um nome à cópia (por exemplo browser caputchin) e clique em Duplicate.

2. Na cópia, encontre o subfluxo forms. Clique no botão + (Add) dele, escolha Add execution, selecione Caputchin Username Password Form e clique em Add.

3. Arraste o passo novo para o topo do subfluxo forms, acima do subfluxo Conditional 2FA, para que ele rode onde o passo antigo rodava. O requisito dele é Required.

4. Exclua o passo original Username Password Form do subfluxo forms.

5. Clique na engrenagem (Settings) do passo do Caputchin e preencha:

   • Alias: qualquer nome, como caputchin-login.
   • Site key: sua chave pública (cpt_pub_...), o único valor enviado ao navegador.
   • Secret key env var: o nome da variável do passo 3, como CAPUTCHIN_SECRET.

   Depois clique em Save. Os outros campos têm padrões que funcionam: Widget mode checkbox (ou invisible, ou game), Locale kc (segue o locale do realm) e Fail closed ligado, então uma queda da verificação bloqueia os logins em vez de deixá-los passar.

6. Abra o menu Action do fluxo, clique em Bind flow, mantenha Browser flow e clique em Save.

O desafio renderiza na mesma página que as credenciais, não como um passo à parte. Com as configurações padrão, a conferência roda quando o usuário clica em Sign In.

Redefinição de senha e registro

O mesmo padrão protege os outros dois formulários:

Cada passo do Caputchin tem as próprias configurações (engrenagem), então informe a chave de site e a variável do segredo em cada um. 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. Binding to flows no repositório mostra a mesma configuração como JSON de export do realm.

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

6. Confira a Content Security Policy

A Content Security Policy de login padrão do Keycloak (em Realm settings → Security defenses → Headers) é frame-src 'self'; frame-ancestors 'self'; object-src 'none';. Ela restringe frames, não scripts nem conexões, e o jogo roda num frame srcdoc, então a checkbox, o widget invisível e o jogo funcionam com ela sem mudanças.

Se você definir uma política própria mais estrita, parta da que está no guia de CSP do repositório. Uma diretiva script-src também vale para os scripts inline do próprio Keycloak, então teste a página de login e o Account Console depois de qualquer mudança.

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 política do navegador.

7. Confirme a primeira sessão verificada no servidor

1. Abra o login da sua aplicação (ou a página de login do realm) numa janela anônima.
2. Entre com um usuário de teste. O widget roda quando você clica em Sign In, e o Keycloak faz o seu login.
3. No painel do Caputchin, abra sua equipe e clique na sua chave de site. Atualize as estatísticas.

Verificadas no servidor agora mostra pelo menos 1: o Keycloak confirmou um token com o Caputchin. Essa é a sua primeira sessão verificada. Se a página de login mostrar "Verification failed. Please complete the check and try again." e Verificadas no servidor continuar em 0, o token nunca chegou ao Keycloak: procure um erro de Content Security Policy no console do navegador (passo 6). Se Concluídas no cliente subiu mas o login ainda falha, confira se a variável do segredo do passo 3 está definida no servidor. Estatísticas e sessões explica cada número.

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.

Veja também

• Visão geral das chaves de site
• WordPress