NextAuth集成Keycloak：Next.js登出清会话但Keycloak会话未终止

核心问题原因 #

NextAuth 默认仅清除自身应用的会话，若要终止 Keycloak 端的全局会话，必须主动调用 Keycloak 的 OpenID Connect 登出端点，并传递必要的验证参数。

1. 正确调用 Keycloak 全局登出端点 #

Keycloak 的 /protocol/openid-connect/logout 是终止全局会话的核心端点，需携带两个关键参数：

• id_token_hint: 用户登录时获取的 ID Token（NextAuth 会自动存储在会话 token 中）
• post_logout_redirect_uri: 登出后跳转的地址，必须提前在 Keycloak 客户端的 Valid Post Logout Redirect URIs 列表中配置

在 NextAuth 的配置文件（pages/api/auth/[...nextauth].js）中，通过自定义 signOut 回调实现同步登出：

import NextAuth from "next-auth";
import KeycloakProvider from "next-auth/providers/keycloak";

export default NextAuth({
  providers: [
    KeycloakProvider({
      clientId: process.env.KEYCLOAK_CLIENT_ID,
      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
      issuer: process.env.KEYCLOAK_ISSUER,
    }),
  ],
  callbacks: {
    async signOut({ token }) {
      // 构造Keycloak登出URL
      const logoutUrl = new URL(`${process.env.KEYCLOAK_ISSUER}/protocol/openid-connect/logout`);
      logoutUrl.searchParams.set('id_token_hint', token.idToken);
      logoutUrl.searchParams.set('post_logout_redirect_uri', `${process.env.NEXTAUTH_URL}/`);
      
      // 重定向到Keycloak完成全局登出，之后会跳回配置的地址
      return logoutUrl.toString();
    },
  },
});

2. 令牌撤销（可选） #

若仅需使 Refresh Token 失效（不强制终止浏览器会话），可调用 /protocol/openid-connect/revoke 端点，需传递以下参数：

• token: 要撤销的 Refresh Token
• token_type_hint: 固定值 refresh_token
• 通过 Basic Auth 传递客户端 ID 和密钥

示例代码（可添加到 signOut 回调中）：

async function revokeRefreshToken(refreshToken) {
  const auth = btoa(`${process.env.KEYCLOAK_CLIENT_ID}:${process.env.KEYCLOAK_CLIENT_SECRET}`);
  const response = await fetch(`${process.env.KEYCLOAK_ISSUER}/protocol/openid-connect/revoke`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${auth}`
    },
    body: new URLSearchParams({
      token: refreshToken,
      token_type_hint: 'refresh_token'
    })
  });
  return response.ok;
}

3. 常见排查点 #

• 参数有效性：若调用端点返回 200 但会话未清除，优先检查 id_token_hint 是否正确，以及 post_logout_redirect_uri 是否在 Keycloak 客户端的白名单内
• Keycloak 客户端配置：确保客户端的 Access Type 为 confidential（使用密钥验证时），或 public 模式下正确配置了跳转地址
• NextAuth 令牌存储：可在 jwt 回调中打印 token，确认 idToken 字段是否存在且有效

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