Pontos-chave
- O Auth.js trata da complexa segurança do backend logo de início, poupando-te de teres de escrever do zero o código para o hash de palavras-passe e a lógica de sessão.
- Usar JWTs para a autenticação no Next.js mantém a tua aplicação rápida, porque o servidor não precisa de consultar uma base de dados sempre que uma página é carregada.
- O Next.js divide o código em componentes do servidor e do cliente, por isso usar middleware é a forma mais eficiente de proteger as rotas antes mesmo de as páginas serem renderizadas.
A autenticação é o que permite que uma aplicação saiba quem deixar entrar e quem bloquear. Todas as aplicações SaaS e web modernas usam autenticação. Os utilizadores introduzem as suas credenciais, o servidor verifica-as e guarda-as enquanto navegam pela aplicação.
O Next.js lida muito bem com a autenticação quando o usas com ferramentas como o Auth.js. Consegue verificar as credenciais dos utilizadores, gerar tokens seguros e proteger páginas privadas. Isto mantém as aplicações front-end seguras sem teres de lidar com criptografia complexa.
Neste blogue, vou falar sobre por que é que faz sentido usar JSON Web Tokens (JWT) com o Auth.js no Next.js. E também sobre como funciona, na prática, a proteção de rotas.
Depois, vou criar uma pequena aplicação com um formulário de login personalizado que gera um JWT para proteger um painel privado. E assim que estiver a funcionar, vou implementar tudo em produção na hospedagem gerida Node.js da Cloudways (Velocity).
Vamos começar…
- O que é o Auth.js (anteriormente NextAuth)
- Por que usar o JWT para a autenticação no Next.js?
- Autenticação do lado do servidor vs. autenticação do lado do cliente no Next.js
- Proteger rotas com o middleware do Next.js
- Como criar uma aplicação Next.js com autenticação JWT
- O que vou usar
- Passo 1: Configurar o projeto Next.js
- Passo 2: Instalar e configurar o Auth.js
- Passo 3: Criar o formulário de início de sessão
- Passo 4: Adicionar middleware para proteção de rotas
- Passo 5: Criar o painel protegido e sair da sessão
- Passo 6: Testar a aplicação localmente
- Passo 7: Enviar para o GitHub
- Passo 8: Implementação na hospedagem Node.js gerida pela Cloudways
- Conclusão
O que é o Auth.js (anteriormente NextAuth)
O Auth.js, antes chamado NextAuth, é uma ferramenta usada nas aplicações Next.js para gerir a autenticação. É uma das soluções mais utilizadas para adicionar a funcionalidade de início de sessão a aplicações web modernas.
Em vez de criares um sistema de autenticação do zero, o que implica lidar com coisas como o hash de palavras-passe, a expiração de tokens, a gestão de sessões e cookies seguros, o Auth.js trata de tudo isso por ti.
Assim, quando tudo isto for tratado automaticamente, basta ligar isto ao meu projeto, definir como os utilizadores devem iniciar sessão e o Auth.js trata do resto nos bastidores, de forma segura e fiável.
Por que usar o JWT para a autenticação no Next.js?
A razão pela qual alguém usaria JWTs em vez de sessões tradicionais de base de dados, como guardar um ID de sessão num PostgreSQL ou num MongoDB, é simples: o JWT funciona como um cartão de identificação digital seguro.
Quando um utilizador inicia sessão com sucesso, o servidor atribui-lhe um cartão de identificação e guarda-o também de forma segura no seu navegador.
Assim, sempre que um utilizador tenta aceder a um URL protegido, o servidor verifica o cartão de identificação para ver se o utilizador tem acesso a esse URL específico e se o cartão está válido e não expirou. O que o servidor não precisa de fazer constantemente é consultar a base de dados sempre que o utilizador clica num link.
O que isto faz é manter a aplicação rápida e aliviar bastante a carga sobre a base de dados.
Alojamento PHP gerido e seguro para o teu backend de autenticação
Implementa um ambiente dedicado de PHP ou Laravel para gerir utilizadores de forma segura, emitir tokens e alimentar o teu frontend Next.js com uma API fiável.
Autenticação do lado do servidor vs. autenticação do lado do cliente no Next.js
Como o Next.js App Router divide o código em componentes do servidor e do cliente, os programadores têm de lidar com a autenticação de forma diferente, dependendo de onde se encontram.
No caso da autenticação do lado do servidor, isto significa verificar a sessão de forma segura no backend antes de a página ser apresentada. É aqui que a questão da segurança é tratada. Se um utilizador não tiver um JWT válido, o servidor recusa-se a mostrar a URL solicitada.
A autenticação do lado do cliente tem mais a ver com a interface do utilizador e menos com segurança. É quando os componentes React do front-end verificam a sessão para decidir, por exemplo, se devem mostrar um botão«Iniciar sessão» ou a foto de perfil de um utilizador. Resumindo, serve para atualizações visuais, não para segurança propriamente dita.
Proteger rotas com o middleware do Next.js
Sem uma autenticação adequada, qualquer pessoa poderia simplesmente digitar um URL restrito no navegador e contornar completamente o ecrã de início de sessão. É isso que se pode evitar com o Next.js Middleware. Também te vou mostrar isto quando abordar o miniprojeto mais à frente neste blogue.
Em vez de verificar manualmente se um utilizador está com sessão ativa em cada página, o middleware faz essa verificação de forma global. Para isso, ele posiciona-se entre o pedido web do utilizador e o servidor que processa esse pedido.
Antes do Next.js renderizar a página protegida que o utilizador pediu, o middleware intercepta o pedido e verifica se existe um JWT válido, aquele «cartão de identificação» de que te falei. Se o token estiver válido, a página carrega. Se não existir ou tiver expirado, o utilizador é redirecionado de volta para a página de início de sessão.
O melhor disto é que mantém o código organizado e basta apenas umas poucas linhas para configurar.
Como criar uma aplicação Next.js com autenticação JWT
Agora que já expliquei o que é a autenticação JWT, para te ajudar a perceber como funciona na prática, vou criar uma aplicação simples em Next.js com uma página de login, um painel de controlo protegido e um botão para sair.
O que vou usar
- Node.js
- VS Code
- Next.js e Tailwind CSS
- Auth.js (NextAuth)
Passo 1: Configurar o projeto Next.js
Primeiro, vou abrir a linha de comandos. Vou criar uma pasta para o meu projeto e entrar nela:
mkdir nextjs-auth-blog cd nextjs-auth-blog
Assim que o meu projeto estiver criado, a primeira coisa de que preciso é ter o Node.js instalado no meu computador.
No meu caso, estou a usar o portátil do trabalho, que tem restrições de TI. Não consigo descarregar a versão padrão, por isso vou simplesmente descarregar a versão binária independente do Node.js do site nodejs.org.
Isto é um ficheiro zip, por isso vou descompactá-lo na pasta «Downloads» para me facilitar a vida.
Antes de poder executar comandos do Node.js, preciso indicar ao Prompt de Comandos onde fica a minha pasta do Node.js. Para isso, vou executar este comando:
define PATH=%PATH%;C:\Users\abdulrehman\Downloads\node-v24.15.0-win-x64\node-v24.15.0-win-x64
Agora já posso criar o meu projeto Next.js executando este comando:
npx create-next-app@latest .
Juntei um ponto no final para dizer ao Next.js para criar o projeto dentro da pasta atual e não criar uma pasta totalmente nova.
Assim que o comando for executado, vou carregar na tecla Enter para aceitar a opção predefinida. Isto vai instalar o Tailwind CSS juntamente com alguns outros pacotes predefinidos do Next.js.
Assim que vir a mensagem de sucesso, vou poder abrir a pasta do meu projeto no VS Code.
Passo 2: Instalar e configurar o Auth.js
Para abrir o meu projeto no VS Code, vou a Ficheiro > Abrir pasta e, em seguida, seleciono a pasta do projeto.
Agora, vou deixar o VS Code aberto e instalar primeiro o pacote Auth.js. Para isso, vou voltar ao prompt de comandos e executar:
npm install next-auth
Para que o Auth.js possa assinar tokens de autenticação de forma segura, vou fornecer-lhe uma chave secreta. Para isso, na raiz da pasta do meu projeto, vou criar um ficheiro chamado .env.local e, nesse ficheiro, vou adicionar uma sequência aleatória:
NEXTAUTH_SECRET="my_super_duper_secret_jwt_key_123"
Para gerir a lógica de início de sessão do meu projeto, vou configurar as rotas do Auth.js. Isso vai tratar do início e fim de sessão dos utilizadores, bem como da gestão das sessões.
Dentro da pasta da aplicação, vou criar uma pasta chamada «api». Depois, dentro dessa, uma pasta chamada «auth». E nessa, uma pasta chamada […nextauth] para gerir a autenticação.
Dentro da última pasta, vou criar um ficheiro chamado route.ts.
O caminho final fica assim: app > api > auth > […nextauth] > route.ts
Agora, no ficheiro route.ts, vou configurar o fornecedor de credenciais e também um utilizador fictício. Para isso, vou colar este código no ficheiro:
import NextAuth de "next-auth";
import CredentialsProvider de "next-auth/providers/credentials";
const handler = NextAuth({
prestadores: [
CredentialsProvider({
nome: "Credenciais",
credenciais: {
e-mail: { label: "E-mail", type: "email" },
password: { label: "Palavra-passe", type: "password" }
},
async authorize(credentials) {
// Utilizador fictício definido diretamente no código para testes
const user = { id: "1", name: "Admin", email: "[email protected]" };
if (credentials?.email === "[email protected]" && credentials?.password === "password123") {
return user;
}
return null;
}
})
],
sessão: {
estratégia: "jwt",
},
páginas: {
signIn: "/", // Redireciona para a nossa página inicial personalizada para o login
}
});
export { handler como GET, handler como POST };
Passo 3: Criar o formulário de início de sessão
Agora é hora de criar a página onde o utilizador vai introduzir as suas credenciais. Para isso, vou abrir o ficheiro app/page.tsx e apagar o código que está lá dentro.
Como este formulário que estou a criar vai receber entradas do utilizador e também enviar dados, vou transformá-lo num Componente Cliente, adicionando «use client» logo no início.
Assim:
"usa o cliente";
import { signIn } de "next-auth/react";
import { useState } de "react";
import { useRouter } from "next/navigation";
export function Home() {
const [email, setEmail] = useState("");
const [password, setPassword] = useState("");
const router = useRouter();
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
const result = await signIn("credentials", {
e-mail,
palavra-passe,
redirect: false,
});
if (result?.ok) {
router.push("/dashboard");
} else {
alert("Credenciais inválidas");
}
};
return (
Iniciar sessão
); }
Passo 4: Adicionar middleware para proteção de rotas
Pois é… neste momento, qualquer pessoa pode simplesmente escrever /dashboard no URL e contornar completamente a lógica de início de sessão que criei. Por isso, vou proteger isto criando um ficheiro chamado middleware.ts na raiz da pasta do meu projeto.
O Auth.js simplifica a proteção das rotas. Vou usar o middleware predefinido e definir quais as rotas que devem ser protegidas.
export { default } from "next-auth/middleware";
export const config = {
matcher: ["/dashboard"],
};
Passo 5: Criar o painel protegido e sair da sessão
Se o utilizador iniciar sessão com sucesso, passando pela minha lógica de autenticação, quero que tenha mesmo um sítio onde possa chegar. Para isso, vou criar uma pasta dentro da app chamada «dashboard» e adicionar um ficheiro page.tsx lá dentro.
Nesta página, vou manter as coisas simples e mostrar o e-mail do utilizador que está a iniciar sessão, usando o Auth.js para verificar a sessão atual. Também vou adicionar um botão simples do lado do cliente para gerir o fim da sessão.
import { getServerSession } from "next-auth";
import LogoutButton de "./LogoutButton";
import { redirect } de "next/navigation";
export default async function Dashboard() {
const session = await getServerSession();
// Verificação de segurança adicional
if (!session) {
redirect("/");
}
return (
Painel de controlo seguro
Bem-vindo de volta, {session?.user?.email}
); }
Agora, para que o botão de sair funcione, vou criar outro ficheiro na pasta «dashboard» chamado «LogoutButton.tsx»:
"usa o cliente";
import { signOut } de "next-auth/react";
export function LogoutButton() {
return (
);
}
Passo 6: Testar a aplicação localmente
Pronto, agora é hora de testar o que criei. Vou voltar à linha de comandos e iniciar o servidor de desenvolvimento:
npm run dev
Agora posso ir a http://localhost:3000 no meu navegador e devo ver o meu formulário de início de sessão.
Também posso iniciar sessão com as minhas credenciais para ver se está a funcionar:
Agora, se eu tentar aceder a /dashboard para fazer uma manobra de contorno, o middleware redireciona-me imediatamente para a página de início de sessão.
Se eu voltar a introduzir as minhas credenciais de teste, consigo iniciar sessão, o que significa que o JWT foi verificado. E quando clico em «Sair», a sessão é encerrada e sou redirecionado para o ecrã de início de sessão.
Passo 7: Enviar para o GitHub
Como o projeto está a funcionar na perfeição, vou encerrar o meu servidor de desenvolvimento premindo CTRL+C na linha de comandos e enviar o código para o Git. Por isso, se também quiseres reutilizar este projeto, podes descarregá-lo do meu repositório no GitHub.
Para enviar o código para o Git, vou começar por criar um novo repositório no GitHub.
Depois, vou executar os comandos abaixo no CMD, um por um.
git init git add . git commit -m "A trabalhar no login JWT do NextAuth" git branch -M main git remote add origin https://github.com/abdulrehman293/nextjs-auth-blog.git git push -u origin main
Agora, se eu voltar ao meu repositório do GitHub e atualizar a página, todos os meus ficheiros e pastas devem estar carregados no meu repositório.
Passo 8: Implementação na hospedagem Node.js gerida pela Cloudways
Depois de enviar o projeto para o GitHub, posso implementá-lo na nossa hospedagem Node.js gerida pela Cloudways (Velocity).
Vou criar rapidamente uma nova aplicação Node. Para esta demonstração, vou escolher o plano Starter.
A seguir, vou ter de ligar o meu GitHub, GitLab ou Bitbucket ao Cloudways. Como o meu projeto está no GitHub, vou ligar-me a esse.
Depois, vou escolher o meu repositório «nextjs-auth-blog » que enviei para o Git e clico em «Continuar».
Agora, o Cloudways vai escolher automaticamente o framework, o ramo e a versão do Node.js certos para a minha aplicação. Quanto ao diretório raiz, vou deixá-lo como está por predefinição.
A seguir, vou até «Variáveis de Ambiente » e clico em «Adicionar». Agora vou adicionar a mesma variável NEXTAUTH_SECRET e o seu valor ao Cloudways, tal como fiz no passo 2 no meu ficheiro .env.local, para assinar os JWTs.
Estou a fazer isto porque o meu ficheiro .env.local nunca foi enviado para o GitHub, por isso o Auth.js não vai ter a sua chave no servidor, a menos que a adicione aqui.
- NEXTAUTH_SECRET — a mesma sequência secreta que usei localmente
Já que estou nesta página, vou adicionar mais uma variável de ambiente: NEXTAUTH_URL.
Faço isto porque o Auth.js precisa de saber o URL real da aplicação para gerir os redirecionamentos corretamente. Assim, quando clico em «Sair», a aplicação deve conseguir redirecionar-me de volta para o ecrã de início de sessão.
Vou voltar às Variáveis de Ambiente, clicar em «Adicionar» e definir:
- NEXTAUTH_URL — o URL temporário do Cloudways da página «Visão geral»
Depois, vou clicar em «Guardar » e em «Implementar agora».
A Cloudways vai agora começar a descarregar o código do GitHub, instalar as dependências, executar a compilação do Next.js e iniciar a minha aplicação. Isto vai demorar entre 5 a 7 minutos, por isso vou esperar até lá.
Assim que a implementação terminar, vou copiar e colar o URL temporário do Cloudways da página «Visão geral» da aplicação no meu navegador e carregar em Enter.
No formulário de início de sessão, tal como fiz localmente, vou introduzir as minhas credenciais, [email protected] e password123, e vou entrar no painel de controlo.
Também vou testar o botão de sair e devo voltar à página de início de sessão no URL ativo, exatamente como devia funcionar.
E é assim que funciona todo o fluxo de autenticação JWT na hospedagem Node.js gerida pela Cloudways. O middleware continua a proteger o painel de controlo, o login continua a emitir um token válido e o logout continua a encerrar a sessão corretamente.
Tudo funciona da mesma forma que na minha configuração local, só que agora a aplicação está online e pode ser acedida de qualquer lugar num servidor ativo.
Conclusão
E assim terminamos o nosso guia sobre autenticação no Next.js. Neste artigo, tentei explicar por que faz sentido usar o Auth.js para a autenticação no Next.js. Também falei das vantagens em termos de desempenho e segurança que ganhas ao usar tokens em vez das tradicionais sessões de base de dados.
Também expliquei como criar uma aplicação Next.js segura que lida com inícios de sessão personalizados e protege um painel privado, e depois implementei-a em produção na hospedagem gerida Node.js da Cloudways (Velocity), para que possa ser acedida a partir de qualquer lugar.
Também publiquei o projeto no meu GitHub para que possas reutilizar facilmente os ficheiros do projeto.
Se tiveres alguma dúvida, deixa um comentário aqui em baixo e eu respondo-te.
P1: O Next.js tem autenticação?
Não, o Next.js não tem autenticação integrada por predefinição. Para implementares a autenticação, vais ter de usar bibliotecas de terceiros, como a Auth.js, a Clerk ou o Firebase, para gerires os inícios de sessão de forma segura.
P2: O que é o middleware do Next.js para autenticação?
O middleware é basicamente um script que é executado antes de uma página carregar, para verificar se o utilizador está com sessão ativa. Se o utilizador não tiver uma sessão válida, o middleware redireciona-o de volta para a página de início de sessão.
P3: O próximo JWT de autenticação é este?
Sim. Por predefinição, o Auth.js usa JSON Web Tokens (JWTs) para a gestão de sessões. No entanto, também pode ser ajustado para usar sessões tradicionais de base de dados, se o teu projeto assim o exigir.
P4: O Next Auth já não é recomendado?
Não, só mudou de nome para Auth.js para poder dar suporte a outras estruturas, além do Next.js. O pacote do Next.js (next-auth) continua a ser muito usado e é mantido ativamente.
Abdul Rehman
O Abdul é um profissional de marketing experiente em tecnologia, movido a café e criativo, que adora manter-se a par das últimas actualizações de software e gadgets tecnológicos. É também um escritor técnico competente que consegue explicar conceitos complexos de forma simples para um público alargado. Abdul gosta de partilhar os seus conhecimentos sobre a indústria da nuvem através de manuais de utilizador, documentação e publicações em blogues.
