authkit nextjs
v0.16.0
Next.js용 AuthKit 라이브러리는 Next.js와 함께 WorkOS 및 AuthKit을 사용하여 인증 및 세션 관리를 위한 편리한 도우미를 제공합니다.
참고: 이 라이브러리는 Next.js 앱 라우터와 함께 사용하기 위한 것입니다.
다음을 사용하여 패키지를 설치하십시오.
npm i @workos-inc/authkit-nextjs
또는
yarn add @workos-inc/authkit-nextjs
.env.local 환경 변수 파일에 다음 값이 있는지 확인하십시오. 클라이언트 ID와 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 는 세션 쿠키를 암호화하는 데 사용되는 개인 키입니다. 길이는 32자 이상이어야 합니다. 1Password 생성기 또는 openssl 라이브러리를 사용하여 명령줄을 통해 강력한 비밀번호를 생성할 수 있습니다.
openssl rand -base64 24
signOut 방법을 사용하려면 WorkOS 대시보드 설정의 '리디렉션'에서 앱 홈페이지를 설정해야 합니다.
특정 환경 변수는 선택 사항이며 쿠키 설정을 디버깅하거나 구성하는 데 사용할 수 있습니다.
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 변수 및 WorkOS 대시보드에 구성된 리디렉션 URI와 일치하는지 확인하세요. 예를 들어 리디렉션 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 미리보기 배포), authkitMiddleware 에서 redirectUri 옵션을 사용하세요.
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 Next.js 일치 프로그램과 동일한 glob 논리를 사용합니다.
사용자 정의 미들웨어를 구성하려는 경우 사용자 세션을 확인하는 것이 유용한 경우가 있습니다. getSession 도우미 메소드는 쿠키에서 세션을 검색하고 액세스 토큰을 확인합니다.
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 } ) ; try/catch 블록에서 withAuth({ ensureSignedIn: true }) 호출을 래핑하면 NEXT_REDIRECT 오류가 발생합니다. 이는 세션이 감지되지 않으면 withAuth 사용자를 AuthKit으로 리디렉션하려고 시도하고 Next의 리디렉션은 try/catch 외부에서 호출되어야 하기 때문입니다.
