업그레이드 가이드 (NextAuth.js v5)

설정 파일

우리의 목표 중 하나는 설정을 한 파일에서 내보내고 이를 authOptions로 애플리케이션 전체에 전달하는 것을 피하는 것이었습니다. 이를 위해 설정 파일을 저장소의 루트로 옮기고, 필요한 함수들을 내보내어 다른 곳에서 사용할 수 있도록 했습니다. (auth, signIn, signOut, handlers 등).

설정 파일은 이전의 라우트 기반 Auth.js 설정과 매우 유사하게 보일 것입니다. 다만 이제는 저장소의 루트에 새로운 파일로 위치하며, 다른 곳에서 사용할 수 있는 메서드들을 내보내고 있습니다. 아래는 v5 설정 파일의 간단한 예제입니다.

import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
import Google from "next-auth/providers/google"
 
export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub, Google],
})

새로운 설정에 대해 주의할 점은 다음과 같습니다:

1. 이제 이 파일은 저장소의 루트에 auth.ts라는 이름으로 위치합니다. 기술적으로는 어떤 이름이든 가능하지만, 애플리케이션 전체에서 이 파일에서 내보낸 메서드들을 가져올 것이므로 짧은 이름을 유지하는 것을 권장합니다.
2. @auth/core를 설치하여 프로바이더 정의를 가져올 필요가 없습니다. 이제는 next-auth 자체에서 제공됩니다.
3. NextAuth() 함수에 전달되는 설정 객체는 이전과 동일합니다.
4. NextAuth() 함수 호출에서 반환된 메서드들은 새롭게 추가되었으며, 애플리케이션의 다른 부분에서 필요로 할 것입니다.

이전의 설정 파일은 API 라우트 (pages/api/auth/[...nextauth].ts / app/api/auth/[...nextauth]/route.ts)에 포함되어 있었지만, 이제는 훨씬 짧아졌습니다. 이 내보내기들은 App Router API 라우트에서 사용하도록 설계되었습니다. 하지만 점진적으로 마이그레이션 중이라면 나머지 애플리케이션은 Pages Router에 그대로 유지할 수 있습니다.

import { handlers } from "@/auth"
export const { GET, POST } = handlers

서버 사이드 인증

Auth.js는 과거에 서버 사이드 인증을 위해 여러 가지 방법을 제공했지만, 가능한 한 간단하게 만들기 위해 노력했습니다.

이제 Next.js 컴포넌트는 기본적으로 서버 우선이며, 표준 Web API를 사용하는 데 투자한 덕분에 대부분의 경우 인증 과정을 단일 auth() 함수 호출로 간소화할 수 있었습니다.

인증 방법

아래 표는 변경 사항을 요약한 내용입니다. 그 아래에는 다양한 환경과 컨텍스트에서 새로운 auth() 메서드를 사용하는 방법에 대한 diff 예제가 있습니다.

상세 설명

- import { authOptions } from "pages/api/auth/[...nextauth]"
- import { getServerSession } from "next-auth/next"
+ import { auth } from "@/auth"
 
export default async function Page() {
-  const session = await getServerSession(authOptions)
+  const session = await auth()
  return (<p>Welcome {session?.user.name}!</p>)
}

'use client';
 
import { useSession, SessionProvider } from 'next-auth/react';
 
const ClientComponent = () => {
  const session = useSession();
 
  return (
    <SessionProvider>
      <p>Welcome {session?.user?.name}</p>
    </SessionProvider>
  )
}

- export { default } from "next-auth/middleware"
+ export { auth as middleware } from "@/auth"

import { auth } from "@/auth"
 
export default auth((req) => {
  // req.auth
})
 
// 특정 경로에서는 미들웨어를 실행하지 않도록 설정
export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

- import { getServerSession } from "next-auth/next"
- import { getToken } from "next-auth/jwt"
- import { authOptions } from "pages/api/auth/[...nextauth]"
+ import { auth } from "@/auth"
+ import { NextApiRequest, NextApiResponse } from "next"
 
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  const session = await getServerSession(req, res, authOptions)
-  const token = await getToken({ req })
+  const session = await auth(req, res)
  if (session) return res.json("Success")
  return res.status(401).json("You must be logged in.");
}

- import { getServerSession } from "next-auth/next"
- import { getToken } from "next-auth/jwt"
- import { authOptions } from "pages/api/auth/[...nextauth]"
+ import { auth } from "@/auth"
 
export const getServerSideProps: GetServerSideProps = async (context) => {
-  const session = await getServerSession(context.req, context.res, authOptions)
-  const token = await getToken({ req: context.req })
+  const session = await auth(context)
  if (session) {
    // 세션을 사용하여 작업 수행
  }
 
  return { props: { session } }
}

Adapters

어댑터 패키지

next-auth v5부터는 데이터베이스 어댑터를 @next-auth/*-adapter 대신 @auth/*-adapter 스코프에서 설치해야 합니다. 데이터베이스 어댑터는 Next.js 기능에 의존하지 않기 때문에, 이 새로운 스코프로 이동하는 것이 더 적절했습니다.

- npm install @next-auth/prisma-adapter
+ npm install @auth/prisma-adapter

데이터베이스 마이그레이션

NextAuth.js v5는 데이터베이스 스키마에 대한 호환성 문제를 일으키지 않습니다. 하지만 OAuth 1.0 지원이 중단되었기 때문에, 사용하지 않는 경우 account 테이블에서 (이전에는 선택 사항이었던) oauth_token_secret과 oauth_token 필드를 제거할 수 있습니다.

또한, 이전에는 GitHub의 refresh_token_expires_in과 같은 드물게 사용되던 필드들이 account 테이블에 추가되어야 했습니다. 이제는 더 이상 그럴 필요가 없으며, 사용하지 않는다면 해당 필드를 제거해도 됩니다. 만약 이 필드를 사용한다면, 새로운 account() 콜백을 통해 반환하도록 해야 합니다.

Edge 호환성

Auth.js는 표준 Web API를 엄격하게 사용하므로(따라서 이를 지원하는 모든 환경에서 실행 가능), 여러분이 의존하는 일부 라이브러리나 ORM(Object-Relational Mapping) 패키지가 아직 준비되지 않았을 수 있습니다. 이 경우, 인증 설정을 여러 파일로 나눌 수 있습니다.

Auth.js는 두 가지 세션 전략을 지원합니다. 어댑터를 사용할 때는 기본적으로 database 전략을 사용합니다. 여러분의 데이터베이스와 그 어댑터가 Edge 런타임/인프라와 호환되지 않는 한, "database" 세션 전략을 사용할 수 없습니다.

예를 들어, 아직 Edge 런타임과 호환되지 않는 ORM/라이브러리에 의존하는 어댑터를 사용하는 경우, 아래 예제처럼 jwt 전략을 강제로 사용하고 설정을 분리하여 라이브러리가 미들웨어와 같은 Edge 환경에서 데이터베이스에 접근하지 않도록 할 수 있습니다.

1. auth.config.ts 파일을 생성하고, Auth.js 설정 옵션을 포함하는 객체를 내보냅니다. 여기서는 어댑터에 의존하지 않는 모든 공통 설정을 넣을 수 있습니다. 이 파일은 설정 객체만 내보내며, 여기서는 NextAuth()를 호출하지 않습니다.

import GitHub from "next-auth/providers/github"
import type { NextAuthConfig } from "next-auth"
 
export default { providers: [GitHub] } satisfies NextAuthConfig

2. 다음으로, auth.ts 파일을 생성하고 어댑터와 jwt 세션 전략을 추가합니다. 이 파일은 미들웨어를 제외한 애플리케이션의 나머지 부분에서 가져올 설정 파일입니다.

import NextAuth from "next-auth"
import { PrismaAdapter } from "@auth/prisma-adapter"
import { PrismaClient } from "@prisma/client"
import authConfig from "./auth.config"
 
const prisma = new PrismaClient()
 
export const { auth, handlers, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: "jwt" },
  ...authConfig,
})

3. 미들웨어 파일에서 첫 번째 auth.config.ts 파일에서 설정 객체를 가져와서 Auth.js를 지연 초기화합니다. 효과적으로, 공통 옵션만으로 Auth.js를 별도로 초기화하되, Edge와 호환되지 않는 어댑터는 제외합니다.

import authConfig from "./auth.config"
import NextAuth from "next-auth"
 
// 아래 두 가지 미들웨어 옵션 중 하나만 사용하세요
// 1. 미들웨어를 직접 사용
// export const { auth: middleware } = NextAuth(authConfig)
 
// 2. 래핑된 미들웨어 옵션
const { auth } = NextAuth(authConfig)
export default auth(async function middleware(req: NextRequest) {
  // 여기에 커스텀 미들웨어 로직을 추가하세요
})

위 예제는 단지 예시일 뿐입니다. 핵심 아이디어는 Edge와 호환되는 설정 부분을 나머지 부분과 분리하고, 미들웨어/Edge 페이지/라우트에서 Edge와 호환되는 부분만 가져오는 것입니다. 이 해결 방법에 대해 더 자세히 알고 싶다면, 예를 들어 Prisma 문서를 참고하세요.

여러분이 사용하는 라이브러리/데이터베이스/ORM의 관리자에게 Edge 런타임/인프라 지원 계획이 있는지 확인해 보세요.

Edge 호환성과 Auth.js가 어떻게 맞물리는지에 대한 일반적인 정보는 Edge 호환성 문서를 참고하세요.

환경 변수

환경 변수에 대한 호환성 문제는 없지만, 몇 가지 사항을 정리하면서 일부 환경 변수가 더 이상 필요하지 않게 되었습니다. 따라서 환경 변수와 관련된 몇 가지 모범 사례를 공유하고자 합니다.

• 모든 환경 변수는 AUTH_로 시작해야 합니다. NEXTAUTH_는 더 이상 사용되지 않습니다.
• 프로바이더의 secret / clientId 변수를 AUTH_GITHUB_SECRET 및 AUTH_GITHUB_ID와 같은 구문으로 명명하면 자동으로 감지되며, 프로바이더 설정에 명시적으로 전달할 필요가 없습니다.
• 대부분의 환경에서 NEXTAUTH_URL/AUTH_URL은 더 이상 필수적이지 않습니다. 요청 헤더를 기반으로 호스트를 자동으로 감지합니다.
• AUTH_TRUST_HOST 환경 변수는 Auth.js 설정에서 trustHost: true를 설정하는 것과 동일한 목적을 가집니다. 이는 프록시 뒤에서 Auth.js를 실행할 때 필요합니다. 이 값을 true로 설정하면 프록시가 앱에 전달한 X-Forwarded-Host 및 X-Forwarded-Proto 헤더를 신뢰하여 호스트 URL(AUTH_URL)을 자동으로 감지합니다.
• AUTH_SECRET 환경 변수는 유일하게 필수적인 변수입니다. 환경 변수를 설정했다면, secret 설정 옵션으로 이 값을 추가로 전달할 필요가 없습니다.

환경 변수와 환경 변수 추론에 대한 자세한 내용은 환경 변수 페이지를 참고하세요.

TypeScript

• NextAuthOptions가 NextAuthConfig로 이름이 변경되었습니다.
• 다음과 같은 타입들이 이제 next-auth와 @auth/sveltekit 같은 모든 프레임워크 패키지에서 내보내집니다:

export type {
  Account,
  DefaultSession,
  Profile,
  Session,
  User,
} from "@auth/core/types"

• 모든 Adapter 타입들도 프레임워크 패키지의 /adapters에서 다시 내보내집니다. 예를 들어 next-auth/adapters, @auth/sveltekit/adapters 등에서 사용할 수 있습니다.