ASP.NET Core Blazor Web App 集成 Microsoft Entra 身份验证的实践指南

在开发基于 ASP.NET Core Blazor Web App 的应用时，集成 Microsoft Entra (原 Azure AD) 身份验证是一个常见需求。本文将详细介绍如何正确配置 Microsoft Entra 身份验证，并解决与本地 Identity 账户系统共存时可能遇到的问题。

核心问题分析

许多开发者在尝试将 Microsoft Entra 身份验证集成到 Blazor Web App 时，会遇到以下典型问题：

1. 回调路径配置错误导致的认证失败
2. 本地 Identity 账户与外部身份验证提供商的冲突
3. Cookie 认证方案配置不当导致的登录异常

正确配置 Microsoft Entra 身份验证

1. 使用正确的身份验证中间件

不再推荐使用传统的 AddMicrosoftAccount 方法，而应该使用 Microsoft.Identity.Web 包提供的 AddMicrosoftIdentityWebApp 方法。这种方法与 Microsoft Entra 平台的最新规范保持一致。

2. 回调路径配置

确保在 Azure 应用注册中配置的回调路径与代码中的设置一致。AddMicrosoftIdentityWebApp 默认使用 /signin-oidc 作为回调路径，这与 Microsoft Entra 文档中的建议一致。

3. 认证方案配置

正确的认证方案配置对于同时支持本地 Identity 账户和外部身份验证至关重要：

var authBuilder = builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = IdentityConstants.ApplicationScheme;
    options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
});

authBuilder.AddMicrosoftIdentityWebApp(
    builder.Configuration.GetSection("AzureAd"),
    cookieScheme: null);  // 关键参数，让 Identity 管理 Cookie

authBuilder.AddIdentityCookies();

关键配置说明

1. cookieScheme: null 参数：
   这个参数确保由 Identity 系统而不是外部身份验证提供商来管理 Cookie。这是实现本地账户和外部身份验证共存的关键。

2. DefaultScheme 设置：
   设置为 IdentityConstants.ApplicationScheme 可以确保系统优先使用 Identity 系统进行认证。

3. ID Token 配置：
   与某些文档建议不同，实际使用中需要启用 ID Token 才能正常工作，特别是在 Blazor Web App 场景中。

常见问题解决方案

问题1：认证失败，提示"No reply address provided"

解决方案：

• 确保 Azure 应用注册中配置的回调路径与代码中的设置一致
• 使用 /signin-oidc 作为回调路径
• 检查租户ID配置是否正确

问题2：本地账户和外部身份验证无法同时工作

解决方案：

• 按照上文所示的认证方案配置
• 特别注意 cookieScheme: null 参数的使用
• 确保认证中间件的添加顺序正确

问题3：登录后无法保持会话

解决方案：

• 检查 Cookie 认证配置
• 确保 Identity 的 Cookie 配置没有被覆盖
• 验证认证方案的一致性

最佳实践建议

1. 统一使用 Microsoft.Identity.Web：
   始终使用最新的 Microsoft.Identity.Web 包而不是传统的身份验证方法。

2. 配置隔离：
   将 Microsoft Entra 的配置放在独立的配置节中，便于管理和维护。

3. 测试验证：
   在开发过程中，同时测试本地账户和外部身份验证的登录流程，确保两者都能正常工作。

4. 日志记录：
   在开发阶段启用详细的认证日志，有助于快速定位问题。

通过遵循这些指导原则和配置建议，开发者可以顺利地在 ASP.NET Core Blazor Web App 中集成 Microsoft Entra 身份验证，同时保持与本地 Identity 系统的兼容性。