Next.js com NextAuth: login com Google

O login com Google oferece uma alternativa prática para que visitantes acessem uma aplicação sem criar uma senha. Quando essa opção é implementada em um projeto Next.js com NextAuth, o usuário pode entrar por meio de uma conta Google, enquanto a aplicação controla a sessão, os dados autorizados e o redirecionamento após a autenticação.

Neste guia, você vai entender o fluxo básico, a configuração do provedor, as variáveis de ambiente, a integração com o App Router e os principais cuidados de segurança. A ideia é mostrar o caminho completo, desde a instalação até a validação do acesso, com uma visão clara para quem está começando.

O que é Next.js com NextAuth: login com Google?

Next.js é um framework usado para criar aplicações web em React, um conjunto de ferramentas que facilita a construção de interfaces. Ele oferece recursos como renderização no servidor, rotas de API, componentes reutilizáveis e suporte a diferentes formas de exibição e organização do projeto.

NextAuth, também conhecido como Auth.js em projetos mais recentes, é uma biblioteca que simplifica a implementação de autenticação. Ela permite conectar uma aplicação a provedores externos, como Google, GitHub, Microsoft ou Facebook, além de oferecer opções para autenticação por e-mail e credenciais.

O login com Google funciona como uma delegação de confiança. O usuário confirma sua identidade diretamente no Google, e a aplicação recebe as informações permitidas pela configuração da integração. O NextAuth organiza esse processo, cria a sessão e gerencia o acesso entre a página inicial e as áreas protegidas.

Como o login com Google funciona

O fluxo costuma seguir esta sequência:

1. O visitante clica em um botão identificado como “Continuar com Google”.
2. A aplicação redireciona o usuário para a página de autorização do Google.
3. O Google apresenta a tela de login e consentimento.
4. After the user authorizes the application, Google returns the authorized identity data.
5. NextAuth validates the information and creates a session in the application.
6. The user returns to the application, already authenticated.

O site não deve presumir que qualquer e-mail informado pela pessoa está automaticamente confirmado fora do fluxo do Google. A validity of the data must be verified according to the provider configuration and the security rules adopted by the application.

Next.js com NextAuth: configuração do login com Google

Preparando o projeto

Antes de configurar a autenticação, é necessário ter um projeto Next.js em funcionamento. A forma mais direta de começar, segundo a documentação oficial, é criar um projeto com o comando de criação do Next.js. O comando abaixo usa o exemplo de pacoterecommended pela própria documentação:

npx create-next-app@latest

Durante o processo, escolha as opções adequadas ao seu projeto. A navegação mais importante para este exemplo é o App Router, que utiliza a pasta app. Depois, instale o pacote de autenticação compatível com a versão adotada pelo projeto.

A documentação do Auth.js indica a instalação por meio do gerenciador de pacotes. Em um projeto com npm, por exemplo:

npm install next-auth@beta

A tag beta é adequada para a linha Auth.js v5. Se o projeto utiliza uma versão estável anterior do NextAuth, o comando e a forma de configuração podem ser diferentes. Em caso de dúvida, consulte a documentação da versão instalada e não misture exemplos de Auth.js v4 com Auth.js v5.

Configurando as credenciais no Google Cloud

Para usar o login com Google, primeiro é preciso criar ou selecionar um projeto no Google Cloud. O projeto do Google Cloud é o espaço administrativo onde ficam, APIs, permissões e credenciais.

A configuração inicial normalmente envolve:

• Criar um projeto no Google Cloud.
• Ativar a API necessária para autenticação OAuth.
• Configurar a tela de consentimento do aplicativo.
• Criar um cliente OAuth do tipo Web.
• Informar as URIs de redirecionamento autorizadas.

A tela de consentimento define como o aplicativo será apresentado ao usuário. Ela pode conter o nome do projeto, o e-mail de suporte, o logotipo, os escopos solicitados e a política de privacidade. O Google pode exigir verificações adicionais dependendo do tipo de aplicação, do uso dos dados e da forma como o serviço é disponibilizado.

O escopo openid é fundamental para usar o OpenID Connect, protocolo que permite confirmar a identidade do usuário. O escopo email solicita o endereço de e-mail, enquanto profile pode ser usado para obter informações básicas do perfil, como nome e foto. É recomendável solicitar somente o necessário para a aplicação.

Criando o cliente OAuth

No painel do Google Cloud, acesse a área de credenciais e crie um cliente OAuth 2.0 do tipo “Aplicativo Web”. O nome do cliente é apenas uma identificação administrativa e não precisa ser exibido na interface pública do site.

A URI de redirecionamento deve corresponder ao endereço fornecido pelo NextAuth. Em desenvolvimento local, o padrão costuma ser:

http://localhost:3000/api/auth/callback/google

O callback é a rota em que o Google devolve o resultado da autorização. O NextAuth cuida dessa etapa, mas o endereço precisa estar autorizado na configuração do cliente OAuth.

Para produção, o domínio e o caminho devem ser trocados pelo endereço real da aplicação:

https://www.seudominio.com.br/api/auth/callback/google

A documentação do Auth.js recomenda usar o prefixo https:// para endpoints de produção. Também é importante usar o mesmo host que o usuário acessa. Não se deve autorizar apenas www.seudominio.com.br e esperar que o callback funcione em seudominio.com.br.

Configurando as variáveis de ambiente

As credenciais do Google devem ficar em variáveis de ambiente, e nunca em um arquivo enviado ao repositório público. O arquivo .env.local é usado para desenvolvimento local e deve ser mantido fora do versionamento.

AUTH_SECRET=uma-chave-longa-e-segura
AUTH_GOOGLE_ID=seu-client-id
AUTH_GOOGLE_SECRET=seu-client-secret

No arquivo .gitignore, confirme que os arquivos de ambiente não serão publicados:

.env*

O AUTH_SECRET é usado pelo Auth.js para proteger a sessão e outros dados relacionados à autenticação. Gere um valor aleatório robusto com uma ferramenta apropriada. O AUTH_GOOGLE_ID e o AUTH_GOOGLE_SECRET correspondem ao identificador e ao segredo do cliente OAuth criado no Google Cloud.

Variáveis que começam com AUTH_ seguem o padrão reconhecido pelo Auth.js. A documentação oficial menciona que o nome da variável secreta pode ser AUTH_SECRET e que ela deve ter um valor aleatório. A dependência AUTH_TRUST_HOST pode ser necessária em alguns ambientes de implantação, conforme a documentação de self-hosting.

Criando o arquivo de autenticação

No App Router, o Auth.js usa um arquivo central para configurar os provedores. Um exemplo com o provedor Google é:

import NextAuth from "next-auth"
import Google from "next-auth/providers/google"

n
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Google({
      allowDangerousEmailAccountLinking: true,
    }),
  ],
})

A opção allowDangerousEmailAccountLinking: true merece atenção. Ela permite vincular contas locais e externas quando o e-mail coincide. Como essa combinação pode cria acesso indevido se o domínio do e-mail não for verificado pelo provedor, a documentação do Auth.js recomenda usar a opção com cautela. Em uma aplicação nova, o ideal é avaliar a necessidade real dessa opção antes de ativá-la.

O arquivo pode ficar, por exemplo, em auth.ts, na raiz do projeto. O nome e o local variam conforme a organização adotada, mas os handlers precisam ser expostos para que a rota de autenticação funcione.

Expondo as rotas de autenticação

O App Router espera uma rota em app/api/auth/[...nextauth]/route.ts que encaminhe as requisições para os handlers do Auth.js:

import { handlers } from "../../../auth"

export const { GET, POST } = handlers

A rota GET atende as páginas e endpoints de autenticação. O método POST processa ações como login e logout, além de receber os callbacks do provedor, de acordo com o fluxo configurado.

Configurando a página de login

A página pode conter um botão que dispara a função signIn. Para isso, ela deve ser um Client Component, porque a interação acontece no navegador:

"use client"

import { signIn } from "../../../auth"

export default function LoginPage() {
  return (
    <main>
      <h1>Acesse sua conta</h1>
      <p>Use sua conta Google para entrar.</p>
      <button onClick={() => signIn("google")}>
        Continuar com Google
      </button>
    </main>
  )
}

O botão pode usar um componente visual próprio, desde que a ação continue sendo signIn("google"). Não é necessário registrar a conta Google em um formulário de e-mail e senha. O usuário final realiza a autenticação diretamente na interface do Google.

Login com Google no App Router: sessão e áreas protegidas

Obtendo a sessão no servidor

Depois da autenticação, a aplicação pode consultar a sessão em um Server Component. O método auth retorna os dados do usuário quando existe uma sessão válida:

import { auth } from "../../auth"

export default async function DashboardPage() {
  const session = await auth()

  if (!session) {
    return null
  }

  return (
    <main>
      <h1>Olá, {session.user?.name}</h1>
      <p>Seu e-mail: {session.user?.email}</p>
    </main>
  )
}

A sessão pode ser usada para exibir nome, e-mail ou imagem do usuário. O conteúdo retornado depende dos escopos autorizados e dos callbacks configurados. É importante não presumir que todo campo estará disponível em qualquer configuração.

Protegendo uma rota

Uma rota privada deve verificar a sessão no servidor e redirecionar visitantes não autenticados. O padrão mais simples é:

import { redirect } from "next/navigation"
import { auth } from "../../auth"

export default async function ContaPage() {
  const session = await auth()

  if (!session) {
    redirect("/login")
  }

  return <h1>Área da conta</h1>
}

A proteção de interface é somente uma parte do trabalho. As ações que alteram dados, como atualizar um perfil ou criar um pedido, também precisam conferir a sessão no servidor. Se a regra puder ser aplicada somente pela interface, uma pessoa pode contornar a interface chamando a API diretamente.

Exibindo o estado de login

Para criar uma interface com botão de entrada e botão de saída, o componente pode utilizar o hook useSession, ou o padrão de Server Components com forms de ação. O hook é simples para quem já trabalha com React:

"use client"

import { useSession, signIn, signOut } from "next-auth/react"

export default function SessionControls() {
  const { data: session, status } = useSession()

  if (status === "loading") {
    return <p>Carregando...</p>
  }

  if (session) {
    return (
      <button onClick={() => signOut()}>
        Sair da conta
      </button>
    )
  }
}

O estado loading evita mostrar uma informação incorreta enquanto a sessão ainda está sendo verificada. Essa distinção melhora a experiência e evita saltos visuais na interface.

Personalizando o perfil com callbacks

O callback session permite modificar os dados que serão enviados à aplicação. Por exemplo, o código pode incluir um identificador interno do usuário:

import NextAuth from "next-auth"
import Google from "next-auth/providers/google"

n
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [Google],
  callbacks: {
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.sub ?? ""
      }
      return session
    },
  },
})

O identificador token.sub é o subject do token de identificação. Ao usá-lo para localizar o usuário em um banco de dados, confirme antes que ele corresponde ao usuário correto. Para ambientes Node.js, a documentação do Auth.js também descreve o callback jwt, que pode ser usado para personalizar o token. É recomendável evitar armazenar dados sensíveis diretamente no token.

Comparativo: login com Google, e-mail e senha e outros provedores

O login com Google não resolve todas as Needs de autenticação de uma aplicação. A escolha depende do público, da infraestrutura disponível e da experiência desejada.

A melhor estratégia pode combinar mais de uma opção. Uma aplicação pública pode oferecer Google como atalho e e-mail como alternativa. Em um ambiente interno, a autenticação corporativa pode ser mais adequada do que permitirem que qualquer pessoa use uma conta pessoal.

Segurança do login com Google

A integração OAuth reduz a necessidade de armazenar senhas Google, mas não elimina as responsabilidades de segurança da aplicação. O login deixa de ser o único ponto de atenção.

Protegendo o segredo do cliente

O AUTH_GOOGLE_SECRET deve ser mantido no servidor. Ele nunca deve ser enviado ao navegador, incorporado em um componente cliente ou publicado em um repositório. Em Yak deployments, use o painel de variáveis de ambiente da plataforma ou o sistema de secrets do provedor de infraestrutura.

Validando a origem e o ambiente

A URI de redirecionamento autorizada deve corresponder ao ambiente de uso. Em desenvolvimento, o endereço local pode ser permitido. Em produção, use HTTPS e o domínio correto. Misturar URLs de teste e produção pode gerar falhas de correspondência ou aumentar a superfície de ataque.

Cuidando do e-mail como identificador

O e-mail costuma ser usado para identificar a pessoa na aplicação, mas o nível de confiança depende do provedor e do escopo. O Google informa se a conta é gerenciada por uma organização, e o Auth.js disponibiliza informações como email_verified. Para decisões importantes, considere um identificador de conta mais robusto e evite criar vinculações automáticas inseguras.

Limitando dados e permissões

Solicite apenas os escopos necessários. Guarde o mínimo de dados necessário para o serviço. No banco de dados, relacione a conta externa a um usuário interno e aplique as permissões desse usuário. A autenticação prova a entrada na conta, mas não autoriza automaticamente todas as ações.

Invalidando sessões e tokens

Para ações sensíveis, é recomendável exigir uma nova autenticação ou utilizar Mechanisms de controle adicionais. Também é importante revisar a validade da sessão, o armazenamento dos tokens e a estratégia de logout. A documentação do Auth.js descreve opções para sessões de banco de dados, JWT e estratégias adaptativas, que podem ser avaliadas de acordo com a necessidade do projeto.

Este conteúdo tem caráter informativo. Decisões técnicas devem ser tomadas com profissional especializado.

Erros comuns e como resolvê-los

Callback não autorizado

Um dos erros mais frequentes é o Google exibir redirect_uri_mismatch ou access_denied. O primeiro normalmente indica que a URI de redirecionamento enviada pela aplicação não corresponde à que foi cadastrada no Google Cloud. Verifique o host, o protocolo, a porta e o caminho /api/auth/callback/google.

O erro access_denied pode estar relacionado ao consentimento recusado, à configuração da tela de consentimento ou às permissões da conta. Não trate esse cenário como uma falha definitiva da aplicação, pois o usuário pode ter cancelado o fluxo deliberadamente.

Erro de configuração de segredo

Mensagens relacionadas a AUTH_SECRET, MissingSecret ou NO_SECRET indicam que a variável não foi carregada. Confirme o nome exato, o arquivo .env.local, a restarting do servidor e a configuração da plataforma de hospedagem.

Sessão criada, mas a interface não atualiza

Verifique se o hook useSession está sendo usado dentro de um Client Component e se o endpoint de sessão está acessível. Se você usa Server Components, prefira consultar auth() no servidor e passe os dados necessários para o componente. Em desenvolvimento, reinicie o servidor após alterar variáveis de ambiente.

Callback importado com caminho incorreto

Erros de módulo não encontrado geralmente indicam que o arquivo auth.ts está em outro diretório ou que o caminho relativo da rota está incorreto. Caminhos absolutos configurados no tsconfig.json, quando habilitados, ajudam a evitar diferenças entre arquivos.

Google exige verificação do aplicativo

Em alguns casos, o Google exibe um aviso de aplicativo não verificado. Isso pode ocorrer em projetos de teste ou em aplicações com escopos amplos. O painel do Google Cloud orienta sobre a verificação, os dados coletados e os motivos do pedido de acesso. A solução não é simplesmente esconder o aviso, mas concluir o processo apropriado e limitar as permissões solicitadas.

Considerações para produção e manutenção

Defina uma estratégia para os usuários do banco de dados

Não é necessário persistir todos os dados do Google em cada requisição. Uma prática comum é manter uma tabela de usuários internos com um identificador estável, vincular a conta Google a esse registro e usar a sessão para carregar as permissões. O callback signIn pode ser usado para criar ou localizar o usuário, sempre com validação dos dados recebidos.

Monitore falhas de autenticação

Registre eventos relevantes sem gravar senhas, tokens completos ou dados desnecessários. Erros de callback, respostas 401 e 403, tentativas repetidas e mudanças de configuração merecem acompanhamento. Isso ajuda a distinguir falha técnica, uso indevido e comportamento normal de um usuário que cancelou o login.

Atualize dependências com atenção

A linha Auth.js v5 passou a usar a marca Auth.js e possui diferenças em relação à série anterior. Ao atualizar o Next.js ou o pacote de autenticação, revise os guias de migração, as APIs usadas e as variáveis de ambiente. Teste o login, o logout, a renovação da sessão e o acesso às rotas protegidas em um ambiente separado.

Planeje a experiência em diferentes dispositivos

A pessoa pode abrir a autorização do Google em uma janela diferente, usar um perfil já conectado ou recusar o compartilhamento. Mensagens devem explicar que o acesso depende da conclusão do fluxo no Google. Evite afirmar que a conta foi vinculada antes de confirmar a sessão no servidor.

Perguntas Frequentes (FAQ)

NextAuth ainda é o nome correto da biblioteca?

Sim. O projeto Auth.js é a evolução do NextAuth. A documentação atual usa Auth.js como nome da marca, enquanto muitos exemplos e.discussões ainda employam NextAuth. Ao montar um projeto, confirme a versão da documentação e instale o pacote compatível, evitando misturar a API v4 com o Auth.js v5.

É necessário ter um banco de dados para usar login com Google?

Não necessariamente. O fluxo básico pode autenticar o usuário e manter a sessão sem um banco de dados. Um banco de dados é recomendável quando você precisa registrar contas internas, histórico, preferências, pedidos ou permissões que não devem ficar apenas na sessão.

O Google fornece automaticamente a senha do usuário?

Não. A autenticação acontece diretamente com o Google, que gerencia as credenciais da conta. Sua aplicação recebe uma identificação e os dados autorizados, como e-mail e informações de perfil dentro dos limites configurados.

Por que o callback termina em /api/auth/callback/google?

Esse é o caminho usado pelo NextAuth para receber a resposta do provedor OAuth. Ele deve ser cadastrado como URI de redirecionamento no cliente OAuth do Google Cloud. O caminho exato pode ser personalizado, mas qualquer alteração precisa ser refletida na configuração do provedor.

O login com Google protege toda a aplicação por padrão?

Não. Depois de autenticar, a aplicação precisa proteger as páginas e APIs que exigem sessão. Também deve validar as permissões no servidor para cada operação sensível. O login resolve a identidade do usuário, enquanto a autorização define o que essa pessoa pode fazer.

Posso usar o mesmo login com Google em vários ambientes?

Pode, mas cada cliente OAuth deve ter URIs de redirecionamento correspondentes ao ambiente. Em desenvolvimento, você normalmente autoriza localhost. Em produção, registra o domínio real com HTTPS. Manter as configurações separadas facilita evitar callbacks incorretos e facilita revisões de segurança.

Conclusão

O login com Google em Next.js com NextAuth é uma solução prática para reduzir o esforço de acesso e aproveitar o gerenciamento de identidade de um provedor conhecido. A implementação começa na criação do cliente OAuth no Google Cloud, passa pela configuração das variáveis de ambiente e termina na integração das rotas, do botão de acesso e da sessão.

O ponto mais importante é combinar convenience com responsabilidade. A autenticação precisa funcionar de forma simples para o visitante, mas o servidor deve continuar responsável por verificar a sessão, controlar permissões, proteger credenciais e validar os dados utilizados. Testar o fluxo completo em desenvolvimento e revisar a configuração antes da publicação evitaErrors frequentes.

Se você precisa de ajuda para colocar isso em prática, a Baita Site tem uma equipe especializada em sites, e-commerce, sistemas e inteligência artificial, com domínio total de WordPress. Fale com a gente e veja como podemos acelerar o seu projeto.

Referências consultadas, [Documentação oficial do Auth.js

Installation](https://authjs.dev/getting-started/installation), com orientações para instalação do Auth.js, criação do arquivo de configuração e configuração de variáveis de ambiente. Documentação oficial do Auth.js: NextAuth.js, com referências sobre provedores, sessão, callbacks e rotas de autenticação. Documentação oficial do Auth.js: Google Provider, com detalhes sobre a integração do Google Provider e configuração do consentimento OAuth. Documentação oficial do Next.js: App Router, com informações sobre a arquitetura de rotas, Server Components, Client Components e convenções do App Router. Google Cloud OAuth 2.0 para Applications Web, com o fluxo de autorização OAuth 2.0 para aplicações web, URIs de redirecionamento e tratamento do código de autorização.