Next-Shadcn-Dashboard-Starter 项目中实现 RefreshToken 过期自动登出机制

背景介绍

在基于 Next.js 和 NextAuth.js 构建的认证系统中，处理 JWT 令牌的刷新和过期是一个常见的需求。Next-Shadcn-Dashboard-Starter 项目提供了一个现代化的仪表板模板，其中包含了用户认证功能。本文将深入探讨如何在该项目中实现当 RefreshToken 过期时自动触发用户登出的机制。

核心问题分析

在传统的 JWT 认证流程中，通常会使用 AccessToken 和 RefreshToken 的组合。AccessToken 有效期较短，而 RefreshToken 有效期较长。当 AccessToken 过期时，系统会使用 RefreshToken 获取新的 AccessToken。但如果 RefreshToken 也过期了，就需要让用户重新登录。

实现方案详解

1. 认证配置设置

首先需要在 auth.config.ts 中配置认证提供者和回调函数：

const authConfig = {
  providers: [
    CredentialProvider({
      // 配置凭证提供者
      async authorize(credentials) {
        // 处理登录逻辑
      },
    }),
  ],
  callbacks: {
    async jwt({ token, user }) {
      // JWT 处理逻辑
    },
    async session({ session, token }) {
      // 会话处理逻辑
    },
  },
  // 其他配置...
};

2. 令牌刷新机制

实现 refreshAccessToken 函数来处理令牌刷新：

async function refreshAccessToken(token) {
  try {
    const response = await fetch(API_ENDPOINT, {
      method: "GET",
      credentials: 'include',
      headers: {
        // 包含必要的请求头
      }
    });
    
    if (!response.ok) throw error;
    
    const newToken = await response.json();
    const decoded = jwtDecode(newToken.token);
    
    return {
      ...token,
      accessToken: newToken.token,
      accessTokenExpires: decoded.exp * 1000,
    };
  } catch (error) {
    return {
      ...token,
      error: "RefreshAccessTokenError", // 标记刷新错误
    };
  }
}

3. JWT 回调处理

在 JWT 回调中实现令牌过期检查和刷新逻辑：

async jwt({ token, user }) {
  // 初始登录处理
  if (user) {
    const decoded = jwtDecode(user.accessToken);
    return {
      ...user,
      accessTokenExpires: decoded.exp * 1000,
    };
  }
  
  // 检查令牌是否过期
  if (Date.now() < token.accessTokenExpires) {
    return token;
  }
  
  // 尝试刷新令牌
  return await refreshAccessToken(token);
}

4. 会话回调处理

将错误信息传递到会话中：

async session({ session, token }) {
  session.user = {
    id: token.user.user_uuid,
    username: token.user.username,
    email: token.user.email,
    role: token.user.role
  };
  session.accessToken = token.accessToken;
  session.error = token.error; // 传递错误信息
  return session;
}

5. 客户端错误检测

在布局组件中监听会话错误并触发登出：

export default function Header() {
  const { data: session } = useSession();
  
  useEffect(() => {
    if(session?.error === "RefreshAccessTokenError") {
      console.log('检测到令牌刷新错误，正在登出...');
      signOut();
    }
  }, [session?.error]);
  
  return (
    // 布局组件内容
  );
}

常见问题与优化建议

1. 多次刷新请求问题：
   当 RefreshToken 过期时，可能会触发多次刷新请求。可以通过在 JWT 回调中添加额外的状态检查来避免这种情况。

2. 响应延迟问题：
   在慢速网络环境下，组件可能在会话更新前多次检查错误状态。可以考虑添加防抖机制。

3. 跨标签页同步：
   使用 window.addEventListener('storage', ...) 监听存储事件，确保所有标签页都能同步登出状态。

4. 用户体验优化：
   可以在登出前显示友好的提示信息，而不是直接强制登出。

最佳实践

1. 令牌有效期设置：

   • AccessToken 建议设置为 15-30 分钟
   • RefreshToken 建议设置为 7-30 天

2. 安全考虑：

   • 确保所有令牌传输都通过 HTTPS
   • 考虑实现令牌撤销机制

3. 错误处理：

   • 提供清晰的错误信息
   • 记录失败的刷新尝试

通过以上实现，Next-Shadcn-Dashboard-Starter 项目可以有效地处理 RefreshToken 过期情况，提供更安全、更流畅的用户认证体验。