NextAuth.js 与 Microsoft Entra ID 集成中的 JWT 序列化问题解析

问题背景

在使用 NextAuth.js 与 Microsoft Entra ID（原 Azure AD）进行身份验证集成时，开发者可能会遇到一个常见的错误："JWTs must use Compact JWS serialization, JWT must be a string"。这个错误通常发生在身份验证回调阶段，导致用户无法成功登录。

问题根源分析

该问题的核心在于 Microsoft Entra ID 返回的令牌格式与 NextAuth.js 期望的格式不匹配。具体来说，当应用程序注册为"单页应用(SPA)"类型时，Entra ID 会返回访问令牌(Access Token)而非 ID 令牌(ID Token)，而 NextAuth.js 期望接收的是符合 Compact JWS 序列化规范的 ID 令牌。

解决方案详解

1. 正确配置应用注册类型

在 Microsoft Entra ID 的应用注册中，必须将应用平台类型设置为"Web"而非"单页应用(SPA)"。这是因为：

• Web 应用类型会返回 ID 令牌，符合 JWT 规范
• SPA 类型返回的访问令牌格式不同，会导致序列化错误

配置路径：Entra ID 门户 → 应用注册 → 您的应用 → 认证 → 平台配置

2. 确保正确的令牌请求范围

在 NextAuth.js 配置中，必须明确请求 openid 范围，这是获取 ID 令牌的必要条件：

MicrosoftEntraID({
    clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
    clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
    issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
    authorization: {
        params: {
            scope: 'openid profile email'
        }
    }
})

3. 环境变量配置要点

确保以下环境变量正确设置：

• AUTH_MICROSOFT_ENTRA_ID_ID：应用注册中的"应用程序(客户端)ID"
• AUTH_MICROSOFT_ENTRA_ID_SECRET：必须是证书和密码中的"值"，而非"密码ID"
• AUTH_MICROSOFT_ENTRA_ID_ISSUER：格式必须为 https://login.microsoftonline.com/{租户ID}/v2.0

4. 基础设施注意事项

在部署环境中，特别是使用反向代理(如 Nginx)时，可能需要调整缓冲区大小设置以处理较大的身份验证令牌：

proxy_buffer_size 16k;
proxy_buffers 4 16k;
large_client_header_buffers 4 16k;

这些设置可以防止"upstream sent too big header"错误，确保完整的身份验证令牌能够通过代理传递。

最佳实践建议

1. 定期检查密钥有效期：过期的密钥会导致类似错误，建议设置提醒在密钥到期前更新

2. 区分开发和生产环境：为不同环境创建单独的应用注册，避免配置冲突

3. 日志记录：启用详细的日志记录以帮助诊断身份验证流程中的问题

4. 测试完整流程：在开发过程中测试从登录到回调的完整流程，而不仅仅是初始登录

通过遵循这些指导原则，开发者可以避免常见的 JWT 序列化问题，实现 NextAuth.js 与 Microsoft Entra ID 的无缝集成。