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
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 comredirectUrisdo cliente.- Login concluido sem acesso: confirme os client roles
gerabase-userougerabase-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.
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:
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
.envprivado. - Client roles:
gerabase-adminegerabase-user. - Mapper de roles: inclua os papeis do client em
resource_access.gerabase-web.rolesno 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
- Faça backup logico do MariaDB.
- Aplique as migrations ate
009_oidc_session_revalidation.sqlou execute o bootstrap da aplicacao atualizada. - Configure o client no Keycloak e preencha o
.envprivado. - Implante primeiro em homologacao com um redirect URI de staging.
- Valide login de um usuario e de um administrador, logout e navegacao entre os subdominios.
- Em producao, ative
OIDC_ENABLED=truecomOIDC_ALLOW_LOCAL_LOGIN=falsepara aceitar somente usuarios do Mix Identity. - Reinicie
gerador-bancos; uma reversao controlada pode definirOIDC_ALLOW_LOCAL_LOGIN=truetemporariamente.
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.