NextAuth配置自定义Scope后无法返回自定义Claims问题

可能的原因及解决步骤 #

1. 先确认ID Token中是否包含目标声明 #

首先要验证授权服务器是否真的在ID Token里返回了这些自定义声明。可以在jwt回调中打印完整的token内容，或者用jwt.io解码查看：

// [...nextauth].js
import jwt from "jsonwebtoken";

export default NextAuth({
  // 其他配置项...
  callbacks: {
    async jwt({ token, user, account }) {
      // 首次登录时，account.id_token包含完整的ID Token
      if (account?.id_token) {
        const decoded = jwt.decode(account.id_token);
        console.log("解码后的ID Token:", decoded); // 检查是否存在自定义声明
      }
      return token;
    },
  },
});

如果解码后看不到目标声明，说明授权服务器未返回，需要检查作用域参数是否正确传递，或联系授权服务器管理员确认配置。

2. 配置jwt回调提取自定义声明 #

NextAuth默认只会提取标准声明，需要手动在jwt回调中将自定义声明添加到token对象：

callbacks: {
  async jwt({ token, user, account }) {
    if (account?.id_token) {
      const decoded = jwt.decode(account.id_token);
      // 将自定义声明挂载到token上
      token.external_groups = decoded.external_groups;
      token.access_roles = decoded.access_roles;
      token.groups = decoded.groups;
      token.custom_claims = decoded.custom_claims;
      token.provider_claims = decoded.provider_claims;
    }
    return token;
  },
},

3. 配置session回调将声明传递到前端 #

如果需要在前端的session中访问这些声明，还要在session回调中把token里的自定义声明同步过去：

callbacks: {
  // 上述jwt回调...
  async session({ session, token }) {
    // 将自定义声明添加到session.user对象中
    session.user.external_groups = token.external_groups;
    session.user.access_roles = token.access_roles;
    session.user.groups = token.groups;
    session.user.custom_claims = token.custom_claims;
    session.user.provider_claims = token.provider_claims;
    return session;
  },
},

4. 确认授权请求的作用域参数正确 #

检查NextAuth的provider配置中，授权参数是否正确传递了所有需要的作用域：

export default NextAuth({
  providers: [
    OAuthProvider({
      // 其他provider配置...
      authorization: {
        params: {
          scope: 'openid profile email external_groups access_roles groups custom_claims provider_claims'
        }
      }
    })
  ],
  // 其他配置...
});

确保作用域字符串无拼写错误，与授权服务器支持的列表完全匹配。

额外检查点 #

• 若使用OpenID连接，确认授权服务器返回的是ID Token，而非仅返回Access Token
• 部分授权服务器需要在客户端应用中额外配置权限，才能返回自定义声明

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