Descarga de nextjs auth0 - Descarga del código fuente de nextjs auth0

nextjs auth0

Otro código fuente

v3.5.0

Descargar

El SDK de Auth0 Next.js es una biblioteca para implementar la autenticación de usuarios en aplicaciones Next.js.

Documentación - Primeros pasos - Referencia de API - Comentarios

Documentación

QuickStart: nuestra guía para agregar Auth0 a su aplicación Next.js.
Preguntas frecuentes: preguntas frecuentes sobre nextjs-auth0.
Ejemplos: muchos ejemplos para sus diferentes casos de uso.
Seguridad: algunos avisos de seguridad importantes que debes consultar.
Arquitectura: descripción general de la arquitectura del SDK.
Pruebas: algo de ayuda para probar su aplicación nextjs-auth0.
Implementación: cómo implementamos nuestra aplicación de ejemplo en Vercel.
Sitio de documentos: explore nuestro sitio de documentos y obtenga más información sobre Auth0.

Empezando

Instalación

Usando npm:

 instalación npm @auth0/nextjs-auth0

Esta biblioteca requiere Node.js 16 LTS y versiones LTS más recientes.

Configuración de autenticación 0

Cree una aplicación web normal en el panel de Auth0.

Si está utilizando una aplicación existente , verifique que haya configurado las siguientes configuraciones en su aplicación web normal:
Haga clic en la pestaña "Configuración" de la página de su aplicación.
Desplácese hacia abajo y haga clic en el enlace "Mostrar configuración avanzada".
En "Configuración avanzada", haga clic en la pestaña "OAuth".
Asegúrese de que el "Algoritmo de firma JsonWebToken" esté configurado en RS256 y que "Conforme a OIDC" esté habilitado.

A continuación, configure las siguientes URL para su aplicación en la sección "URI de aplicación" de la página "Configuración":

URL de devolución de llamada permitidas : http://localhost:3000/api/auth/callback
URL de cierre de sesión permitidas : http://localhost:3000/

Tome nota de los valores de ID de cliente , Secreto de cliente y Dominio en la sección "Información básica". Necesitará estos valores en el siguiente paso.

Configuración básica

Configurar la aplicación

Debe permitir que su aplicación Next.js se comunique correctamente con Auth0. Puede hacerlo creando un archivo .env.local en el directorio raíz de su proyecto que defina los valores de configuración de Auth0 necesarios de la siguiente manera:

 # Un valor secreto largo utilizado para cifrar la cookie de sesiónAUTH0_SECRET='LONG_RANDOM_VALUE'# La URL base de su aplicaciónAUTH0_BASE_URL='http://localhost:3000'# La URL de su dominio de inquilino Auth0AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# El cliente de su aplicación Auth0 IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# El secreto del cliente de su aplicación Auth0AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

Puede ejecutar el siguiente comando para generar una cadena adecuada para el valor AUTH0_SECRET :

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

Puede ver una lista completa de las opciones de configuración de Auth0 en la sección "Propiedades de configuración" del documento "Configuración del módulo".

Para obtener más detalles sobre cómo cargar variables de entorno en Next.js, visite el documento "Variables de entorno".

Agregue handleAuth() a su aplicación, lo que crea los siguientes controladores de ruta internos que realizan diferentes partes del flujo de autenticación:

/api/auth/login : su aplicación Next.js redirige a los usuarios a su proveedor de identidad para que inicien sesión (opcionalmente, puede pasar un parámetro returnTo para regresar a una URL relativa personalizada después de iniciar sesión, por ejemplo /api/auth/login?returnTo=/profile ).
/api/auth/callback : su proveedor de identidad redirige a los usuarios a esta ruta después de iniciar sesión correctamente.
/api/auth/logout : su aplicación Next.js cierra la sesión del usuario.
/api/auth/me : puede recuperar información del perfil de usuario en formato JSON.

Continúe con la configuración dependiendo de su enrutador:

Enrutador de página
Enrutador de aplicaciones

Enrutador de página

Agregar la ruta API dinámica

Cree un controlador de ruta API dinámico en el directorio /pages/api :

Cree un directorio auth en el directorio /pages/api/ .
Cree un archivo [auth0].js en el directorio auth recién creado.

La ruta a su archivo de ruta API dinámica sería /pages/api/auth/[auth0].js . Complete ese archivo de la siguiente manera:

 importar {handleAuth} desde '@auth0/nextjs-auth0'; exportar handleAuth() predeterminado;

Agregue el UserProvider a la aplicación personalizada

Envuelva su componente pages/_app.js con el componente UserProvider :

 // páginas/_app.jsimport Reaccionar desde 'react';importar {UserProvider} desde '@auth0/nextjs-auth0/client';exportar función predeterminada App({ Component, pageProps }) {
  return (<UserProvider> <Componente {...pageProps} /></UserProvider>
  );}

Consumir autenticación

Ahora puede determinar si un usuario está autenticado comprobando que el objeto user devuelto por el gancho useUser() esté definido. También puede iniciar o cerrar sesión con sus usuarios desde la capa frontal de su aplicación Next.js redirigiéndolos a la ruta apropiada generada automáticamente:

 // páginas/index.jsimport { useUser } de '@auth0/nextjs-auth0/client'; exportar función predeterminada Index() {
  const {usuario, error, está cargando} = useUsuario();

  si (isLoading) return <div>Cargando...</div>;
  si (error) devuelve <div>{error.message}</div>;

  if (usuario) {return ( <div>¡Bienvenido {user.name}! <a href="/api/auth/logout">Cerrar sesión</a> </div>);
  }

  return <a href="/api/auth/login">Iniciar sesión</a>;}

Las siguientes reglas de linting podrían sugerir el uso del componente Link en lugar de una etiqueta de anclaje. El componente Link está destinado a realizar transiciones del lado del cliente entre páginas. Como los enlaces apuntan a una ruta API y no a una página, debes mantenerlos como etiquetas de anclaje.

Enrutador de aplicaciones

Consulte Uso de este SDK con componentes de React Server antes de continuar.

Agregar la ruta API dinámica

Cree un controlador de ruta API dinámico y general en el directorio /app/api (estrictamente hablando, no necesita colocar rutas API en /api , pero mantenemos la convención para simplificar):

Cree un directorio api en el directorio /app/ .
Cree un directorio auth en el directorio /app/api/ recién creado.
Cree un directorio [auth0] en el directorio auth recién creado.
Cree un archivo route.js en el directorio [auth0] recién creado.

La ruta a su archivo de ruta API dinámica será /app/api/auth/[auth0]/route.js . Complete ese archivo de la siguiente manera:

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

Agregue el `UserProvider` a su diseño

Envuelva su componente app/layout.js con el componente UserProvider :

 // app/layout.jsimport Reaccionar desde 'react'; importar { UserProvider } desde '@auth0/nextjs-auth0/client'; exportar función predeterminada App({ niños }) {
  return (<UserProvider> <body>{children}</body></UserProvider>
  );}

Consumir autenticación

Ahora puede determinar si un usuario está autenticado comprobando que el objeto user devuelto por el gancho useUser() esté definido. También puede iniciar o cerrar sesión con sus usuarios desde la capa frontal de su aplicación Next.js redirigiéndolos a la ruta apropiada generada automáticamente:

 // páginas/index.js'usa cliente';importar { usarUsuario } de '@auth0/nextjs-auth0/client';exportar función predeterminada Index() {
  const {usuario, error, está cargando} = useUsuario();

  si (isLoading) return <div>Cargando...</div>;
  si (error) devuelve <div>{error.message}</div>;

  if (usuario) {return ( <div>¡Bienvenido {user.name}! <a href="/api/auth/logout">Cerrar sesión</a> </div>);
  }

  return <a href="/api/auth/login">Iniciar sesión</a>;}

Las siguientes reglas de linting podrían sugerir el uso del componente Link en lugar de una etiqueta de anclaje. El componente Link está destinado a realizar transiciones del lado del cliente entre páginas. Como los enlaces apuntan a una ruta API y no a una página, debes mantenerlos como etiquetas de anclaje.

Usando este SDK con componentes de React Server

Los componentes del servidor en el directorio de aplicaciones (incluidas páginas y diseños) no pueden escribir en una cookie.

Si depende únicamente de los componentes del servidor para leer y actualizar su sesión, debe tener en cuenta lo siguiente:

Si tiene una sesión continua (la opción predeterminada para este SDK), la caducidad no se actualizará cuando el usuario visite su sitio. Por lo tanto, la sesión puede caducar antes de lo esperado (puede usar withMiddlewareAuthRequired para mitigar esto).
Si actualiza el token de acceso, el nuevo token de acceso no persistirá en la sesión. Por lo tanto, los intentos posteriores de obtener un token de acceso siempre resultarán en la actualización del token de acceso caducado en la sesión.
Si realiza otras actualizaciones en la sesión, no se mantendrán entre solicitudes.

La cookie puede escribirse desde middleware, controladores de ruta y acciones del servidor.

Para ver otros ejemplos completos, consulte el documento EXAMPLES.md.

Referencia de API

Servidor

Para nodo

import * from @auth0/nextjs-auth0

Para el tiempo de ejecución de Edge

import * from @auth0/nextjs-auth0/edge

Opciones de configuración y variables de entorno
initAuth0
manejarAuth
manejarIniciar sesión
manejarDevolución de llamada
manejarCerrar sesión
manejarPerfil
conApiAuthRequerido
conPageAuthRequired
obtener sesión
sesión de actualización
obtenerToken de acceso
withMiddlewareAuthRequired (solo Edge)

Cliente (para el navegador)

import * from @auth0/nextjs-auth0/client

Proveedor de usuarios
utilizarUsuario
conPageAuthRequired

Ayudantes de prueba

import * from @auth0/nextjs-auth0/testing

generarCookie de sesión

Visite los documentos API generados automáticamente para obtener más detalles.

Cookies y seguridad

Todas las cookies se configurarán en HttpOnly, SameSite=Lax y se configurarán en Secure si AUTH0_BASE_URL de la aplicación es https .

La configuración HttpOnly garantizará que JavaScript del lado del cliente no pueda acceder a la cookie para reducir la superficie de ataque de los ataques XSS.

La configuración SameSite=Lax ayudará a mitigar los ataques CSRF. Obtenga más información sobre SameSite leyendo la publicación del blog "Próximos cambios en el comportamiento del navegador: lo que los desarrolladores deben saber".

Almacenamiento en caché y seguridad

Muchos proveedores de alojamiento ofrecerán almacenar en caché su contenido en el borde para entregar datos a sus usuarios lo más rápido posible. Por ejemplo, Vercel almacenará en caché su contenido en Vercel Edge Network para todo el contenido estático y las funciones sin servidor si proporciona los encabezados de almacenamiento en caché necesarios en su respuesta.

Generalmente es una mala idea almacenar en caché cualquier respuesta que requiera autenticación, incluso si el contenido de la respuesta parece seguro para almacenarse en caché, puede haber otros datos en la respuesta que no lo sean.

Este SDK ofrece una sesión continua de forma predeterminada, lo que significa que cualquier respuesta que lea la sesión tendrá un encabezado Set-Cookie para actualizar la caducidad de la cookie. Vercel y potencialmente otros proveedores de alojamiento incluyen el encabezado Set-Cookie en la respuesta almacenada en caché, por lo que incluso si cree que el contenido de la respuesta se puede almacenar en caché públicamente, el encabezado Set-Cookie de las respuestas no puede hacerlo.

Verifique las reglas de almacenamiento en caché de su proveedor de alojamiento, pero en general nunca debe almacenar en caché las respuestas que requieren autenticación o incluso tocar la sesión para verificar la autenticación (por ejemplo, cuando usa withApiAuthRequired , withPageAuthRequired o incluso simplemente getSession o getAccessToken ).

Manejo de errores y seguridad

Los errores que provienen de Auth0 en la devolución de llamada redirect_uri pueden contener entradas reflejadas del usuario a través del error de OpenID Connect y el parámetro de consulta error_description . Debido a esto, realizamos algunos escapes básicos en las propiedades message , error y error_description de IdentityProviderError .

Pero, si escribe su propio controlador de errores, no debe representar el message de error ni las propiedades error y error_description sin utilizar primero un motor de plantillas que los escape correctamente para otros contextos HTML.

Ruta base y enrutamiento internacionalizado

Con Next.js puede implementar una aplicación Next.js en una subruta de un dominio usando Base Path y servir rutas internacionalizadas (i18n) usando enrutamiento internacionalizado.

Si utiliza estas funciones, las URL de su aplicación cambiarán y, por lo tanto, cambiarán las URL de las rutas nextjs-auth0. Para adaptarse a esto, hay varios lugares en el SDK donde puede personalizar la URL.

Por ejemplo, si basePath: '/foo' debe anteponer esto a loginUrl y profileUrl especificados en su Auth0Provider :

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

Además, cualquier enlace para iniciar sesión o cerrar sesión debe incluir basePath :

 <a href="/foo/api/auth/login">Iniciar sesión</a><br /><a href="/foo/api/auth/logout">Cerrar sesión</a>

Debe configurar baseUrl (o la variable de entorno AUTH0_BASE_URL ). Por ejemplo:

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

Para cualquier página que esté protegida con el lado del servidor conPageAuthRequired, debe actualizar el parámetro returnTo según basePath y locale , si es necesario.

 // ./pages/my-ssr-page.jsxexport predeterminado MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO: implementar getFullReturnTo basado en ctx.resolvedUrl, ctx.locale
  // y la configuración basePath e i18n de next.config.js.
  return '/foo/en-US/mi-página-ssr';};exportar const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  return withPageAuthRequired({ returnTo })(ctx);};

Comparación con el SDK de Auth0 React

También proporcionamos un SDK de Auth0 React, auth0-react, que puede ser adecuado para su aplicación Next.js.

El modelo de seguridad SPA utilizado por auth0-react es diferente del modelo de seguridad de la aplicación web utilizado por este SDK. En definitiva, este SDK protege páginas y rutas API con una sesión de cookies (ver "Cookies y Seguridad"). Una biblioteca SPA como auth0-react almacenará el token de identificación del usuario y el token de acceso directamente en el navegador y los utilizará para acceder a las API externas directamente.

Debe tener en cuenta las implicaciones de seguridad de ambos modelos. Sin embargo, auth0-react puede ser más adecuado para sus necesidades si cumple alguno de los siguientes escenarios:

Está utilizando la exportación de HTML estático con Next.js.
No es necesario acceder a los datos del usuario durante la renderización del lado del servidor.
Desea obtener el token de acceso y llamar a las API externas directamente desde la capa de interfaz en lugar de utilizar las rutas API de Next.js como proxy para llamar a las API externas.

Pruebas

De forma predeterminada, el SDK crea y administra una instancia única para ejecutarla durante toda la vida útil de la aplicación. Al probar su aplicación, es posible que necesite restablecer esta instancia para que su estado no se filtre entre pruebas.

Si está utilizando Jest, le recomendamos utilizar jest.resetModules() después de cada prueba. Alternativamente, puede considerar la posibilidad de crear su propia instancia del SDK, para poder recrearla entre pruebas.

Para pruebas de un extremo a otro, observe cómo utilizamos un proveedor OIDC simulado.

Implementando

Para la implementación, observe cómo implementamos nuestra aplicación de ejemplo en Vercel.

Contribuyendo

¡Apreciamos los comentarios y las contribuciones a este repositorio! Antes de comenzar, lea lo siguiente:

Pautas generales de contribución de Auth0
Directrices del código de conducta de Auth0
Guía de contribución de este repositorio.

Informes de vulnerabilidad

No informe vulnerabilidades de seguridad en el rastreador de problemas público de GitHub. El Programa de Divulgación Responsable detalla el procedimiento para revelar problemas de seguridad.