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.