Implemente a autenticação JWT em APIs Node.js como um profissional

Início » Python » Implemente a autenticação JWT em APIs Node.js como um profissional

Se você estiver criando APIs com Node.js, adicionar autenticação adequada com JWT pode parecer assustador no início, mas na verdade não precisa ser. Com algumas bibliotecas bem escolhidas, uma estrutura clara e boas práticas de validação e segurança, você pode proteger seus endpoints e ainda manter seu código limpo e de fácil manutenção.

Neste guia, vamos mostrar como implementar a autenticação baseada em JWT em uma API Node.js usando Express, MongoDB e ferramentas como jsonwebtoken, bcrypt, Joi e dotenv. Também veremos como validar tokens usando um endpoint JWKS de um servidor de autorização em cenários mais voltados para empresas. Você aprenderá como projetar a estrutura do projeto, criar modelos e rotas, gerar e verificar tokens, adicionar um middleware de autenticação e integrar tudo para que apenas usuários autenticados possam acessar recursos protegidos.

O que os JSON Web Tokens (JWT) trazem para suas APIs Node.js

Os JSON Web Tokens (JWT) são tokens compactos e seguros para URLs que contêm um conjunto de declarações e permitem que duas partes troquem informações autenticadas sem manter o estado da sessão no servidor. Em um contexto de API Node.js, isso significa que, uma vez que um usuário faça login e você emita um JWT, todas as solicitações subsequentes podem ser verificadas pelo seu backend usando apenas o próprio token e uma chave secreta ou pública, o que é muito mais escalável do que as sessões de servidor tradicionais.

Um JWT típico é composto por três partes: um cabeçalho, uma carga útil e uma assinatura, todas codificadas em Base64URL e separadas por pontos, por exemplo. xxxxx.yyyyy.zzzzz. O cabeçalho geralmente especifica o algoritmo e o tipo de token, a carga útil contém informações relacionadas ao usuário, como um ID, funções ou permissões, e a assinatura garante a integridade, de modo que o token não possa ser adulterado sem ser detectado.

Ao implementar JWT em APIs Node.js, normalmente você usa o token como um token de portador (bearer token) no Authorization Cabeçalho HTTP, como Authorization: Bearer <token>E então, decodifique e valide-o dentro do seu middleware do Express ou dos seus manipuladores de rotas. Se o token for válido, você poderá anexar a carga útil decodificada ao objeto de solicitação e usá-la posteriormente para decisões de autorização ou para personalizar a resposta.

Um dos pontos fortes dos JWTs é que eles são independentes de linguagem e têm amplo suporte em diversos ecossistemas, o que os torna uma excelente opção para proteger APIs consumidas por React, Vue, aplicativos móveis ou qualquer cliente de terceiros. Em conjunto com uma validação robusta e um gerenciamento de chaves adequado, permitem que os serviços Node.js participem de forma transparente em arquiteturas baseadas em OAuth 2.0 e OpenID Connect.

Visão geral do projeto: API Node.js com autenticação JWT

Vamos imaginar uma API Node.js simples, porém realista, onde os usuários podem se cadastrar, fazer login e acessar endpoints protegidos somente após apresentar um JWT válido. Utilizaremos o Express para roteamento, o Mongoose para integração com o MongoDB, o jsonwebtoken para criar e verificar tokens, o bcrypt para criptografia segura de senhas, o Joi para validação de entrada e o dotenv para gerenciamento de configuração.

Uma estrutura de pastas bem organizada ajuda a manter a clareza à medida que o projeto cresce. Por isso, em vez de colocar tudo em um único arquivo, definiremos uma estrutura básica com módulos separados para configuração, banco de dados, modelos, rotas e middleware. Essa abordagem modular também facilita a realização de testes unitários em partes específicas do fluxo de autenticação.

Em linhas gerais, a API exporá um conjunto de endpoints REST para cadastro e login de usuários, além de pelo menos um recurso protegido que só poderá ser acessado com um JWT válido nos cabeçalhos da requisição. Ao longo do processo, veremos como validar os dados das requisições, calcular o hash e comparar senhas, gerar tokens que incorporam o ID do usuário e integrar um middleware de autenticação que verifica os tokens nas chamadas recebidas.

O mesmo padrão pode ser estendido a sistemas mais complexos, incluindo aqueles que se integram a um servidor de autorização externo e usam endpoints JWKS para validar tokens de acesso recebidos de clientes OAuth 2.0. Esse segundo cenário é particularmente comum quando você delega a autenticação a provedores de identidade ou precisa oferecer suporte ao login único em vários serviços.

Antes de entrarmos nos detalhes da implementação, vamos descrever as principais partes do ambiente em que nos basearemos e por que cada dependência é importante para o tratamento seguro de JWT no Node.js.

Principais dependências para autenticação JWT em Node.js

O Express é a espinha dorsal de muitas APIs do Node.js, fornecendo uma estrutura minimalista, porém flexível, para roteamento, middleware e tratamento de HTTP. No nosso caso, o Express servirá como plataforma onde registramos rotas como /api/users or /api/authE é aí que inserimos o middleware de verificação JWT que protege os endpoints sensíveis.

Mongoose é uma biblioteca de Modelagem de Dados Orientada a Objetos (ODM) que facilita a interação com o MongoDB por meio de esquemas e modelos, em vez de trabalhar diretamente com consultas brutas. Vamos usá-lo para definir um User Modelo com propriedades como nome, e-mail e senha, e para persistir ou recuperar esses documentos do banco de dados de maneira segura em relação aos tipos.

O método da jsonwebtoken A biblioteca é a escolha padrão em Node.js para criar e verificar JWTs usando uma chave secreta ou pública. Durante o login, assinaremos um token que incorpora o ID do usuário (e quaisquer outras informações necessárias) e, posteriormente, verificaremos esse token em rotas protegidas, rejeitando qualquer solicitação que contenha um token inválido, malformado ou expirado.

Para garantir a segurança das senhas, o bcrypt é usado para criptografar senhas em texto simples antes do armazenamento e para comparar as credenciais fornecidas com os valores criptografados durante a autenticação. Isso é crucial, pois armazenar senhas brutas ou usar estratégias de hash fracas expõe seus usuários a enormes riscos em caso de vazamento de banco de dados, enquanto o bcrypt oferece uma solução comprovada e testada em batalha.

Joi desempenha um papel importante na validação dos dados recebidos na interface da API, descrevendo esquemas para objetos e verificando se cada solicitação se comporta conforme o esperado. Por exemplo, podemos definir que um e-mail deve ser formatado corretamente, que uma senha tem um comprimento mínimo e que certos campos são obrigatórios, o que reduz significativamente as chances de entradas incorretas ou maliciosas passarem despercebidas em nossa lógica.

Finalmente, o dotenv permite carregar variáveis ​​de ambiente de um arquivo. .env arquivo, mantendo segredos como chaves de assinatura JWT, URLs de banco de dados ou configurações fora do código-fonte. Isso ajuda a evitar a codificação fixa de valores sensíveis e promove uma melhor separação entre as configurações de desenvolvimento, teste e produção.

Configurando o servidor e o ambiente Express

O ponto de entrada da nossa API geralmente é um index.js Arquivo onde inicializamos o Express, registramos os middlewares e montamos nossas definições de rota. Neste arquivo, precisaremos da nossa configuração de banco de dados, nossos módulos de roteamento e qualquer middleware global, como análise de corpo JSON ou CORS.

Logo após carregar as dependências, é uma boa ideia chamar require("dotenv").config() então variáveis ​​de ambiente do .env O arquivo ficará disponível através de process.env. Isso inclui chaves como JWT_PRIVATE_KEY, MONGO_URI ou a porta na qual o servidor ficará à escuta, o que mantém a configuração flexível e segura.

O próprio aplicativo Express normalmente usará app.use(express.json()) para analisar corpos de requisições JSON e montar roteadores para prefixos de URL específicos, como app.use("/api/users", usersRouter) e app.use("/api/auth", authRouter). Essa separação mantém as rotas relacionadas à autenticação e as questões de gerenciamento de usuários isoladas de outras partes da API.

Com o ambiente configurado e o Express em execução, o próximo passo é conectar o banco de dados MongoDB por meio de um módulo dedicado, geralmente um `export`. db.js arquivo, onde configuramos a lógica de conexão.

Configurando o MongoDB com o Mongoose

De acordo com o relatório db.js módulo, normalmente importamos Mongoose e chamamos mongoose.connect() com a string de conexão do MongoDB armazenada em uma variável de ambiente. Também podemos configurar opções como lógica de repetição, topologia unificada ou agrupamento de conexões para garantir um comportamento estável em ambientes de produção.

É comum registrar uma mensagem quando a conexão é bem-sucedida e tratar os erros de forma adequada, para que, se o MongoDB estiver inacessível, a API seja iniciada com diagnósticos claros. Em uma aplicação completa, você pode até optar por encerrar o processo se a conexão com o banco de dados falhar, já que muitas rotas dependem dela.

Uma vez que o db.js O arquivo está implementado, nós o importamos de index.js e chamá-la logo no início da inicialização do aplicativo, garantindo que nossa API esteja conectada ao banco de dados antes de processar qualquer solicitação. Essa separação mantém a configuração isolada e reutilizável, enquanto index.js Continua focada nas questões da Express.

Com o banco de dados integrado, podemos prosseguir para a modelagem dos dados que alimentam nosso sistema de autenticação, começando com a definição de um esquema e modelo de usuário.

Construindo o modelo de usuário com suporte a JWT

O método da User modelo, geralmente colocado em /models/user.js, define a estrutura dos documentos do usuário armazenados no MongoDB e encapsula o comportamento relacionado à autenticação. No mínimo, incluiremos propriedades como: name, email e passwordE também podemos adicionar registros de data e hora, funções ou outros metadados conforme necessário.

Uma prática comum é marcar o campo de e-mail como único e obrigatório, garantindo que dois usuários não possam se cadastrar com o mesmo endereço de e-mail. Da mesma forma, o campo de senha não armazenará um valor de texto simples; em vez disso, armazenaremos um hash bcrypt gerado no momento do registro ou quando o usuário atualizar suas credenciais.

Uma decisão de design interessante e muito prática é adicionar um método ao esquema do usuário para gerar JWTs, que recebe o ID do usuário como carga útil e o assina com uma chave secreta definida no ambiente. Este método pode ser chamado durante o login para gerar um token específico para aquele usuário, e mantém a lógica de geração de tokens localizada junto ao modelo que detém os dados de identidade.

Em conjunto com os auxiliares de validação baseados em Joi, o modelo de usuário torna-se a peça central para tudo relacionado à identidade: descrevendo o formato dos dados do usuário, validando as cargas úteis recebidas e gerando tokens usados ​​pelo restante da API.

A partir daqui, podemos implementar as rotas responsáveis ​​por registrar novas contas e autenticar usuários existentes, utilizando o modelo de usuário, bcrypt e Joi em conjunto.

Criando a Rota de Registro

A lógica de registro geralmente reside em um módulo de rota, como por exemplo... /routes/users.js, onde definimos um ponto final como POST /api/users Para processar os pedidos de inscrição recebidos. Essa rota validará a carga útil usando o Joi, verificará se o e-mail já está em uso, calculará o hash da senha, criará o usuário e o salvará no banco de dados.

Antes de persistir qualquer informação, podemos usar um esquema Joi que impõe requisitos como nome e e-mail obrigatórios, formato de e-mail adequado e comprimento mínimo de senha. Caso a validação falhe, a rota responde com um código de erro e uma mensagem adequados, impedindo que dados malformados cheguem à lógica de negócios.

Caso o e-mail ainda não exista, geramos um salt bcrypt e aplicamos um hash à senha, substituindo a senha original pela sua versão criptografada no objeto do usuário. Esse valor criptografado é o que acaba sendo armazenado no MongoDB, o que limita significativamente o impacto de possíveis violações de dados.

Após salvar o novo usuário, algumas implementações também optam por gerar imediatamente um JWT e retorná-lo no cabeçalho ou no corpo da resposta, para que o usuário seja considerado autenticado logo após o registro. Outras APIs podem exigir uma etapa de login separada, dependendo dos requisitos de segurança do sistema.

Após o cadastro, o processo complementar de login pode reutilizar grande parte da mesma lógica de validação, concentrando-se na verificação das credenciais e na emissão de tokens.

Implementando a rota de login e a geração de tokens.

O fluxo de login é normalmente tratado em /routes/auth.js, com um ponto final como POST /api/auth que recebe um e-mail e uma senha no corpo da solicitação. Essa rota utiliza o Joi novamente para garantir que ambos os campos estejam presentes e estruturados corretamente antes de tentar autenticar o usuário.

Após a validação, a rota consulta o banco de dados em busca de um usuário com o e-mail fornecido e, caso encontre um, utiliza o bcrypt para comparar a senha fornecida com o hash armazenado. Se a comparação falhar, a solicitação será rejeitada com uma mensagem de erro apropriada; caso contrário, prosseguimos para a emissão do token.

No momento da autenticação bem-sucedida, chamamos o método de geração de token definido no modelo de usuário, que cria um JWT incorporando o identificador do usuário (e possivelmente outras declarações) e o assina com uma chave secreta. Esse token pode então ser enviado ao cliente, geralmente no corpo da resposta ou em um cabeçalho personalizado, onde o frontend ou o consumidor externo o armazena e reutiliza para solicitações futuras.

Do ponto de vista do cliente, cada chamada subsequente para endpoints protegidos incluirá este JWT no Authorization O cabeçalho contém um token de portador, que é exatamente o que nosso middleware irá procurar. Do lado do servidor, ter um middleware de autenticação dedicado garante que não repetimos a lógica de verificação de token em cada rota.

Antes de nos aprofundarmos nesse middleware, vale a pena notar que esse mesmo padrão se integra bem com o React ou outros frameworks SPA, onde fluxos baseados em JWT são comumente usados ​​tanto para autenticação quanto para necessidades simples de autorização.

Construindo o middleware de autenticação para proteger rotas

O middleware de autenticação, frequentemente implementado em /middleware/auth.js, atua como um guardião para qualquer rota que exija autenticação, interceptando as solicitações antes que elas cheguem ao manipulador de rotas. Sua principal função é ler o JWT do Authorization O cabeçalho é verificado e o conteúdo decodificado é inserido no objeto de requisição para uso posterior.

O middleware começa verificando se o Authorization O cabeçalho existe e segue o esperado. Bearer <token> formato; se o token estiver ausente ou malformado, ele responde imediatamente com um código de status de não autorizado. Isso garante que solicitações não protegidas não entrem acidentalmente em endpoints seguros.

Quando um token está presente, o middleware faz a chamada. jwt.verify() (A partir do jsonwebtoken biblioteca), passando o token e a chave secreta ou pública usada para assinatura. Se a verificação falhar devido à expiração, incompatibilidade de assinatura ou qualquer outro problema, o middleware responde com um erro; caso contrário, ele captura a carga útil decodificada.

Muitas implementações anexam essa carga útil decodificada a req.user ou uma propriedade similar, para que os manipuladores de rotas subsequentes possam acessar as declarações relacionadas ao usuário sem precisar analisar ou verificar o token novamente. Finalmente, o middleware faz chamadas. next() Para passar o controle para a próxima função no pipeline do Express.

Ao combinar esse middleware com as definições de rotas, podemos facilmente marcar alguns endpoints como públicos e outros como protegidos, simplesmente adicionando o middleware à cadeia de tratamento de requisições dessas rotas.

Acessando recursos protegidos com JWT

Um caso de uso comum após a implementação da autenticação é fornecer uma rota que recupere o perfil do usuário atual ou uma lista de usuários, acessível apenas aos chamadores que apresentarem um token válido. Por exemplo, em /routes/users.js, pode haver um GET /api/users/me Ponto de extremidade que retorna informações sobre o usuário conectado.

Para proteger essa rota, anexamos o middleware de autenticação para que qualquer solicitação que o atinja precise conter um JWT válido; caso contrário, o middleware encerrará a solicitação antes que o manipulador real seja executado. Porque a carga útil decodificada já está anexada a req.userO manipulador pode recuperar o ID do usuário diretamente do token e consultar o banco de dados de acordo.

Esse padrão garante que a lógica de negócios não se preocupe com a forma como a autenticação foi realizada; ela simplesmente confia na presença de uma carga útil verificada e se concentra em buscar ou modificar os dados do domínio. Em configurações mais avançadas, você também pode incorporar funções, permissões ou escopos dentro do token e usá-los para direcionar verificações de autorização nos manipuladores.

Do ponto de vista do consumidor, o solicitante primeiro acessará o endpoint de login para obter um token e, em seguida, o incluirá em solicitações subsequentes a esses endpoints protegidos, geralmente provenientes de um SPA como o React, um aplicativo móvel ou uma integração backend-to-backend. A experiência geral é tranquila se as mensagens de erro forem claras quando um token expirar ou for inválido.

Neste ponto, abordamos uma configuração JWT independente usando um segredo armazenado em nosso .env arquivo, mas muitos sistemas de produção também se integram com servidores de autorização externos e usam endpoints JWKS para validar tokens; é aí que entra o middleware Express para APIs protegidas por OAuth.

Utilizando um endpoint JWKS para validar JWTs em Node.js

Em arquiteturas mais avançadas, especialmente aquelas que dependem do OAuth 2.0 e do OpenID Connect, as APIs do Node.js geralmente recebem tokens de acesso emitidos por um servidor de autorização externo, em vez de gerar os JWTs por conta própria. Neste caso, a API deve validar tokens assinados com chaves assimétricas, normalmente RSA ou EC, em que apenas o servidor de autorização detém a chave privada.

Uma solução comum é usar uma biblioteca middleware do Express que busca conjuntos de chaves web JSON (JWKS) de um endpoint configurado e exposto pelo servidor de autorização. Esse endpoint JWKS expõe chaves públicas em um formato padrão, permitindo que a API verifique as assinaturas JWT recebidas sem precisar gerenciar chaves privadas.

Por exemplo, você pode instalar um pacote como express-oauth-jwt e configure-o com a URL JWKS, como https://idsvr.example.com/oauth/v2/oauth-anonymous/jwksE então, conecte o middleware às suas rotas de API do Node.js. Uma vez integrado, o middleware lida automaticamente com a maioria das tarefas de validação de tokens de baixo nível.

Com essa configuração em vigor, a biblioteca procura o kid (ID da chave) do cabeçalho JWT, baixa a chave pública apropriada do endpoint JWKS (se ainda não estiver em cache) e verifica a assinatura usando essa chave. Ele também verifica a data de expiração do token, o emissor, o público-alvo e outros campos padrão, dependendo de como você configurar as opções.

Após a validação bem-sucedida, o JWT analisado e suas declarações ficam disponíveis no Express. request objeto, permitindo que seus manipuladores inspecionem escopos, identificadores de usuário ou atributos personalizados para fins de autorização e registro. Se algo der errado (por exemplo, o token expirou ou a assinatura não corresponde), o middleware responde com os códigos de erro HTTP apropriados e inclui o motivo na mensagem de erro. WWW-Authenticate cabeçalho.

Escopos, declarações e lógica de autorização em sua API

Depois que sua API Node.js confia em um JWT, seja porque o assinou diretamente ou porque um middleware baseado em JWKS o validou, o próximo passo é usar suas declarações e escopos para implementar a autorização. É aqui que você vai além da simples autenticação e começa a conceder ou negar acesso com base no que o usuário tem permissão para fazer.

Os escopos geralmente representam permissões de granularidade ampla, como: read:users or write:orderse geralmente são incluídos em JWTs sob uma reivindicação como scope or scopes. A API pode verificar se o escopo necessário está presente antes de processar uma solicitação que acesse determinados dados comerciais, retornando uma resposta de proibição caso esteja ausente.

Da mesma forma, informações como ID do usuário, e-mail, função ou locatário permitem implementar regras mais específicas; por exemplo, garantindo que os usuários acessem apenas seus próprios registros ou limitando as ações administrativas a funções específicas. No Express, é simples escrever middlewares personalizados que examinam essas declarações. req.user e aplicar verificações de política.

Algumas bibliotecas de validação JWT para Express oferecem recursos integrados para verificar os escopos necessários como parte de suas opções, facilitando a associação de cada rota ou roteador a um conjunto de permissões específico. Essa abordagem mantém as questões de autorização próximas às definições de rota, o que melhora a legibilidade e a capacidade de manutenção.

Do ponto de vista do design, geralmente é melhor tratar os escopos e declarações do JWT como parte de uma política declarativa, em vez de espalhar strings codificadas por todo o código, para evitar inconsistências e facilitar futuras alterações no modelo de segurança.

Testando e solucionando problemas em APIs Node.js protegidas por JWT

Após tudo estar configurado, você precisará testar a chamada da sua API Node.js com e sem JWTs válidos para confirmar se o controle de acesso se comporta exatamente como esperado. Ferramentas simples como curl, HTTPie ou Postman são perfeitas para isso, permitindo que você defina cabeçalhos e payloads facilmente.

Um fluxo de teste típico envolve primeiro chamar o endpoint de login para obter um token e, em seguida, enviar uma segunda solicitação para uma rota protegida com o Authorization: Bearer <token> Conjunto de cabeçalhos. Se a sua implementação estiver correta, as solicitações autorizadas devem ser bem-sucedidas, enquanto as chamadas sem tokens ou com tokens inválidos devem ser rejeitadas.

Ao usar uma biblioteca de validação JWT do Express integrada a um endpoint JWKS, qualquer problema com o token geralmente é sinalizado com um 401 Unauthorized resposta e informações detalhadas no WWW-Authenticate Cabeçalho de resposta. Por exemplo, se um token de acesso expirar, esse cabeçalho geralmente indicará o código de erro específico e a descrição.

Essas mensagens de erro detalhadas são muito úteis durante o desenvolvimento e a depuração, mas você deve ter cuidado para não vazar informações internas excessivamente sensíveis em logs ou respostas de produção. Geralmente, é uma boa ideia centralizar o registro de logs e mascarar ou generalizar certas mensagens, mantendo, ao mesmo tempo, contexto suficiente para que os operadores diagnostiquem problemas.

Testes automatizados e JWTs simulados podem aumentar ainda mais sua confiança, permitindo que você verifique se o comportamento de autorização é estável ao alterar rotas, adicionar escopos ou refatorar a lógica do middleware.

Em resumo, uma API Node.js que combina Express, MongoDB, bcrypt, Joi e JWT — opcionalmente com o suporte de uma biblioteca de validação baseada em JWKS — oferece uma base sólida para proteger endpoints, mantendo a flexibilidade necessária para integração com frameworks frontend modernos, aplicativos móveis e provedores de identidade corporativos.