시작하기
아래 예제 코드는 Next.js 앱에 인증을 추가하는 방법을 설명합니다.
새 프로젝트
시작하는 가장 쉬운 방법은 예제 앱을 클론하고 README.md의 지침을 따르는 것입니다. https://next-auth-example.vercel.app/에서 라이브 데모를 사용해 볼 수 있습니다.
기존 프로젝트
NextAuth 설치
- npm
- yarn
- pnpm
npm install next-auth
yarn add next-auth
pnpm add next-auth
TypeScript를 사용하는 경우, NextAuth.js는 패키지 내에 타입 정의를 포함하고 있습니다. next-auth의 TypeScript에 대해 더 알고 싶다면 TypeScript 문서를 확인하세요.
API 라우트 추가
프로젝트에 NextAuth.js를 추가하려면 pages/api/auth 디렉토리에 [...nextauth].js 파일을 생성하세요. 이 파일은 NextAuth.js의 동적 라우트 핸들러를 포함하며, 모든 전역 NextAuth.js 설정도 포함됩니다.
Next.js 13.2 이상과 새로운 App Router (app/)를 사용하는 경우, 새로운 라우트 핸들러를 사용하여 설정을 초기화할 수 있습니다. 가이드를 따르세요.
import NextAuth from "next-auth"
import GithubProvider from "next-auth/providers/github"
export const authOptions = {
// 하나 이상의 인증 제공자 구성
providers: [
GithubProvider({
clientId: process.env.GITHUB_ID,
clientSecret: process.env.GITHUB_SECRET,
}),
// ...여기에 더 많은 제공자를 추가하세요
],
}
export default NextAuth(authOptions)
/api/auth/*에 대한 모든 요청(signIn, callback, signOut 등)은 자동으로 NextAuth.js에 의해 처리됩니다.
추가 읽기 자료:
공유 세션 상태 구성
useSession을 사용하려면 먼저 애플리케이션 최상위에 세션 컨텍스트인 <SessionProvider />를 노출시켜야 합니다:
import { SessionProvider } from "next-auth/react"
export default function App({
Component,
pageProps: { session, ...pageProps },
}) {
return (
<SessionProvider session={session}>
<Component {...pageProps} />
</SessionProvider>
)
}
useSession의 인스턴스는 세션 데이터와 상태에 접근할 수 있습니다. <SessionProvider />는 또한 세션이 브라우저 탭과 창 간에 업데이트되고 동기화되도록 관리합니다.
클라이언트 문서를 확인하여 NextAuth.js 클라이언트를 사용하여 사용자 경험과 페이지 성능을 향상시키는 방법을 알아보세요. Next.js App Router를 사용하는 경우, <SessionProvider />는 클라이언트 컴포넌트를 필요로 하므로 루트 레이아웃 내에 배치할 수 없습니다. 자세한 내용은 Next.js 문서를 참고하세요.
프론트엔드 - React Hook 추가
NextAuth.js 클라이언트의 useSession() React Hook은 사용자가 로그인했는지 확인하는 가장 쉬운 방법입니다.
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
const { data: session } = useSession()
if (session) {
return (
<>
{session.user.email}으로 로그인됨 <br />
<button onClick={() => signOut()}>로그아웃</button>
</>
)
}
return (
<>
로그인하지 않음 <br />
<button onClick={() => signIn()}>로그인</button>
</>
)
}
애플리케이션의 어디에서나 useSession 훅을 사용할 수 있습니다 (예: 헤더 컴포넌트).
백엔드 - API 라우트
API 라우트를 보호하려면 getServerSession() 메서드를 사용할 수 있습니다.
import { getServerSession } from "next-auth/next"
import { authOptions } from "./auth/[...nextauth]"
export default async (req, res) => {
const session = await getServerSession(req, res, authOptions)
if (session) {
res.send({
content:
"이 콘텐츠는 보호되었습니다. 로그인했으므로 이 콘텐츠에 접근할 수 있습니다.",
})
} else {
res.send({
error: "이 페이지의 보호된 콘텐츠를 보려면 로그인해야 합니다.",
})
}
}
확장성
NextAuth.js 콜백 사용
NextAuth.js는 내장된 콜백을 통해 인증 흐름의 다양한 부분에 후킹할 수 있습 니다.
예를 들어, 로그인 시 프론트엔드 클라이언트로 값을 전달하려면 session 및 jwt 콜백을 조합하여 사용할 수 있습니다:
...
callbacks: {
async jwt({ token, account }) {
// 로그인 직후 OAuth access_token을 토큰에 유지
if (account) {
token.accessToken = account.access_token
}
return token
},
async session({ session, token, user }) {
// 공급자의 access_token과 같은 속성을 클라이언트로 보냄
session.accessToken = token.accessToken
return session
}
}
...
이제 getSession 또는 useSession을 호출할 때 반환되는 데이터 객체에 accessToken 값이 포함됩니다.
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
const { data } = useSession()
const { accessToken } = data
return <div>Access Token: {accessToken}</div>
}
콜백 URL 구성 (OAuth 전용)
OAuth 제공자를 사용하는 경우, 내장 제공자 중 하나를 통해서든 사용자 지정 제공자를 통해서든, 제공자의 설정에서 콜백 URL을 구성해야 합니다. 각 제공자는 이를 설정하는 방법에 대한 지침을 제공하는 "Configuration" 섹션을 가지고 있습니다.
OAuth 제공자와 통합하는 방법을 배우려면 이 단계를 따르세요.
프로덕션 배포
사이트를 배포할 때 NEXTAUTH_URL 환경 변수를 웹사이트의 정식 URL로 설정하세요.
NEXTAUTH_URL=https://example.com
자세한 내용은 배포 페이지를 확인하세요.