Next.js中Keycloak的Refresh Token API调用失败问题排查

1. 检查环境变量加载情况 #

• 确认.env文件里KEYCLOAK_CLIENT_ID和KEYCLOAK_CLIENT_SECRET配置正确，无拼写错误。
• 若代码运行在客户端组件中，环境变量需加NEXT_PUBLIC_前缀（如NEXT_PUBLIC_KEYCLOAK_CLIENT_ID），否则客户端无法读取；服务器组件/API路由无需前缀，但要确保构建时变量已正常注入。
• 可临时打印变量值，确认process.env.KEYCLOAK_CLIENT_ID和process.env.KEYCLOAK_CLIENT_SECRET不为undefined。

2. 验证Refresh Token的有效性 #

• 检查<refreshToken>是否从next-auth的session中正确获取。需在next-auth配置里确保refresh_token被存入session：

  // [...nextauth].js
  callbacks: {
    async session({ session, token }) {
      session.user.refreshToken = token.refreshToken;
      return session;
    },
    async jwt({ token, user, account }) {
      if (account && account.refresh_token) {
        token.refreshToken = account.refresh_token;
      }
      return token;
    }
  }
  

• 确认传入的refresh token未过期，且格式与Postman中使用的完全一致。

3. 修正响应处理的变量错误 #

代码最后一行的response变量未定义，若在Next.js API路由中，应使用res对象：

// 错误写法
return response.json(TokenResponse.data);

// 正确写法
return res.json(TokenResponse.data);

若为服务器组件，无需返回res.json，直接返回数据即可。

4. 解决跨域问题 #

若代码运行在客户端浏览器中，直接调用Keycloak的token端点会触发同源策略拦截（Postman不受此限制）。建议将请求放在Next.js API路由中做代理：

// app/api/refresh-token/route.js
import axios from 'axios';
import { NextResponse } from 'next/server';

export async function POST(req) {
  const { refreshToken } = await req.json();
  const url = `http://localhost:8080/realms/你的realm名称/protocol/openid-connect/token`;
  const keycloakParams = new URLSearchParams();
  
  keycloakParams.append('client_id', process.env.KEYCLOAK_CLIENT_ID!);
  keycloakParams.append('client_secret', process.env.KEYCLOAK_CLIENT_SECRET!);
  keycloakParams.append('grant_type', 'refresh_token');
  keycloakParams.append('refresh_token', refreshToken);
  
  try {
    const tokenResponse = await axios.post(url, keycloakParams, {
      headers: { "Content-Type": "application/x-www-form-urlencoded" }
    });
    return NextResponse.json(tokenResponse.data);
  } catch (error) {
    console.error('刷新token失败:', error.response?.data || error.message);
    return NextResponse.json({ error: '刷新token失败' }, { status: error.response?.status || 500 });
  }
}

客户端调用该API路由即可避免跨域问题。

5. 替换占位符并排查请求细节 #

• 确保URL中的<realm-name>已替换为实际的Keycloak realm名称，比如http://localhost:8080/realms/my-realm/protocol/openid-connect/token。
• 在catch块中打印错误响应，查看Keycloak返回的具体错误（如invalid_client、invalid_grant），精准定位问题。

内容的提问来源于stack exchange，提问作者Nikita