For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /producao/keycloak.md.

Keycloak e Mix Identity

O Gera Base usa OpenID Connect Authorization Code com PKCE S256 para autenticar usuarios do realm compartilhado mixapps.

O cliente oficial e gerabase-web. Cadastre somente callbacks e origens exatos; nao use curingas. Depois de alterar o cliente no Keycloak, atualize tambem o manifesto versionado do Mix Identity, pois a importacao do realm nao modifica automaticamente clientes existentes.

Enderecos de producao

Issuer: https://auth.mixhome.app.br/realms/mixapps
Discovery: https://auth.mixhome.app.br/realms/mixapps/.well-known/openid-configuration
Redirect URI: https://gera-base.jvbgprojects.com.br/auth/callback
Post logout redirect URI: https://gera-base.jvbgprojects.com.br

O callback existe somente no servico principal gerador-bancos. As ferramentas Admin, DDL, JSON Viewer e Biblioteca SQL reutilizam a sessao local segura criada depois da validacao no Keycloak.

Todos os seis backends Python confiaveis recebem a politica OIDC, issuer, client ID, client secret e duracao de sessao pelo Compose para revalidar e renovar a sessao compartilhada. O segredo permanece apenas no ambiente dos servidores, nunca no navegador ou n8n. Os auxiliares recusam sessoes locais no modo exclusivo. Essa distribuicao substitui a configuracao anterior que nao fornecia credenciais aos auxiliares e impedia a revalidacao neles.

O inicio do login cria um cookie temporario __Host-gera_base_oidc, host-only, Secure, HttpOnly e SameSite=Lax. O callback exige que o state coincida com esse cookie antes de consumir o estado persistido; um callback enviado a outro navegador e recusado. O cookie e removido junto da criacao da sessao. Logins iniciados antes dessa atualizacao devem ser reiniciados.

Se o Keycloak estiver atras do Cloudflare, os caminhos de discovery, token e JWKS devem aceitar as chamadas do servidor do Gera Base. O cliente envia o User-Agent identificavel GeraBase-OIDC/1.0; nao aplique Cloudflare Access a esses endpoints de protocolo.

Diagnostico rapido

  • Parametro invalido: redirect_uri: compare literalmente o callback enviado com redirectUris do cliente.
  • Login concluido sem acesso: confirme os client roles gerabase-user ou gerabase-admin.
  • Sessao encerrada em ate cinco minutos: confirme introspeccao, estado do usuario e roles; esse comportamento e esperado apos revogacao.
  • Nao habilite login local ou vinculacao por e-mail para contornar falhas de configuracao.

Variaveis do servidor

No arquivo .env privado da producao, configure os nomes abaixo. O segredo deve ser obtido no Keycloak e nunca salvo em Git, logs ou tickets.

OIDC_ENABLED=true
OIDC_ISSUER=https://auth.mixhome.app.br/realms/mixapps
OIDC_CLIENT_ID=gerabase-web
OIDC_CLIENT_SECRET=
OIDC_REDIRECT_URI=https://gera-base.jvbgprojects.com.br/auth/callback
OIDC_LOGOUT_REDIRECT_URI=https://gera-base.jvbgprojects.com.br
OIDC_SCOPES="openid profile email"
OIDC_ALLOW_LOCAL_LOGIN=false
OIDC_SESSION_REVALIDATION_SECONDS=300

Com OIDC_ALLOW_LOCAL_LOGIN=false, somente identidades do Mix Identity podem iniciar ou manter sessoes humanas. Sessoes locais anteriores sao recusadas, e o painel Admin deixa usuarios e papeis como leitura. Se OIDC_ENABLED=true estiver incompleto, o sistema permanece fechado para login local e informa que o provedor esta indisponivel ou incompleto. Use true somente como reversao temporaria e controlada durante a primeira implantacao.

Para os subdominios compartilharem a sessao, mantenha:

GERA_BASE_COOKIE_DOMAIN=.jvbgprojects.com.br
GERA_BASE_PUBLIC_URL=https://gera-base.jvbgprojects.com.br

Configuracao exata no Keycloak

No realm mixapps, crie ou ajuste o client gerabase-web:

  • Tipo: OpenID Connect, cliente confidential.
  • Standard Flow: habilitado.
  • Direct Access Grants: desabilitado, salvo necessidade explicitamente aprovada.
  • PKCE: obrigatorio com S256.
  • Valid Redirect URIs: https://gera-base.jvbgprojects.com.br/auth/callback.
  • Web Origins: https://gera-base.jvbgprojects.com.br.
  • Valid Post Logout Redirect URIs: https://gera-base.jvbgprojects.com.br.
  • Client authentication: habilitada; copie o segredo apenas para o .env privado.
  • Client roles: gerabase-admin e gerabase-user.
  • Mapper de roles: inclua os papeis do client em resource_access.gerabase-web.roles no ID Token e na resposta de introspeccao.

Se houver homologacao publica, use um client separado ou inclua somente os enderecos de staging correspondentes. Nao reutilize o redirect URI de producao.

Comportamento de contas

O par issuer + sub e o identificador externo estavel. No primeiro login com um papel valido, o Gera Base cria uma conta local vinculada a users.keycloak_issuer + users.keycloak_subject; dados existentes como Biblioteca SQL e estados salvos continuam apontando para o id local.

O sistema nao associa contas existentes pelo e-mail, nome ou apelido. Contas locais antigas permanecem intactas para reversao, mas nao podem autenticar nem manter sessoes quando OIDC_ALLOW_LOCAL_LOGIN=false. Para migrar uma conta local com dados para uma identidade Keycloak, associe o keycloak_subject manualmente com um backup do MariaDB e validacao em homologacao.

Usuarios sem gerabase-admin ou gerabase-user recebem acesso negado. gerabase-admin concede funcoes administrativas e gerabase-user recebe as funcoes comuns do Gera Base.

Uma conta comum tentando abrir o Admin recebe 403, sem entrar em um ciclo de redirecionamentos de login.

Automacoes usam um token de API Gera Base, emitido no painel administrativo, em vez da senha corporativa ou do login local. A previa mascara o token; o workflow existente aceita api_token. Esses tokens de integracao nao sao tokens OIDC e mantem sua politica propria de permissoes e revogacao.

O logout local com redirecionamento ao Keycloak esta implementado. A cada no maximo 300 segundos, a aplicacao renova as credenciais quando ha refresh token e introspecta o access token usando somente as credenciais do proprio client, atualiza a role local e encerra a sessao se o token estiver inativo, o subject divergir, a role for removida ou o Keycloak estiver indisponivel. Access/refresh tokens ficam cifrados no MariaDB; a rotacao do client secret encerra sessoes antigas de forma segura. O limite absoluto e GERA_BASE_SESSION_HOURS (8 horas por padrao), respeitando os limites Idle/Max do Keycloak. Entre novamente apos a atualizacao para obter uma sessao renovavel. Tokens de API continuam independentes.

Implantacao segura

  1. Faça backup logico do MariaDB.
  2. Aplique as migrations ate 009_oidc_session_revalidation.sql ou execute o bootstrap da aplicacao atualizada.
  3. Configure o client no Keycloak e preencha o .env privado.
  4. Implante primeiro em homologacao com um redirect URI de staging.
  5. Valide login de um usuario e de um administrador, logout e navegacao entre os subdominios.
  6. Em producao, ative OIDC_ENABLED=true com OIDC_ALLOW_LOCAL_LOGIN=false para aceitar somente usuarios do Mix Identity.
  7. Reinicie gerador-bancos; uma reversao controlada pode definir OIDC_ALLOW_LOCAL_LOGIN=true temporariamente.

O logout em /auth/logout encerra a sessao local e redireciona para o endpoint de logout do Keycloak. Se o provedor estiver indisponivel, a sessao local ainda e removida e o navegador volta para a URL publica configurada.