NextAuth.js 中 Microsoft Entra ID 集成配置指南

背景介绍

在 NextAuth.js 项目中集成 Microsoft Entra ID（原 Azure AD）身份验证时，开发者经常会遇到配置问题。本文旨在澄清最新版本的配置方式，帮助开发者正确设置 Entra ID 认证流程。

配置变更历史

在 NextAuth.js 5.0.0-beta 版本中，Microsoft Entra ID 提供商的配置接口经历了重要变更：

1. 旧版配置（beta.20 及之前）使用 tenantId 参数
2. 新版配置（beta.25 及之后）改用 issuer 参数

正确配置方式

标准 Entra ID（工作账户）配置

MicrosoftEntraID({
  clientId: process.env.AZURE_ENTRA_CLIENT_ID,
  clientSecret: process.env.AZURE_ENTRA_CLIENT_SECRET,
  issuer: `https://login.microsoftonline.com/${process.env.AZURE_ENTRA_TENANT_ID}/v2.0`
})

Entra External ID（客户身份）配置

MicrosoftEntraID({
  clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
  clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
  issuer: `https://${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_ID}.ciamlogin.com/${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_ID}/v2.0`
})

环境变量设置建议

建议在 .env 文件中配置以下变量：

AZURE_ENTRA_CLIENT_ID=你的应用ID
AZURE_ENTRA_CLIENT_SECRET=你的应用密钥
AZURE_ENTRA_TENANT_ID=你的租户ID

常见问题解答

1. 为什么从 tenantId 改为 issuer？ 这是为了与 OIDC 标准保持一致，issuer 参数更准确地描述了身份提供者的端点位置。

2. 如何获取 issuer 值？ 对于标准 Entra ID，格式为 https://login.microsoftonline.com/{tenant_id}/v2.0 对于 External ID，格式为 https://{tenant_id}.ciamlogin.com/{tenant_id}/v2.0

3. 是否需要其他参数？ 大多数情况下，只需 clientId、clientSecret 和 issuer 三个参数即可完成基本认证流程。

最佳实践

1. 始终将敏感信息存储在环境变量中
2. 为不同环境（开发、测试、生产）配置不同的应用注册
3. 在 Entra ID 应用注册中正确配置重定向URI
4. 根据需要申请适当的 API 权限

故障排查

如果遇到认证问题，可以检查：

1. 应用注册中的平台配置是否正确
2. 重定向URI是否与 NextAuth.js 配置匹配
3. 应用是否已授予必要的 API 权限
4. 客户端密钥是否已过期

通过遵循这些指南，开发者应该能够顺利地在 NextAuth.js 项目中集成 Microsoft Entra ID 认证功能。