Pular para conteúdo

Projeto eCosif 02/2026

ecosif-auth (API Java) – versão: 0.7.01.202601280
Notas de Versão e Impacto
versão documento data responsável
0.7.01.202601280 20/02/2026 José Augusto de Lima Pereira

Índice

ecosif-auth — Release Notes e Impacto na Execução 3

1. Resumo executivo 3

2. Novidades e melhorias (release notes para o cliente) 3

2.1 Segurança e stack 3

2.2 Funcionalidades 4

2.3 Base de dados e migrações 4

2.4 Documentação e operação 4

3. Mudanças que afetam a execução do serviço 5

3.1 Variáveis de ambiente — ação obrigatória 5

3.2 Context path e API Gateway 6

3.3 Flyway e primeira implantação 6

3.4 Docker e imagem 7

3.5 Dependência local (ecosif-database) 7

4. Checklist de atualização (0.6.00.x → 0.7.01.x) 7

ecosif-auth — Release Notes e Impacto na Execução

Versão anterior: 0.6.00.x
Versão atual: 0.7.01.x

Este documento descreve as alterações entre a versão 0.6.00.x e a versão 0.7.01.x, em formato de release notes para o cliente, e as mudanças que afetam a execução e a operação do serviço.

1. Resumo executivo

Aspecto 0.6.00.x (antes) 0.7.01.x (atual)
Versão 0.6.00.202503251 0.7.01.202601280
Java 11 17
Spring Boot 2.4.2 2.7.18
JWT JJWT 0.9.1 JJWT 0.11.5 (HMAC 256 bits)
Documentação API Swagger 2.9.2 SpringDoc OpenAPI 3.0
Variáveis de ambiente Nomes em minúsculas (ecosif_*) Nomes em MAIÚSCULAS (POSTGRES_*, ECOSIF_*)
Migrações de BD Não utilizadas (Hibernate ou scripts manuais) Flyway (execução automática na subida)
Biblioteca partilhada ecosif-database 0.6.00.202503251 ecosif-database 0.7.01.202512010

A atualização exige reconfigurar as variáveis de ambiente e garantir que o context path (ex.: /ecosif-auth) esteja alinhado com o API Gateway. Na primeira implantação da nova versão, o Flyway aplicará todas as migrações incluídas na imagem.

2. Novidades e melhorias (release notes para o cliente)

2.1 Segurança e stack

  • Migração para Java 17 e Spring Boot 2.7.18: atualização de runtime e framework para versões com suporte de longo prazo e correções de segurança.
  • JWT com chave de 256 bits (JJWT 0.11.5): tokens assinados com HMAC SHA-256; maior robustez em relação à versão anterior.
  • Dockerfile de produção: imagem multi-stage com Amazon Corretto 17, utilizador não-root e health check no Actuator.

2.2 Funcionalidades

  • Login com Azure AD (Microsoft Entra ID): novo endpoint para autenticação via Azure AD e criação automática de utilizador quando não existir (/api/auth/signin-azure ou equivalente sob o context path configurado).
  • Endpoint de logs Docker (administrativo): recurso opcional para consulta de logs de contentores (uso interno/admin), exposto sob o path configurado do serviço.
  • Documentação OpenAPI 3.0: substituição do Swagger 2 por SpringDoc; documentação interativa em /swagger-ui.html e especificação em /v3/api-docs.

2.3 Base de dados e migrações

  • Flyway integrado: todas as alterações de schema são aplicadas automaticamente na subida da aplicação (quando ECOSIF_FLYWAY_ENABLED=true), a partir dos scripts em db/migration.
  • Novas migrações incluídas: desde a limpeza/criação inicial do schema (V0.6.00.x), índices e foreign keys de desempenho (V0.7.00.1, V0.7.00.2), ajustes de colunas boolean e compatibilidade JPA (V0.7.00.0, V0.7.00.3), e tabela de cidades (V0.7.00.4). Na primeira execução da nova versão contra uma base existente, o Flyway aplicará apenas as migrações ainda não executadas (por versão).

2.4 Documentação e operação

  • Documentação reorganizada: pasta docs/ com documentos por público (technical, operational, functional) e pasta anotations/ com anotações de arquitetura, desenvolvimento, integradores e endpoints.
  • Guia AWS (ECS + API Gateway): documento específico para implantação na Amazon com ECS e API Gateway (docs/aws-ecs-api-gateway.md).
  • Scripts de apoio: scripts/run-dev.sh para ambiente de desenvolvimento e scripts/test-login-and-refresh.sh para testes de login e refresh token.
  • Tratamento de erros e configuração: melhorias no tratamento global de exceções e configuração de segurança (OAuth2 desativável quando o client id está vazio).

3. Mudanças que afetam a execução do serviço

3.1 Variáveis de ambiente — ação obrigatória

Os nomes das variáveis passaram de minúsculas para MAIÚSCULAS e alguns identificadores foram alterados. O arquivo env.template (formato antigo) foi removido; a configuração deve usar as variáveis abaixo.

Tabela de equivalência (0.6.00.x → 0.7.01.x):

0.6.00.x (antigo) 0.7.01.x (atual) Observação
ecosif_port ECOSIF_AUTH_PORT Porta HTTP do serviço (ex.: 8080).
ecosif_context SERVER_SERVLET_CONTEXT_PATH Path da aplicação (ex.: /ecosif-auth para API Gateway).
ecosif_db_server POSTGRES_HOST Host do PostgreSQL.
ecosif_db_port POSTGRES_PORT Porta do PostgreSQL (ex.: 5432).
ecosif_db_login POSTGRES_DB Nome da base de dados.
ecosif_db_user POSTGRES_USER Utilizador do banco.
ecosif_db_password POSTGRES_PASSWORD Senha (usar repositório de segredos).
hibernate_mode HIBERNATE_DDL_AUTO Em produção use validate; schema gerido pelo Flyway.
(não existia) ECOSIF_FLYWAY_ENABLED true para aplicar migrações na subida; false para desativar.
auth_token_secret AUTH_TOKEN_SECRET Chave JWT (manter segredo forte).
token_expiration TOKEN_EXPIRATION Tempo de vida do token em ms (ex.: 86400000).
ecosif_cors ECOSIF_CORS Origens CORS permitidas (ex.: https://app.ecosif.banco.com.br).
auth2_clientid AUTH2_CLIENT_ID OAuth2 Google (opcional); se vazio, OAuth2 fica desativado.
auth2_secret AUTH2_SECRET OAuth2 Google (opcional).
ecosif_logshow ECOSIF_LOGSHOW Exibir SQL nos logs (ex.: false em prod).
ecosif_logmode_* ECOSIF_LOGMODE_ROOT, ECOSIF_LOGMODE_SPRING, ECOSIF_LOGMODE_HIBERNATE_SQL, ECOSIF_LOGMODE_HIBERNATE Níveis de log.
log_format LOG_FORMAT Nome do logback: default, json ou spring.
swagger_enabled (removido) SpringDoc está sempre disponível; pode restringir por rede/firewall se necessário.

Variáveis de pool HikariCP: na versão atual estão com valores fixos no application.yml (timeout, pool size, etc.); não é necessário configurar ecosif_hk_*.

3.2 Context path e API Gateway

  • Na versão 0.6.00.x o path podia ser / ou outro via ecosif_context.
  • Na versão 0.7.01.x, para integrar com um API Gateway único (ex.: https://app.ecosif.banco.com.br/ecosif-auth), é obrigatório definir:
  • SERVER_SERVLET_CONTEXT_PATH=/ecosif-auth
  • O health check passa a ser: /ecosif-auth/actuator/health (ou o path que configurou).
  • Os endpoints de login e documentação ficam, por exemplo:
  • Login: https://<domínio>/ecosif-auth/api/auth/signin
  • Swagger UI: https://<domínio>/ecosif-auth/swagger-ui.html
  • OpenAPI JSON: https://<domínio>/ecosif-auth/v3/api-docs

3.3 Flyway e primeira implantação

  • Na primeira vez que a nova imagem for executada contra a base de dados:
  • Se ECOSIF_FLYWAY_ENABLED=true (recomendado na primeira vez): o Flyway aplica todas as migrações ainda pendentes (V0.6.00.0 até V0.7.00.4, consoante o estado da base).
  • Se a base já existir com schema antigo, o Flyway faz baseline quando configurado baseline-on-migrate: true (já definido no projeto) e aplica apenas migrações com versão superior ao baseline.
  • Recomendação: fazer backup da base antes da primeira implantação da nova versão e validar em ambiente de teste.
  • Após as migrações estarem aplicadas, pode definir ECOSIF_FLYWAY_ENABLED=false em produção se a política for não executar migrações em cada deploy (gerir migrações em janela de manutenção).

3.4 Docker e imagem

  • Imagem base: Amazon Corretto 17 (em vez de 11).
  • Entrypoint: o contentor usa conf/entrypoint-simple.sh; não utiliza o antigo env.template dentro da imagem.
  • Porta: continua 8080 por defeito; configurável via ECOSIF_AUTH_PORT.
  • Health check: no Dockerfile o health check usa o path do Actuator; em ambiente com context path, o ALB/API Gateway deve usar /<context-path>/actuator/health (ex.: /ecosif-auth/actuator/health).

3.5 Dependência local (ecosif-database)

  • O build da aplicação requer o JAR ecosif-database-0.7.01.202512010.jar (ou versão compatível indicada no pom.xml) na pasta libs/.
  • Em ambiente de build (CI/CD ou Docker build), essa dependência deve estar disponível; em runtime apenas o JAR da aplicação (ecosif-authapp) é necessário.

4. Checklist de atualização (0.6.00.x → 0.7.01.x)

  • [ ] Variáveis de ambiente: substituir todas as variáveis antigas (minúsculas) pelas novas (MAIÚSCULAS) na task definition, docker-compose ou arquivo de configuração.
  • [ ] Context path: definir SERVER_SERVLET_CONTEXT_PATH=/ecosif-auth (ou o path acordado) se o serviço for exposto via API Gateway.
  • [ ] Health check: atualizar o path para /ecosif-auth/actuator/health (ou o path correspondente) no ALB, API Gateway ou orquestrador.
  • [ ] Flyway: na primeira implantação, garantir que ECOSIF_FLYWAY_ENABLED=true e que o utilizador da base tem permissão para criar/alterar tabelas; fazer backup da base antes.
  • [ ] CORS: confirmar que ECOSIF_CORS contém a URL exata do frontend (ex.: https://app.ecosif.banco.com.br).
  • [ ] JWT: manter ou gerar uma nova AUTH_TOKEN_SECRET forte (256 bits recomendado); a mesma chave deve ser usada em todos os serviços que validam o JWT.
  • [ ] Runtime: garantir que o ambiente de execução (host, ECS, Kubernetes) usa Java 17 (ou a imagem Docker Corretto 17 fornecida).
  • [ ] Documentação: após o deploy, validar acesso a /ecosif-auth/swagger-ui.html e /ecosif-auth/actuator/health conforme o context path configurado.