Download nextjs auth0 - download do código-fonte nextjs auth0

nextjs auth0

Outro código-fonte

v3.5.0

Baixar

O SDK Auth0 Next.js é uma biblioteca para implementar autenticação de usuário em aplicativos Next.js.

Documentação - Primeiros passos - Referência da API - Feedback

Documentação

QuickStart – nosso guia para adicionar Auth0 ao seu aplicativo Next.js.
FAQs - Perguntas frequentes sobre nextjs-auth0.
Exemplos – muitos exemplos para seus diferentes casos de uso.
Segurança – Alguns avisos de segurança importantes que você deve verificar.
Arquitetura – Visão geral da arquitetura do SDK.
Teste - alguma ajuda para testar seu aplicativo nextjs-auth0.
Implantando - Como implantamos nosso aplicativo de exemplo no Vercel.
Site de documentos - explore nosso site de documentos e saiba mais sobre o Auth0.

Começando

Instalação

Usando npm:

 instalação npm @auth0/nextjs-auth0

Esta biblioteca requer Node.js 16 LTS e versões LTS mais recentes.

Configuração Auth0

Crie um aplicativo da Web normal no painel Auth0.

Se você estiver usando um aplicativo existente , verifique se definiu as seguintes configurações em seu aplicativo Web normal:
Clique na guia “Configurações” da página do seu aplicativo.
Role para baixo e clique no link "Mostrar configurações avançadas".
Em "Configurações avançadas", clique na guia "OAuth".
Certifique-se de que "Algoritmo de assinatura JsonWebToken" esteja definido como RS256 e que "Conformidade com OIDC" esteja ativado.

Em seguida, configure os seguintes URLs para seu aplicativo na seção "URIs do aplicativo" da página "Configurações":

URLs de retorno de chamada permitidos : http://localhost:3000/api/auth/callback
URLs de logout permitidos : http://localhost:3000/

Anote os valores Client ID , Client Secret e Domain na seção "Informações básicas". Você precisará desses valores na próxima etapa.

Configuração básica

Configurar o aplicativo

Você precisa permitir que seu aplicativo Next.js se comunique corretamente com Auth0. Você pode fazer isso criando um arquivo .env.local no diretório raiz do projeto que define os valores de configuração Auth0 necessários da seguinte forma:

 # Um valor longo e secreto usado para criptografar o cookie da sessãoAUTH0_SECRET='LONG_RANDOM_VALUE'# O URL base do seu aplicativoAUTH0_BASE_URL='http://localhost:3000'# O URL do seu domínio de locatário Auth0AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Cliente do seu aplicativo Auth0 IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# O segredo do cliente do seu aplicativo Auth0AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

Você pode executar o seguinte comando para gerar uma string adequada para o valor AUTH0_SECRET :

 nó -e "console.log(crypto.randomBytes(32).toString('hex'))"

Você pode ver uma lista completa de opções de configuração do Auth0 na seção "Propriedades de configuração" do documento "Configuração do módulo".

Para obter mais detalhes sobre o carregamento de variáveis de ambiente em Next.js, visite o documento "Variáveis de Ambiente".

Adicione handleAuth() ao seu aplicativo, que cria os seguintes manipuladores de rota nos bastidores que executam diferentes partes do fluxo de autenticação:

/api/auth/login : seu aplicativo Next.js redireciona os usuários para seu provedor de identidade para que eles façam login (opcionalmente, você pode passar um parâmetro returnTo para retornar a uma URL relativa personalizada após o login, por exemplo /api/auth/login?returnTo=/profile ).
/api/auth/callback : seu provedor de identidade redireciona os usuários para esta rota depois que eles fazem login com sucesso.
/api/auth/logout : seu aplicativo Next.js desconecta o usuário.
/api/auth/me : você pode buscar informações de perfil do usuário no formato JSON.

Continue a configuração dependendo do seu roteador:

Roteador de página
Roteador de aplicativos

Roteador de página

Adicione a rota de API dinâmica

Crie um manipulador de rota de API dinâmica no diretório /pages/api :

Crie um diretório auth no diretório /pages/api/ .
Crie um arquivo [auth0].js no diretório auth recém-criado.

O caminho para o arquivo de rota da API dinâmica seria /pages/api/auth/[auth0].js . Preencha esse arquivo da seguinte maneira:

 importar { handleAuth } de '@auth0/nextjs-auth0'; exportar padrão handleAuth();

Adicione o UserProvider ao aplicativo personalizado

Envolva seu componente pages/_app.js com o componente UserProvider :

 // páginas/_app.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';exportar função padrão App({Component, pageProps }) {
  return (<UserProvider> <Component {...pageProps} /></UserProvider>
  );}

Consumir autenticação

Agora você pode determinar se um usuário está autenticado verificando se o objeto user retornado pelo gancho useUser() está definido. Você também pode fazer login ou logout de seus usuários da camada frontend de seu aplicativo Next.js, redirecionando-os para a rota apropriada gerada automaticamente:

 // páginas/index.jsimport { useUser } de '@auth0/nextjs-auth0/client';exportar função padrão Index() {
  const {usuário, erro, isLoading} = useUser();

  if (isLoading) return <div>Carregando...</div>;
  if (erro) return <div>{error.message}</div>;

  if (usuário) {return ( <div>Bem-vindo {user.name}! <a href="/api/auth/logout">Sair</a> </div>);
  }

  return <a href="/api/auth/login">Login</a>;}

As próximas regras de linting podem sugerir o uso do componente Link em vez de uma tag âncora. O componente Link destina-se a realizar transições do lado do cliente entre páginas. Como os links apontam para uma rota de API e não para uma página, você deve mantê-los como tags âncora.

Roteador de aplicativos

Confira Usando este SDK com componentes do React Server antes de continuar.

Adicione a rota de API dinâmica

Crie um manipulador de rota de API dinâmico e abrangente no diretório /app/api (estritamente falando, você não precisa colocar rotas de API em /api , mas mantemos a convenção para simplificar):

Crie um diretório api no diretório /app/ .
Crie um diretório auth no diretório /app/api/ recém-criado.
Crie um diretório [auth0] no diretório auth recém-criado.
Crie um arquivo route.js no diretório [auth0] recém-criado.

O caminho para o arquivo de rota da API dinâmica será /app/api/auth/[auth0]/route.js . Preencha esse arquivo da seguinte maneira:

 importar {handleAuth} de '@auth0/nextjs-auth0'; exportar const GET = handleAuth();

Adicione o `UserProvider` ao seu layout

Envolva seu componente app/layout.js com o componente UserProvider :

 // app/layout.jsimport React from 'react';import { UserProvider } from '@auth0/nextjs-auth0/client';exportar função padrão App({ filhos }) {
  return (<UserProvider> <body>{filhos}</body></UserProvider>
  );}

Consumir autenticação

Agora você pode determinar se um usuário está autenticado verificando se o objeto user retornado pelo gancho useUser() está definido. Você também pode fazer login ou logout de seus usuários da camada frontend de seu aplicativo Next.js, redirecionando-os para a rota apropriada gerada automaticamente:

 // pages/index.js'use client';import { useUser } from '@auth0/nextjs-auth0/client';exportar função padrão Index() {
  const {usuário, erro, isLoading} = useUser();

  if (isLoading) return <div>Carregando...</div>;
  if (erro) return <div>{error.message}</div>;

  if (usuário) {return ( <div>Bem-vindo {user.name}! <a href="/api/auth/logout">Sair</a> </div>);
  }

  return <a href="/api/auth/login">Login</a>;}

As próximas regras de linting podem sugerir o uso do componente Link em vez de uma tag âncora. O componente Link destina-se a realizar transições do lado do cliente entre páginas. Como os links apontam para uma rota de API e não para uma página, você deve mantê-los como tags âncora.

Usando este SDK com componentes do React Server

Os componentes do servidor no App Directory (incluindo páginas e layouts) não podem gravar em um cookie.

Se você depende apenas dos Componentes do Servidor para ler e atualizar sua sessão, você deve estar ciente do seguinte:

Se você tiver uma sessão contínua (o padrão para este SDK), a expiração não será atualizada quando o usuário visitar seu site. Portanto, a sessão pode expirar mais cedo do que o esperado (você pode usar withMiddlewareAuthRequired para atenuar isso).
Se você atualizar o token de acesso, o novo token de acesso não persistirá na sessão. Portanto, as tentativas subsequentes de obter um token de acesso sempre resultarão na atualização do token de acesso expirado na sessão.
Se você fizer outras atualizações na sessão, elas não serão persistidas entre as solicitações.

O cookie pode ser escrito a partir de middleware, manipuladores de rotas e ações do servidor.

Para outros exemplos abrangentes, consulte o documento EXAMPLES.md.

Referência de API

Servidor

Para nó

import * from @auth0/nextjs-auth0

Para tempo de execução do Edge

import * from @auth0/nextjs-auth0/edge

Opções de configuração e variáveis de ambiente
initAuth0
identificadorAuth
identificadorLogin
identificadorCallback
identificadorLogout
identificadorProfile
comApiAuthObrigatório
withPageAuthRequired
getSession
sessão de atualização
getAccessToken
withMiddlewareAuthRequired (somente Edge)

Cliente (para o navegador)

import * from @auth0/nextjs-auth0/client

Provedor de usuário
usarUsuário
withPageAuthRequired

Testando ajudantes

import * from @auth0/nextjs-auth0/testing

gerarSessionCookie

Visite os documentos da API gerados automaticamente para obter mais detalhes

Cookies e segurança

Todos os cookies serão definidos como HttpOnly, SameSite=Lax e serão definidos como Secure se o AUTH0_BASE_URL do aplicativo for https .

A configuração HttpOnly garantirá que o JavaScript do lado do cliente não consiga acessar o cookie para reduzir a superfície de ataque de ataques XSS.

A configuração SameSite=Lax ajudará a mitigar ataques CSRF. Saiba mais sobre o SameSite lendo a postagem do blog "Próximas mudanças no comportamento do navegador: o que os desenvolvedores precisam saber".

Cache e Segurança

Muitos provedores de hospedagem oferecem cache de seu conteúdo na borda para fornecer dados aos usuários o mais rápido possível. Por exemplo, a Vercel armazenará em cache seu conteúdo na Vercel Edge Network para todo o conteúdo estático e funções sem servidor se você fornecer os cabeçalhos de cache necessários em sua resposta.

Geralmente é uma má ideia armazenar em cache qualquer resposta que exija autenticação, mesmo que o conteúdo da resposta pareça seguro para armazenamento em cache, pode haver outros dados na resposta que não o são.

Este SDK oferece uma sessão contínua por padrão, o que significa que qualquer resposta que leia a sessão terá um cabeçalho Set-Cookie para atualizar a expiração do cookie. Vercel e potencialmente outros provedores de hospedagem incluem o cabeçalho Set-Cookie na resposta em cache, portanto, mesmo que você ache que o conteúdo da resposta pode ser armazenado em cache publicamente, o cabeçalho Set-Cookie das respostas não pode.

Verifique as regras de cache do seu provedor de hospedagem, mas em geral você nunca deve armazenar em cache respostas que exigem autenticação ou mesmo tocar na sessão para verificar a autenticação (por exemplo, ao usar withApiAuthRequired , withPageAuthRequired ou mesmo apenas getSession ou getAccessToken ).

Tratamento de erros e segurança

Os erros provenientes de Auth0 no retorno de chamada redirect_uri podem conter entrada refletida do usuário por meio do error do OpenID Connect e do parâmetro de consulta error_description . Por causa disso, fazemos alguns escapes básicos nas propriedades message , error e error_description do IdentityProviderError .

Mas, se você escrever seu próprio manipulador de erros, não deverá renderizar a message de erro ou as propriedades error e error_description sem usar um mecanismo de modelo que irá escapá-los adequadamente para outros contextos HTML primeiro.

Caminho Base e Roteamento Internacionalizado

Com Next.js você pode implantar um aplicativo Next.js em um subcaminho de um domínio usando Base Path e servir rotas internacionalizadas (i18n) usando roteamento internacionalizado.

Se você usar esses recursos, os URLs do seu aplicativo serão alterados e, portanto, os URLs para as rotas nextjs-auth0 serão alterados. Para acomodar isso, existem vários locais no SDK onde você pode personalizar o URL.

Por exemplo, se basePath: '/foo' você deve acrescentar isso ao loginUrl e profileUrl especificados em seu Auth0Provider :

 // _app.jsxfunction App({ Componente, pageProps }) {
  return (<UserProvider loginUrl="/foo/api/auth/login" profileUrl="/foo/api/auth/me"> <Component {...pageProps} /></UserProvider>
  );}

Além disso, quaisquer links para login ou logout devem incluir basePath :

 <a href="/foo/api/auth/login">Login</a><br /><a href="/foo/api/auth/logout">Sair</a>

Você deve configurar o baseUrl (ou a variável de ambiente AUTH0_BASE_URL ). Por exemplo:

 # .env.localAUTH0_BASE_URL=http://localhost:3000/foo

Para quaisquer páginas protegidas com o lado do servidor withPageAuthRequired, você deve atualizar o parâmetro returnTo dependendo do basePath e locale , se necessário.

 // ./pages/my-ssr-page.jsxexport padrão MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO: implemente getFullReturnTo com base em ctx.resolvedUrl, ctx.locale
  // e as configurações basePath e i18n do seu next.config.js.
  return '/foo/en-US/my-ssr-page';};export const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  retornar withPageAuthRequired({ returnTo })(ctx);};

Comparação com o SDK Auth0 React

Também fornecemos um SDK Auth0 React, auth0-react, que pode ser adequado para seu aplicativo Next.js.

O modelo de segurança SPA usado por auth0-react é diferente do modelo de segurança de aplicativo Web usado por este SDK. Resumindo, este SDK protege páginas e rotas API com uma sessão de cookies (ver “Cookies e Segurança”). Uma biblioteca SPA como auth0-react armazenará o token de ID do usuário e o token de acesso diretamente no navegador e os usará para acessar APIs externas diretamente.

Você deve estar ciente das implicações de segurança de ambos os modelos. No entanto, o auth0-react pode ser mais adequado às suas necessidades se você atender a qualquer um dos seguintes cenários:

Você está usando exportação de HTML estático com Next.js.
Você não precisa acessar os dados do usuário durante a renderização no servidor.
Você deseja obter o token de acesso e chamar APIs externas diretamente da camada frontend, em vez de usar rotas de API Next.js como proxy para chamar APIs externas.

Teste

Por padrão, o SDK cria e gerencia uma instância singleton para ser executada durante a vida útil do aplicativo. Ao testar seu aplicativo, pode ser necessário redefinir esta instância, para que seu estado não vaze entre os testes.

Se você estiver usando Jest, recomendamos usar jest.resetModules() após cada teste. Alternativamente, você pode criar sua própria instância do SDK, para que ela possa ser recriada entre os testes.

Para testes ponta a ponta, veja como usamos um provedor OIDC simulado.

Implantando

Para implantação, dê uma olhada em como implantamos nosso aplicativo de exemplo no Vercel.

Contribuindo

Agradecemos o feedback e a contribuição para este repositório! Antes de começar, leia o seguinte:

Diretrizes gerais de contribuição do Auth0
Diretrizes do código de conduta do Auth0
O guia de contribuição deste repositório

Relatório de vulnerabilidade

Não relate vulnerabilidades de segurança no rastreador público de problemas do GitHub. O Programa de Divulgação Responsável detalha o procedimento para divulgação de questões de segurança.