NextAuth.js 中 Microsoft Entra 身份验证的正确配置方式

在 NextAuth.js 项目中集成 Microsoft Entra (原 Azure AD) 身份验证时，开发者经常会遇到配置问题。本文将详细介绍正确的配置方法，帮助开发者避免常见陷阱。

配置参数变更

最新版本的 NextAuth.js 对 Microsoft Entra 提供商的配置接口进行了调整。原先使用的 tenantId 参数已被弃用，取而代之的是 issuer 参数。这一变更反映了 OAuth 2.0 和 OpenID Connect 规范的最佳实践。

正确配置方式

对于标准 Microsoft Entra 租户，应采用以下配置格式：

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

其中 issuer 参数需要包含完整的颁发者 URL，格式为 https://login.microsoftonline.com/{tenant_id}/v2.0。

针对 Entra External ID 的特殊配置

如果使用 Microsoft Entra External ID (CIAM) 解决方案，配置方式略有不同：

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_SUB_DOMAIN}.ciamlogin.com/${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_ID}/v2.0`,
  token: `https://${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_SUB_DOMAIN}.ciamlogin.com/${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_ID}/oauth2/v2.0/token`,
  authorization: {
    url: `https://${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_SUB_DOMAIN}.ciamlogin.com/${process.env.AUTH_MICROSOFT_ENTRA_ID_TENANT_ID}/oauth2/v2.0/authorize`,
    params: {
      scope: "openid profile email offline_access"
    }
  }
})

环境变量设置建议

为了保持配置的灵活性，建议将敏感信息存储在环境变量中：

AUTH_MICROSOFT_ENTRA_ID_ID="你的客户端ID"
AUTH_MICROSOFT_ENTRA_ID_SECRET="你的客户端密钥"
AUTH_MICROSOFT_ENTRA_ID_TENANT_ID="你的租户ID"
AUTH_MICROSOFT_ENTRA_ID_TENANT_SUB_DOMAIN="你的租户子域名(仅CIAM需要)"

常见问题解决

1. 认证失败：检查 issuer URL 是否包含正确的租户ID和协议版本(v2.0)
2. 范围不足：确保请求了足够的权限范围(scope)
3. 令牌验证问题：验证颁发者URL是否与令牌中的iss声明完全匹配

通过遵循这些配置指南，开发者可以顺利地在 NextAuth.js 项目中集成 Microsoft Entra 身份验证功能。