ASP.NET Core 静态文件鉴权实战：用认证与授权策略保护 Static Files

ASP.NET Core 静态文件鉴权实战：用认证与授权策略保护 Static Files

【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore

本指南以 ASP.NET Core 官方仓库 StaticFilesAuth 示例 为主体，系统讲解如何为静态文件资源启用认证与授权。示例展示了两种互补的保护方案：一是针对特定 URL 路径要求"必须登录"（仅认证），二是借助自定义授权策略精细控制"谁能访问哪些文件"（认证 + 授权）。读完本文，你将掌握Map分支管道、UseAuthorization、Endpoint元数据注入、PhysicalFileProvider与文件服务器组合等关键技术，并能在自己的项目中落地实现。

示例项目概览

示例项目位于仓库src/Security/samples/StaticFilesAuth/目录，是一个标准的 ASP.NET Core MVC 应用（Microsoft.NET.Sdk.Web），其核心目标是演示对静态文件的访问控制。README 明确给出了两条主线：

1. 对于给定 URL 路径，只允许已认证（authenticated）用户访问静态文件——对应 Startup.cs 中的/MapAuthenticatedFiles；
2. 对于给定 URL 路径，使用授权策略（authorization policy）决定谁能访问特定文件——对应 Startup.cs 中的/MapImperativeFiles。

README 还特别强调：你可以用任意用户名登录；在授权策略场景下，用户只能访问与其用户名匹配的目录。这种"目录即身份"的设计让策略效果一目了然，非常适合作为学习与演示素材。

静态文件防护的两种思路

要理解该示例，先要分清 ASP.NET Core 中认证（Authentication）与授权（Authorization）两个阶段：

• 认证：确认"你是谁"。示例通过 Cookie 认证方案（CookieAuthenticationDefaults.AuthenticationScheme）完成身份识别。
• 授权：确认"你能不能做这件事"。示例使用IAuthorizationService配合授权策略，在认证通过后再做二次判定。

默认情况下，app.UseStaticFiles()直接以匿名方式把wwwroot下的文件暴露给所有请求。示例在 Startup.cs 中保留了这一行为（公开目录），而将需要保护的敏感文件放在PrivateFiles目录下，由专用分支管道托管。这种"公开与私有目录分离"的布局是静态文件防护的常见最佳实践。

两个受保护路径的实现差异在于元数据：

• /MapAuthenticatedFiles分支为端点附加了AuthorizeAttribute(null)（策略为 null），仅要求登录；
• /MapImperativeFiles分支为端点附加了AuthorizeAttribute("files")，要求满足名为files的自定义策略。

动手运行示例

在仓库根目录执行以下命令即可启动：

./restore.sh ./eng/build.sh --projects src/Security/samples/StaticFilesAuth/StaticFilesAuth.csproj

或者直接用 Visual Studio / VS Code 打开src/Security/下的解决方案筛选文件（Security.slnf）运行该项目。启动配置见 launchSettings.json：默认监听https://localhost:5001与http://localhost:5000，并以Development环境启动。

启动后访问首页/，页面列出两个入口链接：

• /MapAuthenticatedFiles
• /MapImperativeFiles

未登录时访问任意受保护路径，会被UseAuthorization拦截并跳转到登录页（Login.cshtml）。登录表单只需输入用户名（密码任意），提交后即完成 Cookie 签发；策略场景下，用户名将决定你可访问的目录。

认证与登录实现

Cookie 认证注册

在ConfigureServices中注册 Cookie 认证：

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie();

AddCookie()使用默认 Cookie 名称、默认登录路径等约定。示例项目未自定义CookieAuthenticationOptions，因此跳转登录、拒绝访问等行为均采用框架默认值。

直接签发身份（不依赖 Identity）

AccountController.cs 演示了不借助 ASP.NET Core Identity、直接用HttpContext.SignInAsync手工签发登录态的方式：

[HttpPost] public async Task<IActionResult> Login(string userName, string password, string returnUrl = null) { ViewData["ReturnUrl"] = returnUrl; // Normally Identity handles sign in, but you can do it directly if (ValidateLogin(userName, password)) { var claims = new List<Claim> { new Claim("user", userName), new Claim("role", "Member") }; await HttpContext.SignInAsync(new ClaimsPrincipal(new ClaimsIdentity(claims, "Cookies", "user", "role"))); if (Url.IsLocalUrl(returnUrl)) { return Redirect(returnUrl); } else { return Redirect("/"); } } return View(); }

要点说明：

• ValidateLogin在示例中恒返回true（"所有登录均成功"），便于演示；
• 声明（Claims）包含user（用户名）与role（角色）；ClaimsIdentity的authenticationType为"Cookies"，nameType为"user"，roleType为"role"，这决定了User.Identity.Name的取值来源；
• Url.IsLocalUrl(returnUrl)用于防止开放重定向攻击；
• 登出使用HttpContext.SignOutAsync()（Logout）。

登录后，导航栏通过 _LoginPartial.cshtml 显示当前用户名与登出按钮；未登录则显示"Login"链接。

场景一：仅认证保护（/MapAuthenticatedFiles）

原理与代码

Configure中先为受保护文件创建PhysicalFileProvider，指向PrivateFiles目录：

var files = new PhysicalFileProvider(Path.Combine(env.ContentRootPath, "PrivateFiles"));

随后用app.Map("/MapAuthenticatedFiles", ...)开启独立分支管道，其内部按顺序注册三个中间件：

app.Map("/MapAuthenticatedFiles", branch => { branch.Use((context, next) => { SetFileEndpoint(context, files, null); return next(context); }); branch.UseAuthorization(); SetupFileServer(branch, files); });

执行流程为：

1. 第一个内联中间件调用SetFileEndpoint，为当前请求对应的文件构造并附加Endpoint元数据（含AuthorizeAttribute(null)）；
2. UseAuthorization()读取端点元数据中的AuthorizeAttribute，发现策略为 null 时仅要求已认证；未认证请求将被拒绝并触发跳转登录；
3. SetupFileServer启动启用了目录浏览的UseFileServer托管文件。

private void SetupFileServer(IApplicationBuilder builder, IFileProvider files) { builder.UseFileServer(new FileServerOptions() { EnableDirectoryBrowsing = true, FileProvider = files }); }

FileServerOptions.EnableDirectoryBrowsing = true会启用目录列表页，便于在浏览器中直接浏览PrivateFiles下的目录树。

为什么必须先 SetEndpoint 再 UseAuthorization

在端点路由模型中，UseAuthorization依赖context.GetEndpoint()从请求中解析端点，进而读取其EndpointMetadataCollection中的AuthorizeAttribute。SetFileEndpoint正是负责把静态文件"伪装"成带授权元数据的端点：

private static void SetFileEndpoint(HttpContext context, PhysicalFileProvider files, string policy) { var fileSystemPath = GetFileSystemPath(files, context.Request.Path); if (fileSystemPath != null) { var metadata = new List<object> { new DirectoryInfo(Path.GetDirectoryName(fileSystemPath)), new AuthorizeAttribute(policy) }; var endpoint = new Endpoint( requestDelegate: null, new EndpointMetadataCollection(metadata), context.Request.Path); context.SetEndpoint(endpoint); } }

关键点：这里手工构造的Endpoint没有RequestDelegate（静态文件由后续的 FileServer 中间件处理），它的作用纯粹是携带元数据。GetFileSystemPath先尝试把请求路径解析为存在的文件，若失败再尝试解析为存在的目录（兼容目录浏览场景），都失败则返回null，此时不附加端点、UseAuthorization不会拦截（相当于 404 由文件服务器自然返回）。

场景二：授权策略保护（/MapImperativeFiles）

策略定义

ConfigureServices中注册名为files的授权策略：

services.AddAuthorization(options => { var basePath = Path.Combine(HostingEnvironment.ContentRootPath, "PrivateFiles"); var usersPath = Path.Combine(basePath, "Users"); // When using this policy users are only authorized to access the base directory, the Users directory, // and their own directory under Users. options.AddPolicy("files", builder => { builder.RequireAuthenticatedUser().RequireAssertion(context => { var userName = context.User.Identity.Name; userName = userName?.Split('@').FirstOrDefault(); if (userName == null) { return false; } if (context.Resource is HttpContext httpContext && httpContext.GetEndpoint() is Endpoint endpoint) { var userPath = Path.Combine(usersPath, userName); var directory = endpoint.Metadata.GetMetadata<DirectoryInfo>(); if (directory != null) { return string.Equals(directory.FullName, basePath, StringComparison.OrdinalIgnoreCase) || string.Equals(directory.FullName, usersPath, StringComparison.OrdinalIgnoreCase) || string.Equals(directory.FullName, userPath, StringComparison.OrdinalIgnoreCase) || directory.FullName.StartsWith(userPath + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase); } throw new InvalidOperationException($"Missing file system metadata."); } throw new InvalidOperationException($"Unknown resource type '{context.Resource.GetType()}'"); }); }); });

策略逻辑逐条解读：

• RequireAuthenticatedUser()：先要求已登录；
• RequireAssertion(...)：再执行自定义断言。断言从context.User.Identity.Name取用户名，并剔除@之后的域名部分（支持user@domain形式的账号）；
• 从context.Resource取出HttpContext，再经GetEndpoint()取得端点，并从端点元数据中读取先前SetFileEndpoint写入的DirectoryInfo——该对象代表请求文件所在目录；
• 目录匹配规则（大小写不敏感）：
  • 等于basePath（PrivateFiles根目录）；
  • 等于usersPath（PrivateFiles/Users）；
  • 等于userPath（PrivateFiles/Users/{userName}，即用户自己的目录）；
  • 以userPath + 目录分隔符开头（用户自己目录的任意子目录）；
• 端点缺失DirectoryInfo元数据或Resource类型异常时，直接抛出InvalidOperationException，避免静默放行。

分支管道

app.Map("/MapImperativeFiles", branch => { branch.Use((context, next) => { SetFileEndpoint(context, files, "files"); return next(context); }); branch.UseAuthorization(); SetupFileServer(branch, files); });

与场景一唯一的差别是SetFileEndpoint传入策略名"files"。UseAuthorization遇到带策略名的AuthorizeAttribute时，会调用IAuthorizationService执行该策略，未通过则返回 403 并跳转到拒绝访问页（AccessDenied.cshtml）。

目录结构：用文件系统组织权限边界

受保护文件按"用户名 = 目录名"的约定组织：

PrivateFiles/ ├── private.html # 策略允许所有登录用户访问 ├── private.txt # 策略允许所有登录用户访问 └── Users/ ├── privatesub.html # 位于 Users 目录下，策略允许所有登录用户访问 ├── User1/ │ └── user1file.html └── User2/ └── user2file.html

结合上面的匹配规则：

• 以User1登录时，可访问private.html、private.txt、Users/privatesub.html，以及Users/User1/下的全部内容；
• 访问Users/User2/user2file.html会被拒绝（403）；
• 未登录访问任何受保护路径都会先被重定向到登录页。

这些文件在 StaticFilesAuth.csproj 中通过<Content Include=...><CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory></Content>配置为随构建复制到输出目录，确保运行时PhysicalFileProvider能定位到它们。

请求管道顺序的关键性

Configure中完整的管道顺序是：

app.UseStaticFiles(); // 公开静态文件（wwwroot），匿名可访问 app.UseAuthentication(); // 认证中间件（为后续授权提供 User） app.Map("/MapAuthenticatedFiles", ...); // 分支 1：仅认证 app.Map("/MapImperativeFiles", ...); // 分支 2：授权策略 app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapDefaultControllerRoute(); });

需要注意的细节：

1. 两个受保护分支使用app.Map在端点路由之前直接按路径前缀分流，形成独立子管道，因此分支内的UseAuthorization是"旧式中间件管道"授权，与后面 MVC 端点路由的授权互不干扰；
2. Map分支内部没有UseStaticFiles，而是用UseFileServer（其内部已包含静态文件中间件）并提供PrivateFiles作为FileProvider，实现"文件源替换"；
3. 公共UseStaticFiles()只服务wwwroot，与私有文件目录严格隔离；
4. 两处UseAuthentication()分别服务于分支管道内的授权与 MVC 端点路由授权。

原理延伸：静态文件鉴权的通用套路

从本例可以提炼出在 ASP.NET Core 中保护静态文件的三种通用模式：

本示例的核心技巧——把静态文件映射为携带授权元数据的Endpoint——正是理解UseAuthorization与静态文件协作的关键：授权中间件只认端点元数据，不关心文件本身如何被服务。

小结

StaticFilesAuth 示例完整展示了在 ASP.NET Core 中为静态文件叠加认证与授权能力的标准手法：

• 用app.Map为受保护路径建立独立管道，SetFileEndpoint注入AuthorizeAttribute与DirectoryInfo元数据；
• 用UseAuthorization统一执行"仅认证"或"自定义策略"两种判定；
• 用PhysicalFileProvider+UseFileServer托管wwwroot之外的私有文件目录；
• 用"用户名 = 目录名"的文件系统布局承载策略规则，实现按用户隔离的静态文件访问控制。

这套方案不依赖 Identity、不修改文件系统权限，纯靠中间件与元数据即可落地，可直接迁移到需要"按目录/按用户隔离静态资源"的真实项目中。更多相关源码与测试可继续翻阅仓库中的 Middleware/StaticFiles 与 Security/Authorization 目录。

【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore