authkit nextjs

Biblioteca AuthKit Next.js

La biblioteca AuthKit para Next.js proporciona ayudas prácticas para la autenticación y la gestión de sesiones utilizando WorkOS y AuthKit con Next.js.

Nota: Esta biblioteca está diseñada para usarse con Next.js App Router.

Instalación

Instale el paquete con:

 npm i @workos-inc/authkit-nextjs

o

 yarn add @workos-inc/authkit-nextjs

Vídeotutorial

Pre-vuelo

Asegúrese de que los siguientes valores estén presentes en su archivo de variables de entorno .env.local . El ID del cliente y la clave API se pueden encontrar en el panel de WorkOS, y el URI de redireccionamiento también se puede configurar allí.

WORKOS_CLIENT_ID= " client_... " # retrieved from the WorkOS dashboard
WORKOS_API_KEY= " sk_test_... " # retrieved from the WorkOS dashboard
WORKOS_COOKIE_PASSWORD= " <your password> " # generate a secure password here
NEXT_PUBLIC_WORKOS_REDIRECT_URI= " http://localhost:3000/callback " # configured in the WorkOS dashboard

WORKOS_COOKIE_PASSWORD es la clave privada utilizada para cifrar la cookie de sesión. Debe tener al menos 32 caracteres. Puede utilizar el generador 1Password o la biblioteca openssl para generar una contraseña segura a través de la línea de comando:

 openssl rand -base64 24

Para utilizar el método signOut , deberá configurar la página de inicio de su aplicación en la configuración del panel de WorkOS en "Redirecciones".

Configuración opcional

Ciertas variables de entorno son opcionales y se pueden utilizar para depurar o configurar las opciones de cookies.

WORKOS_COOKIE_MAX_AGE= ' 600 ' # maximum age of the cookie in seconds. Defaults to 400 days, the maximum allowed in Chrome
WORKOS_COOKIE_DOMAIN= ' example.com '
WORKOS_COOKIE_NAME= ' authkit-cookie '
WORKOS_API_HOSTNAME= ' api.workos.com ' # base WorkOS API URL
WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
WORKOS_API_PORT=3000 # port to use for API calls

WORKOS_COOKIE_DOMAIN se puede utilizar para compartir sesiones de WorkOS entre aplicaciones/dominios. Nota: WORKOS_COOKIE_PASSWORD debería ser el mismo en todas las aplicaciones/dominios. No es necesario para la mayoría de los casos de uso.

Configuración

Ruta de devolución de llamada

WorkOS requiere que tenga una URL de devolución de llamada a la que redirigir a los usuarios después de que se hayan autenticado. En su aplicación Next.js, exponga una ruta API y agregue lo siguiente.

 import { handleAuth } from '@workos-inc/authkit-nextjs' ;

export const GET = handleAuth ( ) ;

Asegúrese de que esta ruta coincida con la variable WORKOS_REDIRECT_URI y el URI de redireccionamiento configurado en su panel de WorkOS. Por ejemplo, si su URI de redireccionamiento es http://localhost:3000/auth/callback , entonces colocaría el código anterior en /app/auth/callback/route.ts .

También puedes controlar la ruta a la que se enviará al usuario después de iniciar sesión pasando una opción returnPathname para handleAuth de esta manera:

 export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ;

handleAuth se puede utilizar con varias opciones.

Opción	Por defecto	Descripción
returnPathname	/	El nombre de la ruta a la que redirigir al usuario después de iniciar sesión
baseURL	undefined	La URL base que se utilizará para el URI de redireccionamiento en lugar del de la solicitud. Útil si la aplicación se ejecuta en un contenedor como Docker donde el nombre de host puede ser diferente al de la solicitud.

software intermedio

Esta biblioteca se basa en el middleware Next.js para proporcionar gestión de sesiones para rutas. Coloque lo siguiente en su archivo middleware.ts en la raíz de su proyecto:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

El middleware se puede configurar con varias opciones.

Opción	Por defecto	Descripción
redirectUri	undefined	Se utiliza en casos en los que necesita que su URI de redireccionamiento se establezca dinámicamente (por ejemplo, implementaciones de vista previa de Vercel)
middlewareAuth	undefined	Se utiliza para configurar las opciones de autenticación de middleware. Consulte autenticación de middleware para obtener más detalles.
debug	false	Habilita los registros de depuración.
signUpPaths	[]	Se utiliza para especificar rutas que deben utilizar la sugerencia en pantalla de "registro" al redirigir a AuthKit.

URI de redireccionamiento personalizado

En los casos en los que necesite que su URI de redireccionamiento se configure dinámicamente (por ejemplo, implementaciones de vista previa de Vercel), use la opción redirectUri en authkitMiddleware :

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  redirectUri : 'https://foo.example.com/callback' ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

Los URI de redireccionamiento personalizados se utilizarán sobre un URI de redireccionamiento configurado en las variables de entorno.

Uso

Envuelva su aplicación en AuthKitProvider

Utilice AuthKitProvider para ajustar el diseño de su aplicación, lo que agrega algunas protecciones para los casos extremos de autenticación.

 import { AuthKitProvider } from '@workos-inc/authkit-nextjs' ;

export default function RootLayout ( { children } : { children : React . ReactNode } ) {
  return (
    < html lang = "en" >
      < body >
        < AuthKitProvider > { children } < / AuthKitProvider >
      < / body >
    < / html >
  ) ;
}

Obtener el usuario actual

Para las páginas en las que desea mostrar una vista de inicio y cierre de sesión, utilice withAuth para recuperar el perfil de usuario de WorkOS.

 import Link from 'next/link' ;
import { getSignInUrl , getSignUpUrl , withAuth , signOut } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user } = await withAuth ( ) ;

  if ( ! user ) {
    // Get the URL to redirect the user to AuthKit to sign in
    const signInUrl = await getSignInUrl ( ) ;

    // Get the URL to redirect the user to AuthKit to sign up
    const signUpUrl = await getSignUpUrl ( ) ;

    return (
      < >
        < Link href = { signInUrl } > Log in < / Link >
        < Link href = { signUpUrl } > Sign Up < / Link >
      < / >
    ) ;
  }

  return (
    < form
      action = { async ( ) => {
        'use server' ;
        await signOut ( ) ;
      } }
    >
      < p > Welcome back { user ?. firstName && `, ${ user ?. firstName } ` } < / p >
      < button type = "submit" > Sign out < / button >
    < / form >
  ) ;
}

Requerir autenticación

Para las páginas donde es obligatorio un usuario registrado, puede utilizar la opción ensureSignedIn :

 const { user } = await withAuth ( { ensureSignedIn : true } ) ;

Habilitar ensureSignedIn redirigirá a los usuarios a AuthKit si intentan acceder a la página sin estar autenticados.

autenticación de middleware

El comportamiento predeterminado de esta biblioteca es solicitar autenticación mediante el método withAuth por página. Hay algunos casos de uso en los que no desea llamar withAuth (por ejemplo, no necesita datos de usuario para su página) o si prefiere un enfoque "seguro por defecto" donde cada ruta definida en su comparador de middleware esté protegida. a menos que se especifique lo contrario. En esos casos, puede optar por utilizar la autenticación de middleware:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  middlewareAuth : {
    enabled : true ,
    unauthenticatedPaths : [ '/' , '/about' ] ,
  } ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin/:path*' , '/about' ] } ;

En el ejemplo anterior, la página /admin requerirá que un usuario inicie sesión, mientras que se puede acceder a / y /about sin iniciar sesión.

unauthenticatedPaths utiliza la misma lógica global que el comparador Next.js.

Recuperar sesión en middleware

A veces es útil comprobar la sesión del usuario si desea crear middleware personalizado. El método auxiliar getSession recuperará la sesión de la cookie y verificará el token de acceso.

 import { authkitMiddleware , getSession } from '@workos-inc/authkit-nextjs' ;
import { NextRequest , NextFetchEvent } from 'next/server' ;

export default async function middleware ( request : NextRequest , event : NextFetchEvent ) {
  // authkitMiddleware will handle refreshing the session if the access token has expired
  const response = await authkitMiddleware ( ) ( request , event ) ;

  // If session is undefined, the user is not authenticated
  const session = await getSession ( response ) ;

  // ...add additional middleware logic here

  return response ;
}

// Match against pages that require auth
export const config = { matcher : [ '/' , '/account/:path*' ] } ;

Cerrar sesión

Utilice el método signOut para cerrar la sesión del usuario que ha iniciado sesión actualmente y redirigirlo a la página de inicio de su aplicación. La redirección de la página de inicio se establece en la configuración del panel de WorkOS en "Redireccionar".

Visualizando una suplantación

Representa el componente Impersonation en tu aplicación para que quede claro cuando alguien se hace pasar por un usuario. El componente mostrará un marco con información sobre el usuario suplantado, así como un botón para dejar de suplantar.

 import { Impersonation } from '@workos-inc/authkit-nextjs' ;

export default function App ( ) {
  return (
    < div >
      < Impersonation / >
      { /* Your app content */ }
    < / div >
  ) ;
}

Obtener el token de acceso

A veces resulta útil obtener el token de acceso directamente, por ejemplo, para realizar solicitudes de API a otro servicio.

 import { withAuth } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  const { accessToken } = await withAuth ( ) ;

  if ( ! accessToken ) {
    return < div > Not signed in < / div > ;
  }

  const serviceData = await fetch ( '/api/path' , {
    headers : {
      Authorization : `Bearer ${ accessToken } ` ,
    } ,
  } ) ;

  return < div > { serviceData } < / div > ;
}

Actualizando la sesión

Utilice el método refreshSession en una acción del servidor o un controlador de ruta para obtener los detalles más recientes de la sesión, incluidos los cambios en las funciones o permisos del usuario.

El parámetro organizationId se puede pasar a refreshSession para cambiar la sesión a una organización diferente. Si la sesión actual no está autorizada para la siguiente organización, se devolverá un error de autenticación apropiado.

Regístrate rutas

La opción signUpPaths se puede pasar a authkitMiddleware para especificar rutas que deben usar la sugerencia en pantalla de "registro" al redirigir a AuthKit. Esto es útil para los casos en los que desea que una ruta que exige que la autenticación se trate como una página de registro.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;

Depuración

Para habilitar los registros de depuración, inicialice el middleware con el indicador de depuración habilitado.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( { debug : true } ) ;

Solución de problemas

Error NEXT_REDIRECT al usar bloques try/catch

Envolver una llamada withAuth({ ensureSignedIn: true }) en un bloque try/catch provocará un error NEXT_REDIRECT . Esto se debe a que withAuth intentará redirigir al usuario a AuthKit si no se detecta ninguna sesión y las redirecciones en Next deben llamarse fuera de try/catch.