Documentação técnica • Autor: Leonardo Norbiato - Equipe de Engenharia
Cliente: Aster Technology / UVA Última Atualização: 15/09/2025 Autores: Leonardo Norbiato - Equipe de Engenharia

microservice-auth

Microserviço de autenticação e autorização — Go/Gin/JWT

Índice

1. OBJETIVO DO REPOSITÓRIO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-auth", um microserviço desenvolvido em Go que gerencia autenticação, autorização e controle de acesso baseado em perfis e permissões. O serviço implementa JWT com access/refresh tokens, sistema de roles/perfis (RBAC), multi-tenancy, rate limiting, recuperação de senha e integração com Redis para cache de tokens. Atua como serviço central de autenticação para todo o ecossistema Aster/UVA, fornecendo controle granular de permissões por módulo, rota e método HTTP.

2. ÚLTIMA REVISÃO

3. TECNOLOGIAS UTILIZADAS

Backend
Go 1.22.0, Gin v1.10.0 (HTTP framework), GORM v1.25.12 (ORM)
PostgreSQL (driver: gorm.io/driver/postgres v1.5.11)
JWT (golang-jwt/jwt/v5 v5.2.1), Redis (go-redis/v9 v9.0.4)
Swagger (swaggo/gin-swagger v1.6.0, swaggo/swag v1.16.4)
Rate limiting (ulule/limiter/v3 v3.11.2), Logging (sirupsen/logrus v1.9.3)
UUID (google/uuid v1.6.0), Validação (go-playground/validator/v10 v10.23.0)
Configuração (joho/godotenv v1.5.1), Testes (stretchr/testify v1.10.0)
Repositórios: GitHub (aster-technology/microservice-auth)
Frontend
Não aplicável (API pura)
Banco de Dados
PostgreSQL 13 (principal), Redis (cache de tokens e sessões)
Ferramentas de Conexão e Infraestrutura
Docker Compose (PostgreSQL + Redis + App), Nginx (preparado), SSL/TLS (preparado)
Rede compartilhada: astor_shared_network

4. FUNCIONALIDADES E DOMÍNIOS

Domínios Principais:

Funcionalidades Técnicas:

5. ARQUITETURA FRONTEND

6. ARQUITETURA BACKEND

Controllers/Handlers:

Repositories:

Entities:

Helper/Utilities:

7. ROTAS E ENDPOINTS

Rotas Públicas:

Rotas Autenticadas (JWT):

Gestão de Perfis:

Gestão de Módulos:

Gestão de Permissões:

Rotas Super Admin:

Documentação:

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

users:
id (string, PK), username, email (unique), password_hash, plan, is_active, is_delinquent, is_admin, is_super_admin, is_owner, canceled, tenant_id, created_at, updated_at
profiles:
id (uint, PK), name (unique), created_at, updated_at
user_profiles:
user_id (string, PK), profile_id (uint, PK) - Relacionamento N:N entre users e profiles
modules:
id (uint, PK), name (unique), route, created_at, updated_at
permissions:
id (uint, PK), module_id, label, slug (unique), route, method, group, group_name, dependencies, created_at, updated_at
profile_permissions:
id (uint, PK), profile_id, permission_id, allowed, created_at, updated_at
user_permissions:
id (uint, PK), user_id, permission_id, allowed, created_at, updated_at
password_reset_tokens:
id (uint, PK), user_id, token, expires_at, created_at

9. CONFIGURAÇÃO E VARIÁVEIS

Arquivo principal: docker-compose.yml

Variáveis principais:

Configurações Docker:

10. TREEVIEW DA ARQUITETURA

microservice-auth/
├── cmd/
│   └── auth-service/
│       └── main.go                    # Ponto de entrada da aplicação
├── internal/
│   ├── adapters/
│   │   ├── handlers/                  # Handlers HTTP (13 arquivos)
│   │   │   ├── login_handler.go       # Autenticação
│   │   │   ├── register_handler.go    # Registro de usuários
│   │   │   ├── refresh_token_handler.go # Renovação de tokens
│   │   │   ├── forgot_password_handler.go # Solicitação de reset
│   │   │   ├── reset_password_handler.go # Reset de senha
│   │   │   ├── user_handler.go        # CRUD de usuários
│   │   │   ├── profile_handler.go     # Gestão de perfis
│   │   │   ├── permission_handler.go  # Gestão de permissões
│   │   │   ├── module_handler.go      # Gestão de módulos
│   │   │   ├── impersonate_handler.go # Impersonação
│   │   │   ├── routes.go              # Configuração de rotas
│   │   │   ├── token_helper.go        # Utilitários de token
│   │   │   └── permission_helper.go   # Utilitários de permissão
│   │   ├── repositories/              # Implementações de repositórios (6 arquivos)
│   │   │   ├── user_repository_impl.go
│   │   │   ├── profile_repository_impl.go
│   │   │   ├── permission_repository_impl.go
│   │   │   ├── module_repository_impl.go
│   │   │   ├── password_reset_token_repository_impl.go
│   │   │   └── profile_permission_repository_impl.go
│   │   └── seeds/                     # Seeds de dados iniciais
│   │       ├── executor.go            # Executor de seeds
│   │       ├── clean_data/clean.go    # Limpeza de dados
│   │       ├── modules_permissions/   # Seeds de módulos e permissões
│   │       └── profiles/              # Seeds de perfis
│   ├── config/
│   │   └── config.go                  # Configuração da aplicação
│   ├── domain/
│   │   ├── entities/                  # Entidades de domínio (3 arquivos)
│   │   │   ├── user.go                # Entidade User
│   │   │   ├── permission_entities.go # Entidades de permissões
│   │   │   └── password_reset_token.go # Token de reset
│   │   ├── interfaces/                # Interfaces de repositórios
│   │   │   └── interfaces.go
│   │   └── models/                    # Modelos de dados (4 arquivos)
│   │       ├── user_models.go
│   │       ├── permission_models.go
│   │       ├── profile_permission_models.go
│   │       └── module_models.go
│   ├── usecases/                      # Casos de uso (10 arquivos)
│   │   ├── authenticate_user.go       # Autenticação
│   │   ├── register_user.go           # Registro
│   │   ├── update_user.go             # Atualização
│   │   ├── delete_user.go             # Exclusão
│   │   ├── impersonate.go             # Impersonação
│   │   ├── request_password_reset.go  # Solicitação de reset
│   │   ├── reset_password.go          # Reset de senha
│   │   ├── create_profile.go          # Criação de perfil
│   │   ├── get_modules_and_profiles.go # Busca de módulos
│   │   └── user_permissions.go        # Permissões do usuário
│   └── utils/
│       └── string_utils.go            # Utilitários de string
├── pkg/
│   └── middleware/                    # Middlewares (3 arquivos)
│       ├── auth_middleware.go         # Middleware de autenticação
│       ├── role_middleware.go         # Middleware de roles
│       └── inadimplency_middleware.go # Middleware de inadimplência
├── docs/                              # Documentação Swagger
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── docker-compose.yml                 # Orquestração de serviços
├── Dockerfile                         # Build da aplicação
├── nginx.conf                         # Configuração Nginx
├── nginx.Dockerfile                   # Build Nginx
├── go.mod                             # Dependências Go
├── go.sum                             # Checksums das dependências
└── README.md                          # Documentação do projeto

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos:

Dependências principais:

12. INTEGRAÇÕES EXTERNAS

13. CONTROLE DE VERSÃO

14. SEGURANÇA E ACESSO

15. CONSIDERAÇÕES FINAIS

O microservice-auth é um microserviço robusto e bem estruturado em Go que implementa um sistema completo de autenticação e autorização. Oferece controle de acesso baseado em perfis (RBAC), sistema de permissões granulares, multi-tenancy e integração com Redis para cache.

Principais pontos fortes:

O serviço está preparado para produção e integração com o ecossistema de microserviços Aster/UVA, fornecendo autenticação e autorização centralizadas para todos os outros serviços.

Retornar para home