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

问题背景

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

问题本质

这个错误的根本原因是 NextAuth.js 期望接收到的 JWT（JSON Web Token）采用 Compact JWS 序列化格式，而实际收到的令牌格式不符合预期。Compact JWS 是 JWT 的一种标准序列化方式，它将令牌的三个部分（头部、载荷和签名）用点号连接起来形成一个字符串。

常见解决方案

1. 应用注册平台类型设置

Microsoft Entra ID 会根据应用注册时选择的平台类型（Web 或 SPA）返回不同格式的令牌：

• Web 应用：返回 ID Token（符合 JWT 规范）
• 单页应用(SPA)：返回 Access Token（可能不符合 JWT 规范）

解决方案：在 Entra ID 的应用注册中，将平台类型设置为"Web"而非"单页应用"。

2. 正确的 API 权限配置

确保在 Entra ID 的应用注册中正确配置了 API 权限：

1. 添加"openid"作用域
2. 确保已授予管理员同意
3. 根据需要添加其他权限（如 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. 令牌有效期检查

检查 Entra ID 中配置的客户端密码是否已过期。过期的密钥会导致令牌生成失败或格式异常。

5. 服务器配置调整

对于部署在 NGINX 等服务器后的应用，可能需要调整缓冲区大小设置：

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

这些调整可以确保大型的认证头部能够被正确处理。

技术原理深入

Microsoft Entra ID 针对不同类型的应用（Web 和 SPA）采用不同的安全策略。对于 SPA 应用，Entra ID 会返回经过优化的 Access Token，这种令牌可能不符合标准的 JWT 格式。而 NextAuth.js 的验证机制严格要求符合 JWT 标准的令牌，因此当平台类型设置为 SPA 时就会出现兼容性问题。

最佳实践建议

1. 统一使用 Web 平台类型：即使开发的是 SPA 应用，也建议注册为 Web 应用类型
2. 完整的权限配置：始终包含 openid 作用域，并根据需要添加其他标准作用域
3. 定期检查密钥有效期：建立密钥轮换机制，避免因密钥过期导致生产环境故障
4. 环境隔离：为开发、测试和生产环境分别创建独立的应用注册
5. 日志监控：实现全面的日志记录，便于快速诊断认证问题

总结

NextAuth.js 与 Microsoft Entra ID 的集成问题大多源于配置细节。通过理解平台差异、正确配置应用注册和确保环境变量准确，开发者可以避免常见的 JWT 序列化问题。对于部署在服务器后的应用，还需要注意服务器的缓冲区配置，确保认证流程的完整性和可靠性。