Introdução para Integradores - ecosif-auth

Atualizado (MVP1): login externo via POST /api/auth/external-login. Legado signin-azure removido. Ver autenticacao.md.

Bem-vindo!

Este documento fornece uma visão geral do serviço ecosif-auth para integradores que desejam utilizar a API.

O que é o ecosif-auth?

O ecosif-auth é o serviço central de autenticação e autorização do ecossistema eCosif. Ele fornece:

• Autenticação de usuários através de múltiplos métodos (local, Azure AD, OAuth2)
• Emissão de tokens JWT para acesso aos serviços ecosif
• Validação de tokens para outros serviços do ecossistema

Por que usar o ecosif-auth?

• ✅ Segurança: Autenticação robusta com tokens JWT
• ✅ Multi-método: Suporte a autenticação local, Azure AD e OAuth2
• ✅ Stateless: Tokens JWT não requerem sessão no servidor
• ✅ Bem documentado: API REST completa com Swagger/OpenAPI
• ✅ Padrões: Segue padrões REST e JWT amplamente adotados

Como Funciona

Fluxo Básico

1. Login: Cliente faz login enviando credenciais
2. Token: Serviço retorna token JWT
3. Uso: Cliente usa token em requisições para serviços ecosif
4. Validação: Cada serviço valida o token automaticamente

┌─────────┐         ┌──────────────┐         ┌─────────────┐
│ Cliente │────────>│ ecosif-auth  │────────>│   Token     │
│         │  Login  │              │         │    JWT      │
└─────────┘         └──────────────┘         └─────────────┘
     │                                           │
     │                                           │
     │         ┌─────────────────────────────────┘
     │         │
     ▼         ▼
┌──────────────────────────────────────┐
│  Outros Serviços ecosif              │
│  (validam token automaticamente)     │
└──────────────────────────────────────┘

Endpoints Principais

Autenticação

• POST /api/auth/signin: Autenticação local ou Azure AD
• POST /api/auth/signin: Autenticação local (usuário/senha)
• POST /api/auth/external-login: Login Microsoft/Google (id_token → JWT ECOSIF)

Documentação

• GET /swagger-ui.html: Interface interativa Swagger UI
• GET /v3/api-docs: Especificação OpenAPI 3.0 em JSON

Métodos de Autenticação

1. Autenticação Local

Usuário e senha armazenados no sistema: - Ideal para ambientes internos - Requer que usuário já esteja cadastrado

2. Autenticação Azure AD

Integração com Microsoft Azure Active Directory: - Ideal para empresas que usam Azure AD - Suporta criação automática de usuários - Não requer senha (Azure valida)

3. OAuth2 (Google)

Login via conta Google: - Ideal para aplicações que preferem SSO social - Configuração opcional

Tokens JWT

O que é JWT?

JWT (JSON Web Token) é um padrão aberto para transmitir informações de forma segura entre partes.

Estrutura do Token

O token JWT retornado contém:

• Header: Metadados (algoritmo, tipo)
• Payload: Claims (username, expiração, etc.)
• Signature: Assinatura para validação

Validade

• Padrão: 30 minutos
• Configurável: Via variável TOKEN_EXPIRATION

Após expirar, é necessário fazer login novamente.

Base URL

• Desenvolvimento: http://localhost:8080
• Produção: Configure conforme seu ambiente

Autenticação em Requisições

Para usar endpoints protegidos, inclua o token no header:

Authorization: Bearer <seu-token-jwt>

Exemplo:

GET /api/admin/docker-logs?service=ecosif-auth
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c3VhcmlvQGV4ZW1wbG8uY29tIiwiaWF0IjoxNjQwMDAwMDAwLCJleHAiOjE2NDAwMTgwMDB9.xyz

Códigos de Status HTTP

• 200 OK: Requisição bem-sucedida
• 201 Created: Recurso criado com sucesso
• 400 Bad Request: Dados inválidos
• 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

Formato de Respostas

Sucesso

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

Erro

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

Próximos Passos

Para começar a integrar:

1. Autenticação: Aprenda a autenticar usuários
2. Uso da API: Saiba como usar a API
3. Exemplos: Veja exemplos práticos
4. Erros Comuns: Resolva problemas frequentes

Recursos Adicionais

• Swagger UI: Interface interativa para testar a API
• OpenAPI Spec: Especificação completa da API
• Documentação de Endpoints: Lista completa de endpoints

Suporte

Para suporte: - Consulte a documentação completa em /docs - Teste endpoints no Swagger UI - Entre em contato com a equipe de desenvolvimento

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 com antecedência.