eCosif — Autenticação

Uso da API - Guia para Integradores

Endpoints atuais: POST /api/auth/signin (local) e POST /api/auth/external-login (IdP). Ver autenticacao.md.

Este guia explica como usar a API do ecosif-auth para autenticação e operações administrativas.

Autenticação

Todos os endpoints protegidos requerem autenticação via token JWT no header:

Authorization: Bearer <seu-token-jwt>

Veja Autenticação para obter um token.

Endpoints Disponíveis

Autenticação

POST /api/auth/signin

Autentica um usuário e retorna token JWT.

Autenticação: Não requerida

Métodos suportados: - Autenticação local (username/password) - Autenticação Azure AD (username apenas)

Exemplo:

curl -X POST http://localhost:8080/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario@exemplo.com",
    "password": "senha123",
    "azure": false
  }'

Veja Autenticação para mais detalhes.

POST /api/auth/external-login

Login externo (Microsoft/Google). Envie o id_token obtido no browser.

Autenticação: Não requerida

Exemplo:

curl -X POST http://localhost:8080/api/auth/external-login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AZURE",
    "token": "<id_token>",
    "tokenType": "ID_TOKEN"
  }'

Veja Autenticação para mais detalhes.

Administrativos

GET /api/admin/docker-logs

Obtém logs de um container Docker.

Autenticação: Requerida (Bearer Token)

Parâmetros: - service (query, obrigatório): Nome do serviço - lines (query, opcional): Número de linhas (padrão: 100, máximo: 1000)

Serviços disponíveis: - ecosif-auth - ecosif-masterdata - ecosif-moviments - ecosif-querys - ecosif-reports - ecosif-compliance - ecosif-angular - nginx - postgres

Exemplo:

TOKEN="seu-token-jwt"

curl -X GET "http://localhost:8080/api/admin/docker-logs?service=ecosif-auth&lines=100" \
  -H "Authorization: Bearer $TOKEN"

Resposta:

{
  "service": "ecosif-auth",
  "containerName": "ecosif-auth",
  "lines": 100,
  "logs": "2024-01-01 10:00:00.000 INFO  [main] Application started...\n..."
}

GET /api/admin/docker-logs/services

Lista serviços disponíveis para visualização de logs.

Autenticação: Requerida (Bearer Token)

Exemplo:

TOKEN="seu-token-jwt"

curl -X GET "http://localhost:8080/api/admin/docker-logs/services" \
  -H "Authorization: Bearer $TOKEN"

Resposta:

{
  "services": [
    "ecosif-auth",
    "ecosif-masterdata",
    "ecosif-moviments",
    "ecosif-querys",
    "ecosif-reports",
    "ecosif-compliance",
    "ecosif-angular",
    "nginx",
    "postgres"
  ],
  "serviceToContainer": {
    "ecosif-auth": "ecosif-auth",
    "postgres": "ecosif-postgres"
  }
}

Monitoramento

GET /actuator/health

Health check da aplicação.

Autenticação: Não requerida

Exemplo:

curl http://localhost:8080/actuator/health

Resposta:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    }
  }
}

GET /actuator/info

Informações da aplicação.

Autenticação: Não requerida

GET /actuator/prometheus

Métricas Prometheus.

Autenticação: Não requerida

Documentação

GET /swagger-ui.html

Interface Swagger UI para testes interativos.

Autenticação: Não requerida

Acesso: Abra no navegador: http://localhost:8080/swagger-ui.html

GET /v3/api-docs

Especificação OpenAPI 3.0 em formato JSON.

Autenticação: Não requerida

Exemplo:

curl http://localhost:8080/v3/api-docs

Formato de Requisições

Content-Type

Todas as requisições POST devem usar:

Content-Type: application/json

Body JSON

Exemplo de body para requisições POST:

{
  "campo1": "valor1",
  "campo2": "valor2"
}

Formato de Respostas

Sucesso (200 OK)

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "1",
    "displayName": "João Silva",
    "email": "joao.silva@exemplo.com",
    "roles": ["ADMIN"],
    "tenant": "empresa-exemplo"
  },
  "tenantName": "empresa-exemplo"
}

Erro (400/401/404/500)

{
  "success": false,
  "message": "Mensagem de erro descritiva"
}

Códigos de Status HTTP

Código Significado Quando Ocorre
200 OK Requisição bem-sucedida
201 Created Recurso criado com sucesso
400 Bad Request Dados inválidos ou incompletos
401 Unauthorized Não autenticado ou credenciais inválidas
403 Forbidden Não autorizado
404 Not Found Recurso não encontrado
500 Internal Server Error Erro interno do servidor

Tratamento de Erros

Erro 401 (Unauthorized)

Token inválido ou expirado:

if (response.status === 401) {
  // Fazer login novamente
  const loginResponse = await fazerLogin();
  // Tentar requisição novamente com novo token
}

Erro 400 (Bad Request)

Dados inválidos:

if (response.status === 400) {
  const error = await response.json();
  console.error('Erro:', error.message);
  // Exibir mensagem para o usuário
}

Erro 500 (Internal Server Error)

Erro do servidor:

if (response.status === 500) {
  // Log do erro e notificar administrador
  console.error('Erro interno do servidor');
}

Rate Limiting

Atualmente, não há rate limiting implementado. Em produção, considere implementar no lado do cliente.

Timeouts

Configure timeouts apropriados nas requisições:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 segundos

fetch(url, {
  signal: controller.signal
})
.then(response => {
  clearTimeout(timeoutId);
  return response.json();
});

Retry Logic

Para operações críticas, implemente retry logic:

async function fazerRequisicaoComRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) {
        return await response.json();
      }
      if (response.status === 401) {
        // Token expirado, fazer login novamente
        await renovarToken();
        options.headers.Authorization = `Bearer ${novoToken}`;
        continue;
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Versão da API

Versão atual: 0.7.01.202511271

A API segue versionamento semântico. Mudanças que quebram compatibilidade serão sinalizadas.

Próximos Passos