将FormsAuthentication迁移至.NET 5.0的最优实现方案咨询

前置准备 #

• 梳理原有Forms身份验证全链路逻辑：包括Cookie加密规则、票证过期策略、Ticket存储的自定义字段、授权拦截规则、登出逻辑，以及是否存在跨站点Cookie共享、多系统统一登录的场景
• 完成.NET 5项目除身份验证外的基础业务迁移验证，保证业务逻辑可正常运行，避免多问题耦合导致排查困难

核心方案：用ASP.NET Core Cookie认证原生替换Forms认证 #

.NET 5官方推荐用Cookie认证作为Forms认证的替代方案，整体改造成本最低，逻辑对齐度最高：

1. 注册认证服务
   在Startup.cs的ConfigureServices方法中添加服务注册代码：

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        // 路径配置和原有Forms认证逻辑完全对齐
        options.LoginPath = "/Account/Login";
        options.LogoutPath = "/Account/Logout";
        options.AccessDeniedPath = "/Error/AccessDenied";
        // Cookie配置和原有规则保持一致
        options.Cookie.Name = ".YourApp.Auth";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.SameAsRequest;
        options.ExpireTimeSpan = TimeSpan.FromMinutes(30); // 和原有Forms票证过期时间对齐
        options.SlidingExpiration = true; // 按需开启滑动过期，和原有逻辑一致
    });

2. 配置中间件
   注意中间件顺序必须严格遵循：先认证、后授权，顺序错误会导致所有授权逻辑失效
   在Startup.cs的Configure方法中按顺序添加中间件：

app.UseRouting();
// 先加认证中间件
app.UseAuthentication();
// 后加授权中间件
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
});

3. 替换原有Forms认证API
   原有Forms相关的API全部替换为ASP.NET Core Cookie认证的对应方法：

• 登录逻辑：登录校验通过后，构造ClaimsPrincipal对象，将原有Forms Ticket中存储的用户名、用户ID、自定义字段全部存入Claim集合，调用HttpContext.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, claimsPrincipal) 签发认证Cookie
• 登出逻辑：直接调用HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme) 清除Cookie
• 身份读取逻辑：原有读取用户身份的逻辑全部改为从HttpContext.User的Claims集合中获取，原有[Authorize]特性可直接复用，无需修改
• 自定义授权过滤器：如果原有过滤器依赖Forms认证的对象，改为读取HttpContext.User的Claims即可

存量用户无感知兼容方案（可选） #

如果需要迁移后存量用户不需要重新登录，可增加旧Forms Cookie兼容逻辑：

原有Forms认证采用MachineKey加密Cookie，.NET Core无原生MachineKey实现，需手动实现解密逻辑

• 提取原有.NET Framework项目web.config中<machineKey>节点的validationKey、decryptionKey和对应的加密算法
• 自定义Cookie认证的TicketDataFormat，实现对旧Forms Cookie的解密逻辑，解密成功后直接转换为ASP.NET Core的AuthenticationTicket，用户无需重新登录
• 等全量上线后所有存量旧Cookie过期，即可移除兼容逻辑，降低后续维护成本

验证与上线 #

• 功能测试：覆盖登录、登出、匿名访问、授权访问、过期Cookie校验等场景，保证逻辑和原有行为完全一致
• 业务校验：验证依赖用户身份的业务逻辑全部正常，Ticket中的自定义字段可正确读取
• 灰度上线：先切小流量验证，观测登录成功率、401错误率等指标，无异常后再全量发布

内容的提问来源于stack exchange，提问作者Rafael