authkit nextjs
v0.16.0
Библиотека AuthKit для Next.js предоставляет удобные помощники для аутентификации и управления сеансами с помощью WorkOS и AuthKit с Next.js.
Примечание. Эта библиотека предназначена для использования с маршрутизатором приложений Next.js.
Установите пакет с помощью:
npm i @workos-inc/authkit-nextjs
или
yarn add @workos-inc/authkit-nextjs
Убедитесь, что в вашем файле переменных среды .env.local присутствуют следующие значения. Идентификатор клиента и ключ API можно найти на панели управления WorkOS, там же можно настроить URI перенаправления.
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 — это закрытый ключ, используемый для шифрования файла cookie сеанса. Оно должно быть не менее 32 символов. Вы можете использовать генератор 1Password или библиотеку openssl для создания надежного пароля через командную строку:
openssl rand -base64 24
Чтобы использовать метод signOut , вам необходимо настроить домашнюю страницу вашего приложения в настройках панели инструментов WorkOS в разделе «Перенаправления».
Некоторые переменные среды являются необязательными и могут использоваться для отладки или настройки параметров файлов cookie.
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 можно использовать для совместного использования сеансов WorkOS между приложениями/доменами. Примечание. WORKOS_COOKIE_PASSWORD должен быть одинаковым для всех приложений/доменов. Не требуется для большинства случаев использования.
WorkOS требует, чтобы у вас был URL-адрес обратного вызова, на который можно перенаправлять пользователей обратно после прохождения аутентификации. В вашем приложении Next.js откройте маршрут API и добавьте следующее.
import { handleAuth } from '@workos-inc/authkit-nextjs' ;
export const GET = handleAuth ( ) ; Убедитесь, что этот маршрут соответствует переменной WORKOS_REDIRECT_URI и настроенному URI перенаправления на панели управления WorkOS. Например, если ваш URI перенаправления — http://localhost:3000/auth/callback , вам следует поместить приведенный выше код в /app/auth/callback/route.ts .
Вы также можете контролировать путь, по которому пользователь будет отправлен после входа в систему, передав параметр returnPathname в handleAuth следующим образом:
export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ; handleAuth можно использовать с несколькими опциями.
| Вариант | По умолчанию | Описание |
|---|---|---|
returnPathname | / | Путь, на который будет перенаправлен пользователь после входа в систему. |
baseURL | undefined | Базовый URL-адрес, который будет использоваться для URI перенаправления вместо URL-адреса в запросе. Полезно, если приложение запускается в контейнере, таком как Docker, где имя хоста может отличаться от имени в запросе. |
Эта библиотека использует промежуточное программное обеспечение Next.js для обеспечения управления сеансами для маршрутов. Поместите следующее в файл middleware.ts в корне вашего проекта:
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' ] } ;Промежуточное программное обеспечение можно настроить с помощью нескольких опций.
| Вариант | По умолчанию | Описание |
|---|---|---|
redirectUri | undefined | Используется в тех случаях, когда вам нужно, чтобы URI перенаправления устанавливался динамически (например, при предварительном развертывании Vercel). |
middlewareAuth | undefined | Используется для настройки параметров аутентификации промежуточного программного обеспечения. Дополнительные сведения см. в разделе «Аутентификация промежуточного программного обеспечения». |
debug | false | Включает журналы отладки. |
signUpPaths | [] | Используется для указания путей, которые должны использовать подсказку на экране «регистрации» при перенаправлении на AuthKit. |
В тех случаях, когда вам нужно, чтобы URI перенаправления устанавливался динамически (например, при предварительном развертывании Vercel), используйте параметр redirectUri в 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' ] } ;Пользовательские URI перенаправления будут использоваться поверх URI перенаправления, настроенного в переменных среды.
AuthKitProvider Используйте AuthKitProvider для переноса макета приложения, что добавляет некоторую защиту в пограничных случаях аутентификации.
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 >
) ;
} Для страниц, на которых вы хотите отобразить представление входа и выхода из системы, используйте withAuth для получения профиля пользователя из 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 >
) ;
} Для страниц, где вход пользователя в систему обязателен, вы можете использовать опцию ensureSignedIn :
const { user } = await withAuth ( { ensureSignedIn : true } ) ; Включение ensureSignedIn перенаправит пользователей в AuthKit, если они попытаются получить доступ к странице без аутентификации.
По умолчанию эта библиотека запрашивает аутентификацию с помощью метода withAuth для каждой страницы. В некоторых случаях вы не хотите вызывать withAuth (например, вам не нужны пользовательские данные для вашей страницы) или если вы предпочитаете подход «безопасный по умолчанию», при котором каждый маршрут, определенный в вашем сопоставителе промежуточного программного обеспечения, защищен. если не указано иное. В этих случаях вы можете вместо этого использовать аутентификацию промежуточного программного обеспечения:
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' ] } ; В приведенном выше примере страница /admin потребует от пользователя входа в систему, тогда как доступ к / и /about можно получить без входа в систему.
unauthenticatedPaths использует ту же логику glob, что и средство сопоставления Next.js.
Иногда полезно проверить сеанс пользователя, если вы хотите создать собственное промежуточное программное обеспечение. Вспомогательный метод getSession извлечет сеанс из файла cookie и проверит токен доступа.
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*' ] } ; Используйте метод signOut , чтобы выйти из системы текущего вошедшего в систему пользователя и перенаправить его на домашнюю страницу вашего приложения. Перенаправление на домашнюю страницу задается в настройках панели управления WorkOS в разделе «Перенаправление».
Отобразите компонент Impersonation в своем приложении, чтобы было понятно, когда кто-то выдает себя за пользователя. Компонент отобразит фрейм с некоторой информацией о выдающем себя пользователе, а также кнопку прекращения выдачи себя за другое лицо.
import { Impersonation } from '@workos-inc/authkit-nextjs' ;
export default function App ( ) {
return (
< div >
< Impersonation / >
{ /* Your app content */ }
< / div >
) ;
}Иногда полезно получить токен доступа напрямую, например, чтобы сделать запросы API к другой службе.
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 > ;
} Используйте метод refreshSession в действии сервера или обработчике маршрута, чтобы получить последние сведения о сеансе, включая любые изменения в ролях или разрешениях пользователя.
Параметр organizationId можно передать в refreshSession , чтобы переключить сеанс на другую организацию. Если текущий сеанс не авторизован для следующей организации, будет возвращена соответствующая ошибка аутентификации.
Параметр signUpPaths можно передать в authkitMiddleware чтобы указать пути, которые должны использовать подсказку на экране «регистрация» при перенаправлении на AuthKit. Это полезно в тех случаях, когда вы хотите, чтобы путь, требующий аутентификации, рассматривался как страница регистрации.
import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;
export default authkitMiddleware ( {
signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;Чтобы включить журналы отладки, инициализируйте промежуточное программное обеспечение с включенным флагом отладки.
import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;
export default authkitMiddleware ( { debug : true } ) ; Обертывание вызова withAuth({ ensureSignedIn: true }) в блок try/catch приведет к ошибке NEXT_REDIRECT . Это связано с тем, что withAuth попытается перенаправить пользователя в AuthKit, если сеанс не обнаружен, а перенаправления в Next должны вызываться вне try/catch.
