NextAuth.js 中使用自定义 JWT 令牌的完整指南

背景介绍

NextAuth.js 是一个流行的 Next.js 身份验证库，它提供了多种身份验证策略和提供程序。在实际开发中，很多开发者会遇到需要集成已有后端认证系统的情况，特别是当后端已经实现了 JWT 认证机制时。本文将详细介绍如何在 NextAuth.js 中无缝集成自定义的 JWT 令牌系统。

核心挑战

NextAuth.js 默认会生成自己的 JWT 令牌用于会话管理，这与许多已有后端系统的工作方式存在冲突。主要面临以下几个技术难点：

1. 如何保留后端生成的 JWT 令牌
2. 如何实现令牌自动刷新机制
3. 如何正确处理令牌过期情况
4. 如何扩展 NextAuth.js 的类型定义

解决方案架构

类型定义扩展

首先需要扩展 NextAuth.js 的类型系统，以支持自定义的令牌结构。在项目根目录创建 next-auth.d.ts 文件：

declare module "next-auth" {
  interface BackendAccessJWT {
    access: string;
    refresh?: string;
  }

  interface UserObject {
    id: number;
    email: string;
    name: string;
  }

  interface DecodedJWT extends UserObject {
    token_type: "refresh" | "access";
    exp: number;
    iat: number;
    jti: string;
  }

  interface AuthValidity {
    valid_until: number;
    refresh_until: number;
  }

  interface User {
    tokens: BackendAccessJWT;
    user: UserObject;
    validity: AuthValidity;
  }

  interface Session {
    user: UserObject;
    validity: AuthValidity;
    error?: "RefreshTokenExpired" | "RefreshAccessTokenError";
  }
}

declare module "next-auth/jwt" {
  interface JWT {
    data: User;
    error?: "RefreshTokenExpired" | "RefreshAccessTokenError";
  }
}

认证流程实现

在 Credentials 提供者中实现自定义认证逻辑：

const authOptions: AuthOptions = {
  providers: [
    CredentialsProvider({
      async authorize(credentials) {
        try {
          // 调用后端API获取令牌
          const res = await login(credentials?.email, credentials?.password);
          const tokens = await res.json();
          
          // 解码令牌获取用户信息
          const access = jwtDecode(tokens.access);
          const refresh = jwtDecode(tokens.refresh);
          
          return {
            id: refresh.jti,
            tokens,
            user: {
              id: access.id,
              email: access.email,
              name: access.name
            },
            validity: {
              valid_until: access.exp,
              refresh_until: refresh.exp
            }
          };
        } catch (error) {
          return null;
        }
      }
    })
  ],
  callbacks: {
    async jwt({ token, user }) {
      // 初始登录
      if (user) return { ...token, data: user };
      
      // 检查令牌有效期
      if (Date.now() < token.data.validity.valid_until * 1000) {
        return token;
      }
      
      // 刷新令牌逻辑
      if (Date.now() < token.data.validity.refresh_until * 1000) {
        return await refreshAccessToken(token);
      }
      
      // 令牌过期处理
      return { ...token, error: "RefreshTokenExpired" };
    },
    async session({ session, token }) {
      session.user = token.data.user;
      session.validity = token.data.validity;
      session.error = token.error;
      return session;
    }
  }
};

令牌刷新机制

实现自动刷新令牌的函数：

async function refreshAccessToken(token: JWT): Promise<JWT> {
  try {
    const res = await refresh(token.data.tokens.refresh);
    const accessToken = await res.json();
    
    const { exp } = jwtDecode(accessToken.access);
    
    return {
      ...token,
      data: {
        ...token.data,
        validity: {
          ...token.data.validity,
          valid_until: exp
        },
        tokens: {
          ...token.data.tokens,
          access: accessToken.access
        }
      }
    };
  } catch (error) {
    return { ...token, error: "RefreshAccessTokenError" };
  }
}

安全中间件

使用中间件处理令牌过期情况：

export default withAuth(
  async function middleware(req) {
    const token = await getToken({ req });
    
    if (token && Date.now() >= token.data.validity.refresh_until * 1000) {
      const response = NextResponse.redirect("/login");
      response.cookies.delete("next-auth.session-token");
      return response;
    }
    
    return NextResponse.next();
  },
  {
    callbacks: {
      authorized: ({ token }) => !!token
    }
  }
);

最佳实践建议

1. 令牌有效期设置：建议访问令牌设置较短有效期(如15分钟)，刷新令牌设置较长时间(如7天)

2. 错误处理：实现全面的错误处理机制，包括网络错误、令牌无效等情况

3. 安全考虑：

   • 使用HTTPS传输令牌
   • 实现CSRF保护
   • 考虑添加二次验证机制

4. 性能优化：

   • 缓存用户信息减少解码次数
   • 批量处理令牌刷新请求

5. 测试策略：

   • 单元测试各个回调函数
   • 集成测试完整认证流程
   • 模拟网络延迟和错误情况

常见问题解决

1. 令牌不更新问题：确保在刷新令牌时返回全新的对象，而不是修改现有对象

2. 类型冲突问题：仔细检查类型定义，确保与实现完全匹配

3. 会话同步问题：在多标签页情况下，需要考虑会话状态的同步

4. 跨域问题：如果前端和后端分离部署，需要正确配置CORS

总结

通过本文介绍的方法，开发者可以灵活地将NextAuth.js集成到已有JWT认证系统中，同时保留NextAuth.js提供的丰富功能和良好开发体验。关键在于正确理解NextAuth.js的工作机制，并通过类型扩展和回调函数实现自定义逻辑。这种方案既保留了现有后端认证系统的安全性，又能利用NextAuth.js简化前端认证流程的开发工作。