Next.js应用中使用NextAuth.js进行用户认证管理详解

照片由 Tyler Franta 拍摄，来自 Unsplash

身份验证在 web 应用中扮演着关键角色，保护用户数据和访问权限。在 Next.js 中，有效的身份验证管理需要在服务器端和客户端处理之间采取 平衡的方法。在 Next.js 生态系统中，有一个广为采用的解决方案是 NextAuth.js。本文将深入探讨在 Next.js 应用程序中处理身份验证的细节，并通过一个使用 NextAuth.js 的实际案例来解释。

在 Next.js 应用程序中管理身份验证：一个详细的指南 身份验证是许多 web 应用程序中的一个重要组成部分，确保用户能够安全地访问他们的数据和相关信息。……tidewave.net

不为什么使用NextAuth.js进行身份验证？

注：此处翻译可能需要根据上下文调整为更合适的表达，如“为什么选择NextAuth.js进行身份验证？”或其他更符合原文意图的表述。根据专家建议，更合适的翻译为：

为什么使用NextAuth.js进行身份验证？

或更口语化的表达为：

为什么选用NextAuth.js来做身份验证？

NextAuth.js 通过提供对各种提供商（包括 OAuth、电子邮件和自定义选项等）的原生支持，简化了 Next.js 应用中的身份验证过程。它确保安全的会话管理，与数据库集成顺畅，并包含了高级功能，包括 JWT 处理和防止常见安全漏洞。其简单的特性、灵活性和广泛自定义能力的结合，使其成为在现代 web 应用程序中构建可扩展且安全的身份验证系统的绝佳选择。

NextAuth.js 的主要特点

NextAuth.js 是一个强大的认证库，专为 Next.js 应用程序设计，提供了一系列功能，旨在简化并增强您应用的认证添加过程。以下是 NextAuth.js 的一些关键功能：

1. 支持的提供商 ：NextAuth.js 支持多种认证提供商，例如 OAuth （Google，Facebook，GitHub），邮箱和密码，以及 自定义的身份提供者。

2. 安全会话管理： 它安全地管理用户的会话，支持JWT（JSON Web Tokens）和数据库会话，以保持用户状态在不同请求间一致。

3. 可自定义的身份验证流程： 开发者可以自定义登录页面、登出页面和账户管理页面。

4. 数据库集成： 它能够与数据库集成，存储和管理用户账户、会话等数据，支持多种数据库，如MongoDB、PostgreSQL和MySQL。

5. 内置安全： NextAuth.js** 包括了防范常见安全风险的功能，例如 CSRF 保护、会话过期，和 加密的令牌**。

6. 回调和事件： 开发者可以在认证事件和回调函数中挂钩，执行自定义操作，如修改用户数据或记录事件。

1. 自动刷新令牌功能: 该库会自动处理令牌的刷新，确保用户无需手动干预即可保持认证状态。

8. 简单的设置与配置 ： 它提供了一个简单的设置流程和通过一个next-auth.config.js 文件提供的配置选项。

9. 多个会话功能： 用户可以同时处理多个会话，这在用户可能从不同设备或浏览器登录的应用程序中特别有用。

10. 灵活的UI定制： 提供了定制认证相关UI组件外观和行为的选项。

11. API 路由集成： 与 Next.js API 路由 无缝对接，灵活地与后端服务进行集成。

12. Next.js 中间件集成，集成 Next.js中间件，对特定路由进行 认证保护 等高级用例。

13. 国际化的支持： 提供构建支持多种语言及地区设置的认证过程的工具。

14. JWT 和会话管理： 支持 JSON Web Tokens 和 服务器端会话，为开发人员提供了灵活性来管理用户认证。

15. 社交登录的整合： 让社交登录和基于 OAuth 的身份验证过程变得更简单。

16. 邮箱验证： 包括内置的邮箱验证和密码重置工作流程支持，提升安全性和用户体验。

17. 开发者友好的文档 : 提供了详尽的文档和技术示例，帮助开发者快速入门并自定义身份验证流程。

18. 可扩展性： 设计用于处理大规模应用程序中的认证，在支持大量用户和复杂的认证需求方面具备功能。

19. 可扩展性 ： 支持轻松地扩展和修改，使开发人员能够根据其特定需求和应用场景对库进行调整。

20. 活跃的社区与贡献者们维护: 由活跃的社区和贡献者们维护，提供定期更新，支持新功能及改进。

这些功能一起使NextAuth.js成为一个处理Next.js应用中登录验证的强大解决方案。（NextAuth.js）

NextAuth.js 的使用示例

如何在Next.js应用程序中配置NextAuth.js，如下是一个基本示例：

    // pages/api/auth/[...nextauth].js  
    import NextAuth from "next-auth";  
    import Providers from "next-auth/providers";  

    export default NextAuth({  
      providers: [  
        Providers.Google({  
          clientId: process.env.GOOGLE_CLIENT_ID,  
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,  
        }),  
        Providers.GitHub({  
          clientId: process.env.GITHUB_CLIENT_ID,  
          clientSecret: process.env.GITHUB_CLIENT_SECRET,  
        }),  
        // 可以在此添加更多提供商  
      ],  
      callbacks: {  
        async session(session, user) {  
          session.user.id = user.id;  
          return session;  
        },  
        async jwt(token, user) {  
          if (user) {  
            token.id = user.id;  
          }  
          return token;  
        },  
      },  
      database: process.env.DATABASE_URL, // 可选：用于持久化会话  
    });

此示例展示了如何将Google和GitHub设置为身份验证提供商，并自定义会话和JWT回调设置，同时可选择连接到数据库以保存会话。

在 Next.js 项目中使用 NextAuth.js 设置认证

在使用 Next.js 和 NextAuth.js 设置用户身份验证时，需要遵循几个关键步骤以确保安全且无缝的用户体验。NextAuth.js 是一个强大且灵活的用户身份验证库，简化了集成各种身份验证提供者的过程，并管理会话，以保护应用程序的安全。

安装相关依赖项

首先，你需要安装NextAuth.js以及任何必要的提供者。你可以使用npm或yarn来完成这一步。

    npm install next-auth

或者，

在终端中运行以下命令来安装next-auth:
yarn add next-auth

创建用于认证的API路由

创建一个文件用于你的认证 API 路径，位于 **pages/api/auth/[...nextauth].js**。在这里配置 NextAuth.js 及其提供程序。

    // pages/api/auth/[...nextauth].js  
    import NextAuth from "next-auth";  
    import GoogleProvider from "next-auth/providers/google";  
    import EmailProvider from "next-auth/providers/email";  
    import { PrismaAdapter } from "@next-auth/prisma-adapter";  
    import { PrismaClient } from "@prisma/client";  

    // 初始化 Prisma 客户端  
    const prisma = new PrismaClient();  

    export default NextAuth({  
      // 配置身份验证提供程序  
      providers: [  
        GoogleProvider({  
          clientId: process.env.GOOGLE_CLIENT_ID,  
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,  
        }),  
        EmailProvider({  
          server: process.env.EMAIL_SERVER,  
          from: process.env.EMAIL_FROM,  
        }),  
        // 根据需要添加更多提供程序  
      ],  
      adapter: PrismaAdapter(prisma), // 可选：使用数据库适配器  
      secret: process.env.NEXTAUTH_SECRET, // 可选：用于加密  
      pages: {  
        signIn: '/auth/signin',  // 自定义登录页面  
        signOut: '/auth/signout', // 自定义注销页面  
        error: '/auth/error',     // 自定义错误页面  
        verifyRequest: '/auth/verify-request', // (用于验证请求的电子邮件)  
        newAccount: '/auth/new-account',  // (用于新账户创建)  
      },  
      callbacks: {  
        async session({ session, user }) {  
          // 添加自定义逻辑来修改会话对象  
          session.user.id = user.id;  
          return session;  
        },  
      },  
    });

设置环境变量

添加您的身份验证提供者的凭证以及其他任何密钥到您的环境变量中。在项目根目录下创建一个.env.local文件，并添加如下所示的内容：

GOOGLE_CLIENT_ID=你的谷歌客户端ID  
GOOGLE_CLIENT_SECRET=你的谷歌客户端密钥值  
EMAIL_SERVER=smtp://用户名:密码@smtp.example.com:587  
EMAIL_FROM=你的邮箱地址@example.com  
NEXTAUTH_SECRET=你的nextauth密钥值

自定义登录页面

如有愿意，可以创建自定义的登录页面。在 **pages/auth/signin.js** 添加文件：

    // pages/auth/signin.js  
    import { getProviders, signIn } from "next-auth/react";  

    export default function SignIn({ providers }) {  
      return (  
        <div>  
          <h1>账号登录</h1>  
          {Object.values(providers).map((provider) => (  
            <div key={provider.name}>  
              <button onClick={() => signIn(provider.id)}>  
                {provider.name} 登录  
              </button>  
            </div>  
          ))}  
        </div>  
      );  
    }  

    export async function getServerSideProps() {  
      const providers = await getProviders();  
      return {  
        props: { providers },  
      };  
    }

保护页面或API路径

使用NextAuth.js的钩子来保护您的页面或API端点。例如，保护一个页面可以这样：

/pages/protected.js
import { getSession } from "next-auth/react";

export default function ProtectedPage() {
  return <div>保护页面</div>;
}

export async function getServerSideProps(context) {
  const session = await getSession(context);
  if (!session) {
    // 未登录则跳转到登录页面
    return {
      redirect: {
        destination: '/auth/signin',
        permanent: false,
      },
    };
  }
  return {
    props: { session },
  };
}

添加登录和退出的链接

您可以使用 **next-auth/react** 來進行組件中的身份驗證相關的操作。例如，可以添加登錄和登出的功能。

    // components/Navbar.js  
    import { signIn, signOut, useSession } from "next-auth/react";  

    export default function Navbar() {  
      const { data: session } = useSession();  

      return (  
        <nav>  
          {session ? (  
            <>  
              <span>你好，{session.user.name}</span>  
              <button onClick={() => signOut()}>退出</button>  
            </>  
          ) : (  
            <button onClick={() => signIn()}>登录</button>  
          )}  
        </nav>  
      );  
    }

来测试一下您的设置吧

运行你的 Next.js 应用：

    npm run dev

进入 你的登录页面并测试 登录过程。

此示例使用**[NextAuth.js](https://next-auth.js.org/) 设置了一个基本的身份验证体系，使用 Google 和 邮箱登录**。你可以根据你的应用需求自定义和扩展它。

使用NextAuth.js进行Next.js登录的小贴士

在 Next.js 项目中使用 NextAuth.js 实现身份验证时，可以更有效地做到以下一些实用的小建议：

确保您的API路径安全

确保敏感的 API 端点通过验证用户是否已认证来保护。使用 [**getSession**](https://next-auth.js.org/v3/tutorials/securing-pages-and-api-routes#using-getsession) 或 [**getServerSession**](https://next-auth.js.org/configuration/nextjs#getserversession) 来验证会话的有效性。

    // pages/api/secure-data.js
    import { getSession } from "next-auth/react";

    export default async function handler(req, res) {
      const session = await getSession({ req });
      if (session) {
        // 用户已登录
        res.status(200).json({ data: "这是安全数据。" });
      } else {
        // 用户未登录
        res.status(401).json({ error: "未授权。" });
      }
    }

自定义身份验证页面

根据您的应用程序设计，自定义默认的登录页面和错误页面。

下面是一个自定义登录页面的例子：

// pages/auth/signin.js  
import { getProviders, signIn } from "next-auth/react";  

export default function SignIn({ providers }) {  
  return (  
    <div>  
      <h1>登录</h1>  
      {Object.values(providers).map((provider) => (  
        <div key={provider.name}>  
          <button onClick={() => signIn(provider.id)}>  
            用 {provider.name} 登录  
          </button>  
        </div>  
      ))}  
    </div>  
  );  
}  

export async function getServerSideProps() {  
  const providers = await getProviders();  
  return {  
    props: { providers },  
  };  
}

自定义错误页面的例子

    // pages/auth/error.js
    export default function Error() {
      return (
        <div>
          <h1>认证错误</h1>
          <p>认证过程中出现了问题，请尝试重新登录。</p>
        </div>
      );
    }

用回调来实现自定义逻辑

通过回调来自定义NextAuth.js的行为。给会话对象添加自定义属性。

    // pages/api/auth/[...nextauth].js  
    import NextAuth from "next-auth";  
    import GoogleProvider from "next-auth/providers/google";  

    export default NextAuth({  
      providers: [  
        GoogleProvider({  
          clientId: process.env.GOOGLE_CLIENT_ID,  
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,  
        }),  
      ],  
      callbacks: {  
        async session({ session, token }) {  
          // 在会话对象中添加自定义的用户ID  
          session.user.id = token.id;  
          return session;  
        },  
        async jwt({ token, user }) {  
          如果有用户数据，{  
            token.id = user.id;  
          }  
          return token;  
        },  
      },  
    });

实现基于角色的访问权限控制

通过session对象根据用户角色控制访问，以限制对某些页面的访问。

    // pages/admin.js
    import { getSession } from "next-auth/react";

    export default function AdminPage() {
      return <div>管理员页面内容</div>;
    }

    export async function getServerSideProps(context) {
      const session = await getSession(context);
      if (!session || session.user.会话用户角色 !== "admin") {
        // 未授权时，重定向至登录页面或错误提示页面
        return {
          redirect: {
            destination: '/auth/signin',
            permanent: false,
          },
        };
      }
      return {
        props: { session },
      };
    }

用户注册和资料更新管理

扩展 NextAuth.js 来处理用户注册或更新的需求，如有必要。你可以根据需要使用自定义逻辑来管理用户数据。

比如Prisma这样的例子：

    // pages/api/auth/[...nextauth].js  
    import NextAuth from "next-auth";  
    import { PrismaAdapter } from "@next-auth/prisma-adapter";  
    import { PrismaClient } from "@prisma/client";  

    const prisma = new PrismaClient();  

    export default NextAuth({  
      providers: [  
        // 您要使用的提供者  
      ],  
      adapter: PrismaAdapter(prisma),  
      callbacks: {  
        async signIn({ user }) {  
          // 处理用户登录的自定义逻辑  
          return true; // 或 false 来拒绝访问  
        },  
        async session({ session, user }) {  
          // 自定义会话处理  
          return session;  
        },  
      },  
    });

用 (JSON Web Token, JWT) 优化身份验证

使用JWT进行无状态的认证，在你不需要在服务器上存储会话的情况下。

    // pages/api/auth/[...nextauth].js
    import NextAuth from "next-auth";
    import GoogleProvider from "next-auth/providers/google";

    export default NextAuth({
      providers: [
        GoogleProvider({
          clientId: process.env.GOOGLE_CLIENT_ID,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
        }),
      ],
      session: {
        strategy: "jwt", // 使用 JWT 进行会话管理
      },
      callbacks: {
        async jwt({ token, user }) {
          // 如果有用户信息
          if (user) {
            token.id = user.id;
          }
          return token;
        },
        async session({ session, token }) {
          // 将 token 中的 id 赋值给会话中的用户 id
          session.user.id = token.id;
          return session;
        },
      },
    });

安全注销实现

确保签出过程安全结束会话。

    // pages/api/auth/signout.js
    import { signOut } from "next-auth/react";

    export default function SignOutPage() {
      signOut({ callbackUrl: '/' });
      return <div>正在退出登录...</div>;
    }

保护好网站页面

使用 [useSession](https://next-auth.js.org/getting-started/client#usesession) 钩子根据用户的登录状态来显示内容。

    // pages/仪表盘页面
    import { useSession, signIn } from "next-auth/react";

    export default function Dashboard() {
      const { data: session, status } = useSession();

      if (status === "loading") {
        return <div>正在加载...</div>;
      }

      if (!session) {
        signIn(); // 重定向至登录页面
        return <div>正在重定向...</div>;
      }

      return <div>欢迎，{session.user.name}</div>;
    }

利用中间件来保护路由

从 Next.js 13 开始，使用 中间件 根据认证状态保护路由的安全性。

    // middleware.ts
    import { NextResponse } from "next/server";
    import { getToken } from "next-auth/jwt";

    export async function 中间件(req) {
      const token = await getToken({ req, secret: process.env.NEXTAUTH_SECRET });

      // 如果没有 token 并且请求路径以 "/protected" 开头，则重定向到登录页面
      if (!token && req.nextUrl.pathname.startsWith("/protected")) {
        return NextResponse.redirect(new URL("/auth/signin", req.url));
      }

      // 返回下一个响应
      return NextResponse.next();
    }

彻底测试认证

确保你彻底测试所有认证流程，包括特殊情况，如过期会话、无效凭证和基于角色的访问权限。

通过遵循这些提示并参考提供的代码示例，您可以在您的 Next.js 项目中轻松地使用 NextAuth.js 设置强大的身份验证功能。

结束语

在Next.js应用中管理认证，使用NextAuth.js非常简单。这个强大的库提供了一系列的功能和定制选项，使集成各种认证提供方、安全地管理会话以及保护页面及[API路由]变得容易。通过遵循本文中概述的步骤，您可以在您的Next.js应用中建立一个强大的认证系统，提升安全性和用户体验。

了解如何在 Next.js 应用程序中管理身份验证，可以参考这篇文章 https://tidewave.net/blog/managing-authentication-in-a-next.js-application