Autenticação & Autorização API¶
Arquivos Referenciados Neste Documento - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/service/deps.py - apps/service/app.py - apps/service/main.py
Tabela de Conteúdo¶
- Introdução
- Estrutura do Projeto
- Componentes Principais
- Visão Geral da Arquitetura
- Análise Detalhada dos Componentes
- Análise de Dependências
- Considerações de Desempenho
- Guia de Solução de Problemas
- Conclusão
- Apêndices
Introdução¶
Este documento fornece documentação abrangente da API para o sistema de autenticação e autorização do Nexo. Ele cobre login com validação de nome de usuário/senha, emissão e atualização de tokens JWT, registro de usuário, redefinição de senha, gerenciamento de sessão, controle de acesso baseado em função (RBAC), endpoints de gerenciamento de perfil, cabeçalhos de segurança, políticas CORS, estratégias de limitação de taxa, tratamento de token do lado do cliente, respostas de erro e práticas recomendadas de segurança.
Estrutura do Projeto¶
As funcionalidades de autenticação e autorização são implementadas dentro da camada de serviço: - Rotas definem pontos de extremidade HTTP para operações de autenticação e usuário. - Esquemas compartilhados definem modelos de solicitação/resposta. - Modelos compartilhados definem entidades persistentes. - Injeção de dependência conecta utilitários de segurança e sessões de banco de dados às rotas. - Configuração do aplicativo registra middleware e roteadores.
graph TB
subgraph "Camada de Serviço"
A["routes/auth.py"]
B["routes/users.py"]
C["deps.py"]
D["app.py"]
E["main.py"]
end
subgraph "Compartilhado"
F["schemas/auth.py"]
G["schemas/user.py"]
H["models/user.py"]
end
A --> F
A --> C
B --> G
B --> H
D --> A
D --> B
E --> D
Fontes do Diagrama - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/deps.py - apps/service/app.py - apps/service/main.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py
Fontes da Seção - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/deps.py - apps/service/app.py - apps/service/main.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py
Componentes Principais¶
- Rotas de autenticação: login, logout, atualização de token, redefinição de senha e fluxos relacionados.
- Rotas de usuário: registro, atualizações de perfil, alterações de senha, configurações de conta.
- Esquemas: cargas de solicitação/resposta validadas para operações de autenticação e usuário.
- Modelos: entidade de usuário usada pela persistência e lógica de negócios.
- Dependências: utilitários de segurança compartilhados (por exemplo, ajudantes JWT, hash de senha) e provedores de sessão de banco de dados.
- Fiação do aplicativo: registro de middleware (CORS, cabeçalhos de segurança, limitação de taxa) e montagem de roteador.
Responsabilidades principais: - Validar credenciais e emitir tokens de acesso de curta duração e tokens de atualização de longa duração. - Impor RBAC por meio de contexto de usuário atual injetado por dependência e verificações de permissão. - Fornecer fluxos de alteração/redefinição de senha seguros. - Manter respostas de erro consistentes e códigos de status.
Fontes da Seção - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/service/deps.py - apps/service/app.py
Visão Geral da Arquitetura¶
Fluxo de alto nível para solicitações autenticadas: - Cliente envia solicitação com um token de acesso. - Middleware de segurança valida o token e resolve o usuário atual e funções. - Manipulador de rota executa lógica de negócios com verificações de RBAC. - Resposta inclui cabeçalhos de segurança apropriados.
sequenceDiagram
participant Cliente as "Cliente"
participant Roteador as "Roteadores de Autenticação/Usuário"
participant Deps as "Dependências de Segurança"
participant Modelo as "Modelo de Usuário/Banco de Dados"
participant Aplicativo as "Middleware do Aplicativo"
Cliente->>Roteador : "POST /autenticação/login"
Roteador->>Modelo : "Validar credenciais"
Modelo-->>Roteador : "Registro de usuário"
Roteador->>Deps : "Emitir tokens de acesso + atualização"
Roteador-->>Cliente : "{token_de_acesso, token_de_atualização}"
Cliente->>Roteador : "GET /usuários/me"
Roteador->>Deps : "Verificar token de acesso"
Deps->>Modelo : "Carregar usuário atual"
Modelo-->>Deps : "Objeto de usuário"
Roteador-->>Cliente : "Dados do perfil"
Fontes do Diagrama - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/deps.py - apps/shared/models/user.py - apps/service/app.py
Análise Detalhada dos Componentes¶
Pontos de Extremidade de Autenticação¶
- Login: Valida nome de usuário/senha, retorna tokens de acesso e atualização.
- Atualização de Token: Aceita um token de atualização válido para obter um novo token de acesso.
- Logout: Invalida ou expira o token de atualização se uma sessão no lado do servidor for usada.
- Redefinição de Senha: Inicia o fluxo de redefinição (token/e-mail) e completa a redefinição.
Destaque da solicitação/resposta: - Carga de login inclui campos de nome de usuário e senha definidos no esquema de autenticação. - Respostas incluem tipos de token e metadados de expiração. - Erros incluem credenciais inválidas e solicitações malformadas.
flowchart TD
Start(["Solicitação de Login"]) --> Validate["Validar nome de usuário/senha"]
Validate --> Valid{"Válido?"}
Valid -- "Não" --> Err["Retornar 401 Não Autorizado"]
Valid -- "Sim" --> Issue["Emitir tokens de acesso + atualização"]
Issue --> Resp["Retornar tokens e expiração"]
Resp --> End(["Concluído"])
Fontes do Diagrama - apps/service/routes/auth.py - apps/shared/schemas/auth.py
Fontes da Seção - apps/service/routes/auth.py - apps/shared/schemas/auth.py
Registro de Usuário¶
- Ponto de extremidade cria um novo usuário com campos validados do esquema de usuário.
- Senhas são armazenadas antes do armazenamento usando a estratégia de hash configurada.
- Retorna a representação do usuário criado sem campos sensíveis.
Cenários de erro: - Nome de usuário ou e-mail duplicado. - Falhas de validação em campos de entrada.
Fontes da Seção - apps/service/routes/users.py - apps/shared/schemas/user.py - apps/shared/models/user.py
Fluxo de Redefinição de Senha¶
- Iniciar redefinição: gera um token de redefinição limitado no tempo e o armazena com segurança.
- Concluir redefinição: verifica o token, impõe a política de senha, atualiza o hash de senha.
Considerações de segurança: - Tokens devem ser de curta duração e de uso único. - Limite a taxa de tentativas de redefinição por usuário/IP.
Fontes da Seção - apps/service/routes/auth.py - apps/shared/schemas/auth.py
Gerenciamento de Perfil¶
- Obter perfil: retorna dados do perfil não sensíveis do usuário atual.
- Atualizar perfil: permite atualizar campos seguros; rejeita alterações sensíveis, a menos que autorizado.
- Alterar senha: exige verificação da senha atual e impõe a política.
- Configurações de conta: alterna preferências quando aplicável.
Controle de acesso: - Usuários podem atualizar seus próprios perfis. - Administradores podem gerenciar perfis de outros usuários com base no RBAC.
Fontes da Seção - apps/service/routes/users.py - apps/shared/schemas/user.py - apps/shared/models/user.py
Controle de Acesso Baseado em Função (RBAC)¶
- Funções são anexadas a usuários e impostas por meio do contexto de usuário atual injetado por dependência.
- Verificações de permissão ocorrem no nível da rota ou por meio de decoradores/middleware.
- Funções comuns incluem administrador e usuário regular; permissões mapeiam ações como gerenciar_usuários, atualizar_perfil, etc.
Padrão de implementação: - Usuário atual resolvido do token de acesso. - Guardas de função/permissão opcionais validam o acesso antes da execução da rota.
classDiagram
class Usuário {
+id
+nome_de_usuário
+e-mail
+funções
+is_ativo
}
class AutenticaçãoDeps {
+get_usuario_atual(token)
+exigir_função(função)
+exigir_permissão(permissão)
}
class AutenticaçãoRotas {
+login()
+atualizar()
+redefinir_senha()
}
class UsuárioRotas {
+registrar()
+obter_perfil()
+atualizar_perfil()
+alterar_senha()
}
AutenticaçãoRotas --> AutenticaçãoDeps : "usa"
UsuárioRotas --> AutenticaçãoDeps : "usa"
AutenticaçãoDeps --> Usuário : "carrega"
Fontes do Diagrama - apps/service/deps.py - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/models/user.py
Fontes da Seção - apps/service/deps.py - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/models/user.py
Gerenciamento de Sessão¶
- Tokens de acesso stateless carregam declarações mínimas (id do usuário, funções).
- Tokens de atualização podem ser armazenados no lado do servidor para revogação e rotação.
- Logout invalida tokens de atualização quando aplicável.
Práticas recomendadas: - Vidas úteis de token de acesso curtas. - Cookies seguros, HttpOnly para tokens de atualização quando baseados em navegador. - Rotação na atualização para mitigar o roubo de token.
Fontes da Seção - apps/service/routes/auth.py - apps/service/deps.py
Cabeçalhos de Segurança, CORS e Limitação de Taxa¶
- Cabeçalhos de segurança: configure cabeçalhos de resposta padrão (por exemplo, opções de tipo de conteúdo, transporte estrito, opções de quadro, proteção XSS).
- CORS: lista de origens permitidas, métodos e cabeçalhos; restringe o uso de credenciais.
- Limitação de taxa: aplique limites por ponto de extremidade ou globais para proteger login, atualização e redefinição de senha.
Pontos de configuração: - Inicialização do aplicativo registra middleware e define padrões. - Variáveis de ambiente controlam origens permitidas e limites.
Fontes da Seção - apps/service/app.py - apps/service/main.py
Análise de Dependências¶
As rotas de autenticação e usuário dependem de esquemas e modelos compartilhados e usam injeção de dependência para acesso a segurança e banco de dados. O aplicativo conecta roteadores e middleware.
graph LR
Autenticação["routes/auth.py"] --> EsquemaAutenticação["schemas/auth.py"]
Usuário["routes/users.py"] --> EsquemaUsuário["schemas/user.py"]
Usuário --> ModeloUsuário["models/user.py"]
Autenticação --> Dependências["deps.py"]
Usuário --> Dependências
Aplicativo["app.py"] --> Autenticação
Aplicativo --> Usuário
Principal["main.py"] --> Aplicativo
Fontes do Diagrama - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/service/deps.py - apps/service/app.py - apps/service/main.py
Fontes da Seção - apps/service/routes/auth.py - apps/service/routes/users.py - apps/shared/schemas/auth.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/service/deps.py - apps/service/app.py - apps/service/main.py
Considerações de Desempenho¶
- Mantenha tokens de acesso pequenos; evite armazenar declarações grandes.
- Use algoritmos de hash eficientes com fatores de custo apropriados para senhas.
- Cache atributos de usuário frequentemente acessados onde for seguro.
- Aplique limitação de taxa para reduzir o risco de força bruta e proteger recursos.
- Prefira tokens de acesso stateless; armazene apenas o estado do servidor necessário para tokens de atualização.
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]
Guia de Solução de Problemas¶
Problemas comuns e resoluções: - Credenciais inválidas: verifique nome de usuário/senha e certifique-se de que a conta esteja ativa. - Token de acesso expirado: atualize usando o ponto de extremidade de token de atualização; lidar com respostas 401 de forma elegante. - Token de atualização inválido ou revogado: solicite re-login; limpe tokens locais. - Erros CORS: confirme que a origem esteja na lista de permissões e o modo de credenciais corresponda à política do servidor. - Taxa limite excedida: retroceda e tente novamente após um atraso; implemente retrocesso exponencial.
Dicas operacionais: - Registre tentativas de login com falha com detalhes sanitizados. - Monitore taxas de sucesso/falha de token de atualização. - Auditoria de negações de RBAC para uso potencial.
Fontes da Seção - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/app.py
Conclusão¶
O sistema de autenticação e autorização do Nexo combina acesso stateless baseado em JWT com gerenciamento de token de atualização opcional no lado do servidor, aplicação de RBAC, e configurações de segurança robustas. Ao seguir os fluxos documentados, padrões de tratamento de erro e práticas recomendadas, os clientes podem implementar integrações seguras e resilientes.
[Nenhuma fonte necessária, pois esta seção resume sem analisar arquivos específicos]
Apêndices¶
Fluxos de Autenticação de Exemplo¶
- Login: envie nome de usuário/senha; receba tokens de acesso e atualização; armazene com segurança.
- Chamada protegida: inclua token de acesso no cabeçalho de Autorização; lidar com 401 atualizando.
- Atualização: apresente token de atualização; receba novo token de acesso; rotule token de atualização se suportado.
- Logout: invalide token de atualização se aplicável; limpe tokens locais.
[Nenhuma fonte necessária, pois esta seção fornece exemplos conceituais]
Respostas de Erro¶
- 400 Solicitação Ruim: entrada malformada ou falha de validação.
- 401 Não Autorizado: credenciais ou token inválidos.
- 403 Proibido: permissões ou funções insuficientes.
- 404 Não Encontrado: recurso não encontrado.
- 409 Conflito: nome de usuário/e-mail duplicado.
- 429 Muitas Solicitações: taxa limite excedida.
- 500 Erro Interno do Servidor: erro de servidor inesperado.
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]
Práticas Recomendadas de Segurança¶
- Hash de senhas com um algoritmo forte e fator de trabalho apropriado.
- Use HTTPS em todos os lugares; impõe HSTS.
- Defina flags de cookie seguros para tokens de atualização (HttpOnly, Secure, SameSite).
- Minimize tempo de vida e escopo do token; rotule tokens de atualização.
- Valide e sanitize todas as entradas; rejeite valores não seguros.
- Implemente limitação de taxa e limiares de bloqueio de conta.
- Evite registrar segredos ou tokens.
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]