アップグレードガイド (NextAuth.js v5)

設定ファイル

私たちの目標の1つは、設定を1つのファイルからエクスポートし、アプリケーション全体で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
})
 
// Optionally, don't invoke Middleware on some paths
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) {
    // Do something with the session
  }
 
  return { props: { session } }
}

アダプター

アダプターパッケージ

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 のサポートが廃止されたため、(以前はオプションだった) oauth_token_secret および oauth_token フィールドは、使用していない場合は account テーブルから削除できます。

さらに、以前は一般的ではなかった GitHub の refresh_token_expires_in フィールドのようなフィールドは、account テーブルに追加する必要がありました。これはもはや当てはまらず、使用していない場合は削除できます。使用する場合は、新しいaccount() コールバック経由で返すようにしてください。

Edge 互換性

Auth.js は厳密に標準のWeb APIを使用しているため（したがって、Web API をサポートするあらゆる環境で実行できます）、依存している一部のライブラリや ORM（オブジェクトリレーショナルマッピング）パッケージはまだ準備ができていない可能性があります。この場合、認証構成を複数のファイルに分割できます。

Auth.js は 2 つのセッション戦略をサポートしています。アダプターを使用している場合、デフォルトは 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 セッション戦略を追加します。これは、ミドルウェア以外でアプリケーションの残りの部分からインポートする auth.ts 構成ファイルです。

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"
 
// Use only one of the two middleware options below
// 1. Use middleware directly
// export const { auth: middleware } = NextAuth(authConfig)
 
// 2. Wrapped middleware option
const { auth } = NextAuth(authConfig)
export default auth(async function middleware(req: NextRequest) {
  // Your custom middleware logic goes here
})

上記は単なる例です。主な考え方は、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 型は、next-auth/adapters、@auth/sveltekit/adapters など、フレームワークパッケージの /adapters からも再エクスポートされます。