authkit nextjs

Bibliothèque AuthKit Next.js

La bibliothèque AuthKit pour Next.js fournit des aides pratiques pour l'authentification et la gestion de session à l'aide de WorkOS et AuthKit avec Next.js.

Remarque : Cette bibliothèque est destinée à être utilisée avec le routeur d'application Next.js.

Installation

Installez le package avec :

 npm i @workos-inc/authkit-nextjs

ou

 yarn add @workos-inc/authkit-nextjs

Tutoriel vidéo

Avant le vol

Assurez-vous que les valeurs suivantes sont présentes dans votre fichier de variables d'environnement .env.local . L'ID client et la clé API se trouvent dans le tableau de bord WorkOS, et l'URI de redirection peut également y être configuré.

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 est la clé privée utilisée pour chiffrer le cookie de session. Il doit comporter au moins 32 caractères. Vous pouvez utiliser le générateur 1Password ou la bibliothèque openssl pour générer un mot de passe fort via la ligne de commande :

 openssl rand -base64 24

Pour utiliser la méthode signOut , vous devrez définir la page d'accueil de votre application dans les paramètres de votre tableau de bord WorkOS sous « Redirections ».

Configuration facultative

Certaines variables d'environnement sont facultatives et peuvent être utilisées pour déboguer ou configurer les paramètres des 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 peut être utilisé pour partager des sessions WorkOS entre applications/domaines. Remarque : Le WORKOS_COOKIE_PASSWORD doit être le même dans toutes les applications/domaines. Non nécessaire dans la plupart des cas d'utilisation.

Installation

Itinéraire de rappel

WorkOS nécessite que vous disposiez d'une URL de rappel vers laquelle rediriger les utilisateurs une fois qu'ils se sont authentifiés. Dans votre application Next.js, exposez une route API et ajoutez ce qui suit.

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

export const GET = handleAuth ( ) ;

Assurez-vous que cet itinéraire correspond à la variable WORKOS_REDIRECT_URI et à l'URI de redirection configuré dans votre tableau de bord WorkOS. Par exemple, si votre URI de redirection est http://localhost:3000/auth/callback , vous devez alors mettre le code ci-dessus dans /app/auth/callback/route.ts .

Vous pouvez également contrôler le chemin vers lequel l'utilisateur sera envoyé après la connexion en passant une option returnPathname à handleAuth comme ceci :

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

handleAuth peut être utilisé avec plusieurs options.

Option	Défaut	Description
returnPathname	/	Le chemin vers lequel rediriger l'utilisateur après la connexion
baseURL	undefined	L'URL de base à utiliser pour l'URI de redirection au lieu de celle de la demande. Utile si l'application est exécutée dans un conteneur tel que Docker où le nom d'hôte peut être différent de celui de la requête

Intergiciel

Cette bibliothèque s'appuie sur le middleware Next.js pour assurer la gestion des sessions des routes. Mettez ce qui suit dans votre fichier middleware.ts à la racine de votre projet :

 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' ] } ;

Le middleware peut être configuré avec plusieurs options.

Option	Défaut	Description
redirectUri	undefined	Utilisé dans les cas où vous avez besoin que votre URI de redirection soit défini dynamiquement (par exemple, les déploiements de prévisualisation de Vercel)
middlewareAuth	undefined	Utilisé pour configurer les options d'authentification du middleware. Voir l'authentification middleware pour plus de détails.
debug	false	Active les journaux de débogage.
signUpPaths	[]	Utilisé pour spécifier les chemins qui doivent utiliser l'indice d'écran « inscription » lors de la redirection vers AuthKit.

URI de redirection personnalisé

Dans les cas où vous avez besoin que votre URI de redirection soit défini de manière dynamique (par exemple, les déploiements de prévisualisation Vercel), utilisez l'option redirectUri dans 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' ] } ;

Les URI de redirection personnalisés seront utilisés sur un URI de redirection configuré dans les variables d'environnement.

Usage

Enveloppez votre application dans AuthKitProvider

Utilisez AuthKitProvider pour envelopper la présentation de votre application, ce qui ajoute des protections pour les cas extrêmes d'authentification.

 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 >
  ) ;
}

Obtenir l'utilisateur actuel

Pour les pages sur lesquelles vous souhaitez afficher une vue de connexion et de déconnexion, utilisez withAuth pour récupérer le profil utilisateur 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 >
  ) ;
}

Exiger une authentification

Pour les pages pour lesquelles un utilisateur connecté est obligatoire, vous pouvez utiliser l'option ensureSignedIn :

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

L'activation de ensureSignedIn redirigera les utilisateurs vers AuthKit s'ils tentent d'accéder à la page sans être authentifiés.

Authentification middleware

Le comportement par défaut de cette bibliothèque est de demander l'authentification via la méthode withAuth page par page. Il existe certains cas d'utilisation dans lesquels vous ne souhaitez pas appeler withAuth (par exemple, vous n'avez pas besoin de données utilisateur pour votre page) ou si vous préférez une approche "sécurisée par défaut" dans laquelle chaque route définie dans votre middleware matcher est protégée. sauf indication contraire. Dans ces cas-là, vous pouvez choisir d'utiliser l'authentification middleware à la place :

 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' ] } ;

Dans l'exemple ci-dessus, la page /admin nécessitera qu'un utilisateur soit connecté, tandis que / et /about seront accessibles sans se connecter.

unauthenticatedPaths utilise la même logique globale que le matcher Next.js.

Récupérer la session dans le middleware

Parfois, il est utile de vérifier la session utilisateur si vous souhaitez composer un middleware personnalisé. La méthode d'assistance getSession récupérera la session à partir du cookie et vérifiera le jeton d'accès.

 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*' ] } ;

Déconnexion

Utilisez la méthode signOut pour déconnecter l’utilisateur actuellement connecté et rediriger vers la page d’accueil de votre application. La redirection de la page d'accueil est définie dans les paramètres de votre tableau de bord WorkOS sous « Redirection ».

Visualiser une imitation

Restituez le composant Impersonation dans votre application afin qu'il soit clair quand quelqu'un usurpe l'identité d'un utilisateur. Le composant affichera un cadre avec des informations sur l'utilisateur usurpé, ainsi qu'un bouton pour arrêter l'usurpation d'identité.

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

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

Obtenez le jeton d'accès

Parfois, il est utile d'obtenir le jeton d'accès directement, par exemple pour effectuer des requêtes API vers un autre service.

 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 > ;
}

Actualisation de la session

Utilisez la méthode refreshSession dans une action de serveur ou un gestionnaire de route pour récupérer les derniers détails de la session, y compris toute modification apportée aux rôles ou aux autorisations de l'utilisateur.

Le paramètre organizationId peut être transmis refreshSession afin de basculer la session vers une autre organisation. Si la session en cours n'est pas autorisée pour l'organisation suivante, une erreur d'authentification appropriée sera renvoyée.

Parcours d'inscription

L'option signUpPaths peut être transmise à authkitMiddleware pour spécifier les chemins qui doivent utiliser l'indice d'écran « inscription » lors de la redirection vers AuthKit. Ceci est utile dans les cas où vous souhaitez qu'un chemin exigeant l'authentification soit traité comme une page d'inscription.

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

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

Débogage

Pour activer les journaux de débogage, initialisez le middleware avec l'indicateur de débogage activé.

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

export default authkitMiddleware ( { debug : true } ) ;

Dépannage

Erreur NEXT_REDIRECT lors de l'utilisation de blocs try/catch

Encapsuler un appel withAuth({ ensureSignedIn: true }) dans un bloc try/catch provoquera une erreur NEXT_REDIRECT . En effet, withAuth tentera de rediriger l'utilisateur vers AuthKit si aucune session n'est détectée et les redirections dans Next doivent être appelées en dehors d'un try/catch.