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¶

Login: Cliente faz login enviando credenciais
Token: Serviço retorna token JWT
Uso: Cliente usa token em requisições para serviços ecosif
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:

Autenticação: Aprenda a autenticar usuários
Uso da API: Saiba como usar a API
Exemplos: Veja exemplos práticos
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.