本文将分别简单介绍 Authentication(认证) 和 Authorization(授权)。
并以简单的例子在 ASP.NET Core 6.0 的 WebAPI 中以 JWT 方案实现认证,并辅以相应的授权例子。
Authentication 和 Authorization 长得很像,傻傻分不清楚。
Authentication(认证):标识用户的身份,一般发生在登录的时候。
Authorization(授权):授予用户权限,指定用户能访问哪些资源;授权的前提是知道这个用户是谁,所以授权必须在认证之后。
其实,认证和授权其实是不分家的。
安装 Microsoft.AspNetCore.Authentication.JwtBearer
在控制台中:
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer -v 6.0.1在 appsetting.json 中,添加一个 Jwt 节点
"Jwt": {     "SecretKey": "lisheng741@qq.com",     "Issuer": "WebAppIssuer",     "Audience": "WebAppAudience" }在 Program.cs 文件中注册服务,和调用相关中间件。
//引入所需的命名空间 using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.IdentityModel.Tokens; using System.Text;  var configuration = builder.Configuration;  //注册服务 builder.Services.AddAuthentication(options => {     options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme; }) .AddJwtBearer(options => {     options.TokenValidationParameters = new TokenValidationParameters()     {         ValidateIssuer = true, //是否验证Issuer         ValidIssuer = configuration["Jwt:Issuer"], //发行人Issuer         ValidateAudience = true, //是否验证Audience         ValidAudience = configuration["Jwt:Audience"], //订阅人Audience         ValidateIssuerSigningKey = true, //是否验证SecurityKey         IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"])), //SecurityKey         ValidateLifetime = true, //是否验证失效时间         ClockSkew = TimeSpan.FromSeconds(30), //过期时间容错值,解决服务器端时间不同步问题(秒)         RequireExpirationTime = true,     }; });  //调用中间件:UseAuthentication(认证),必须在所有需要身份认证的中间件前调用,比如 UseAuthorization(授权)。 app.UseAuthentication(); app.UseAuthorization();主要是用于生成 JWT 的 Token。
using Microsoft.IdentityModel.Tokens; using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Text;  namespace AuthenticationTest;  public class JwtHelper {     private readonly IConfiguration _configuration;      public JwtHelper(IConfiguration configuration)     {         _configuration = configuration;     }      public string CreateToken()     {         // 1. 定义需要使用到的Claims         var claims = new[]         {             new Claim(ClaimTypes.Name, "u_admin"), //HttpContext.User.Identity.Name             new Claim(ClaimTypes.Role, "r_admin"), //HttpContext.User.IsInRole("r_admin")             new Claim(JwtRegisteredClaimNames.Jti, "admin"),             new Claim("Username", "Admin"),             new Claim("Name", "超级管理员")         };          // 2. 从 appsettings.json 中读取SecretKey         var secretKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration["Jwt:SecretKey"]));          // 3. 选择加密算法         var algorithm = SecurityAlgorithms.HmacSha256;          // 4. 生成Credentials         var signingCredentials = new SigningCredentials(secretKey, algorithm);          // 5. 根据以上,生成token         var jwtSecurityToken = new JwtSecurityToken(             _configuration["Jwt:Issuer"],     //Issuer             _configuration["Jwt:Audience"],   //Audience             claims,                          //Claims,             DateTime.Now,                    //notBefore             DateTime.Now.AddSeconds(30),    //expires             signingCredentials               //Credentials         );          // 6. 将token变为string         var token = new JwtSecurityTokenHandler().WriteToken(jwtSecurityToken);          return token;     } }该 JwtHelper 依赖于 IConfiguration(为了读取配置文件),将 JwtHelper 的创建交由 DI 容器,在 Program.cs 中添加服务:
builder.Services.AddSingleton(new JwtHelper(configuration));将 JwtHelper 注册为单例模式。
新建一个 AccountController,以构造函数方式注入 JwtHelper,添加两个 Action:GetToken 用于获取 Token,GetTest 打上 [Authorize] 标签用于验证认证。
using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Mvc;  namespace AuthenticationTest.Controllers;  [Route("api/[controller]/[action]")] [ApiController] public class AccountController : ControllerBase {     private readonly JwtHelper _jwtHelper;      public AccountController(JwtHelper jwtHelper)     {         _jwtHelper = jwtHelper;     }      [HttpGet]     public ActionResult<string> GetToken()     {         return _jwtHelper.CreateToken();     }      [Authorize]     [HttpGet]     public ActionResult<string> GetTest()     {         return "Test Authorize";     } }方式一:通过 Postman、Apifox 等接口调试软件调试
使用 Postman 调用 /api/Account/GetToken 生成 Token
在调用 /api/Account/GetTest 时传入 Token,得到返回结果
方式二:在浏览器控制台调试
调试 /api/Account/GetToken
var xhr = new XMLHttpRequest(); xhr.addEventListener("readystatechange", function() {    if(this.readyState === 4) {       console.log(token = this.responseText); //这里用了一个全局变量 token,为下一个接口服务    } }); xhr.open("GET", "/api/Account/GetToken"); xhr.send();调试 /api/Account/GetTest
var xhr = new XMLHttpRequest(); xhr.addEventListener("readystatechange", function() {    if(this.readyState === 4) {       console.log(this.status, this.responseText); //this.status为响应状态码,401为无认证状态    } }); xhr.open("GET", "/api/Account/GetTest"); xhr.setRequestHeader("Authorization",`Bearer ${token}`); //附带上 token xhr.send();注意:授权必须基于认证,即:若没有完成上文关于认证的配置,则下面的授权是不会成功的。
其实 JWT 是认证的一种方案,其他的方案如 Cookies。本节介绍的授权,实际上与 JWT 没有什么关系,是基于 ASP.NET Core 的基本能力。
这一部分,将先介绍相关标签、授权方式,再介绍基于策略的授权。这三部分大致的内容如下描述:
相关标签:Authorize 和 AllowAnonymous
授权方式:介绍三种授权方式(Policy、Role、Scheme)
基于策略(Policy)的授权:深入 Policy 授权方式
授权相关标签具体请查考官方文档简单授权
打上该标签的 Controller 或 Action 必须经过认证,且可以标识需要满足哪些授权规则。
授权规则可以是 Policy(策略)、Roles(角色) 或 AuthenticationSchemes(方案)。
[Authorize(Policy = "", Roles ="", AuthenticationSchemes ="")]允许匿名访问,级别高于 [Authorize] ,若两者同时作用,将生效 [AllowAnonymous]
基本上授权只有:Policy、Role、Scheme 这3种方式,对应 Authorize 标签的3个属性。
推荐的授权方式,在 ASP.NET Core 的官方文档提及最多的。一个 Policy 可以包含多个要求(要求可能是 Role 匹配,也可能是 Claims 匹配,也可能是其他方式。)
下面举个基础例子(说是基础例子,主要是基于 Policy 的授权方式可以不断深入追加一些配置):
在 Program.cs 中,添加两条 Policy:
policy1 要求用户拥有一个 Claim,其 ClaimType 值为 EmployeeNumber。
policy2 要求用户拥有一个 Claim,其 ClaimType 值为 EmployeeNumber,且其 ClaimValue 值为1、2、3、4 或 5。
builder.Services.AddAuthorization(options => {     options.AddPolicy("policy1", policy => policy.RequireClaim("EmployeeNumber"));     options.AddPolicy("policy2", policy => policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5")); })在控制器中添加 [Authorize] 标签即可生效:
[Authorize(Policy = "policy1")] public class TestController : ControllerBase或在控制器的 Action 上:
public class TestController : ControllerBase {     [Authorize(Policy = "policy1")]     public ActionResult<string> GetTest => "GetTest"; }基于角色授权,只要用户拥有角色,即可通过授权验证。
在认证时,给用户添加角色相关的 Claim ,即可标识用户拥有的角色(注:一个用户可以拥有多个角色的 Claim),如:
new Claim(ClaimTypes.Role, "admin"), new Claim(ClaimTypes.Role, "user")在 Controller 或 Action 中:
[Authorize(Roles = "user")] public class TestController : ControllerBase {     public ActionResult<string> GetUser => "GetUser";          [Authorize(Roles = "admin")] //与控制器的Authorize叠加作用,除了拥有user,还需拥有admin     public ActionResult<string> GetAdmin => "GetAdmin";          [Authorize(Roles = "user,admin")] //user 或 admin 其一满足即可     public ActionResult<string> GetUserOrAdmin => "GetUserOrAdmin"; }方案如:Cookies 和 Bearer,当然也可以是自定义的方案。
由于这种方式不常用,这里不做展开,请参考官方文档按方案限制标识。
上面已经提及了一个基于策略授权的基础例子,下面将继续深入这种授权方式。
授权主要的方式,是通过 Handler 程序判断授权,需要实现的接口是 IAuthorizationHandler。
基于策略的授权,需要继承 AuthorizationHandler<TRequirement> 并重写 HandleRequirementAsync 方法,该方法需要 Requirement 作为入参,相关的接口是 IAuthorizationRequirement。
具体步骤为:
在实现 Requirement 之前,我们需要先定义一些权限项,主要用于后续作为 Policy 的名称,并传入 我们实现的 Requirement 之中。
public static class Permissions {     public const string User = "User";     public const string UserCreate = User + ".Create";     public const string UserDelete = User + ".Delete";     public const string UserUpdate = User + ".Update"; }如上,定义了“增”、“删”、“改”等权限,其中 User 将拥有完整权限。
public class PermissionAuthorizationRequirement : IAuthorizationRequirement {     public PermissionAuthorizationRequirement(string name)     {         Name = name;     }     public string Name { get; set; } }使用 Name 属性表示权限的名称,与 Permissions 中的常量对应。
这里假定用户的 Claim 中 ClaimType 为 Permission 的项,如:
new Claim("Permission", Permissions.UserCreate), new Claim("Permission", Permissions.UserUpdate)如上,标识该用户用户 UserCreate 和 UserUpdate 的权限。
注意:当然,实际程序我们肯定不是这样实现的,这里只是简易示例。
接着,实现一个授权 Handler:
public class PermissionAuthorizationHandler : AuthorizationHandler<PermissionAuthorizationRequirement> {     protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, PermissionAuthorizationRequirement requirement)     {         var permissions = context.User.Claims.Where(_ => _.Type == "Permission").Select(_ => _.Value).ToList();         if (permissions.Any(_ => _.StartsWith(requirement.Name)))         {             context.Succeed(requirement);         }         return Task.CompletedTask;     } }运行HandleRequirementAsync 时,会将用户的 Claim 中 ClaimType 为 Permission 的项取出,并获取其 Value 组成一个List<string>。
接着验证 Requirement 是否满足授权,满足则运行context.Succeed 。
在 Program.cs 中,将PermissionAuthorizationHandler 添加到 DI 中:
builder.Services.AddSingleton<IAuthorizationHandler, PermissionAuthorizationHandler>();builder.Services.AddAuthorization(options => {     options.AddPolicy(Permissions.UserCreate, policy => policy.AddRequirements(new PermissionAuthorizationRequirement(Permissions.UserCreate)));     options.AddPolicy(Permissions.UserUpdate, policy => policy.AddRequirements(new PermissionAuthorizationRequirement(Permissions.UserUpdate)));     options.AddPolicy(Permissions.UserDelete, policy => policy.AddRequirements(new PermissionAuthorizationRequirement(Permissions.UserDelete))); });控制器如下:
[Route("api/[controller]/[action]")] [ApiController] public class UserController : ControllerBase {     [HttpGet]     [Authorize(Permissions.UserCreate)]     public ActionResult<string> UserCreate() => "UserCreate";      [HttpGet]     [Authorize(Permissions.UserUpdate)]     public ActionResult<string> UserUpdate() => "UserUpdate";      [HttpGet]     [Authorize(Permissions.UserDelete)]     public ActionResult<string> UserDelete() => "UserDelete"; }基于上面的假定,用户访问接口的情况如下:
/api/User/UserCreate #成功 /api/User/UserUpdate #成功 /api/User/UserDelete #403无权限至此,基于策略(Policy)的授权其实已经基本完成。
接下去的内容,将是对上面一些内容的完善或补充。
一般添加授权策略如下是在 Program.cs 中,方式如下:
builder.Services.AddAuthorization(options => {     options.AddPolicy("policy", policy => policy.RequireClaim("EmployeeNumber")); });通过 AuthorizationOptions.AddPolicy 添加授权策略这种方式不灵活,无法动态添加。
通过实现 IAuthorizationPolicyProvider 并添加到 DI 中,可以实现动态添加 Policy。
IAuthorizationPolicyProvider 的默认实现为 DefaultAuthorizationPolicyProvider 。
实现一个 PolicyProvider 如下:
public class TestAuthorizationPolicyProvider : DefaultAuthorizationPolicyProvider, IAuthorizationPolicyProvider {     public TestAuthorizationPolicyProvider(IOptions<AuthorizationOptions> options) : base(options) { }      public new Task<AuthorizationPolicy> GetDefaultPolicyAsync()         =>  base.GetDefaultPolicyAsync();      public new Task<AuthorizationPolicy?> GetFallbackPolicyAsync()         => base.GetFallbackPolicyAsync();      public new Task<AuthorizationPolicy?> GetPolicyAsync(string policyName)     {         if (policyName.StartsWith(Permissions.User))         {             var policy = new AuthorizationPolicyBuilder(JwtBearerDefaults.AuthenticationScheme);             policy.AddRequirements(new PermissionAuthorizationRequirement(policyName));             return Task.FromResult<AuthorizationPolicy?>(policy.Build());         }         return base.GetPolicyAsync(policyName);     } }注意:自定义的TestAuthorizationPolicyProvider 必须实现IAuthorizationPolicyProvider,否则添加到 DI 时会不生效。
在 Program.cs 中,将自定义的 PolicyProvider 添加到 DI 中:
builder.Services.AddSingleton<IAuthorizationPolicyProvider, TestAuthorizationPolicyProvider>();注意:只会生效最后一个添加的 PolicyProvider。
自定义 AuthorizationMiddleware 可以:
具体请查看官方文档自定义 AuthorizationMiddleware 的行为
具体请查看官方文档基于资源的授权
在 MiniApi 中几乎都是形如 MapGet() 的分支节点,这类终结点无法使用 [Authorize] 标签,可以用使用 RequireAuthorization("Something") 进行授权,如:
app.MapGet("/helloworld", () => "Hello World!")     .RequireAuthorization("AtLeast21");建议看一下ASP.NET Core 认证与授权6:授权策略是怎么执行的?这篇文章,文章将授权相关的源码整理出来了,并说明了其中的关系。
与授权相关的 interface 和 class 如下:
IAuthorizationService #验证授权的服务,主要方法AuthorizeAsync DefaultAuthorizationService #IAuthorizationService的默认实现 IAuthorizationHandler #负责检查是否满足要求,主要方法HandleAsync IAuthorizationRequirement #只有属性,没有方法;用于标记服务,以及用于追踪授权是否成功的机制。 AuthorizationHandler<TRequirement> #主要方法HandleRequirementAsync这里简述一下其关系:
[Authorize] 标签生效时,调用的是IAuthorizationService 的AuthorizeAsync(由DefaultAuthorizationService 实现)。
AuthorizeAsync 会去调用所有IAuthorizationHandler 的HandleAsync (由AuthorizationHandler<TRequirement> 实现)。
HandleAsync 会去调用AuthorizationHandler<TRequirement>  的HandleRequirementAsync 的方法。
注意:这里只是列出了主要的接口和类,部分没有列出,如:IAuthorizationHandlerProvider(这个接口的默认实现DefaultAuthorizationHandlerProvider,主要是用于收集IAuthorizationHandler 并返回IEnumerable<IAuthorizationHandler>)
Gitee:https://gitee.com/lisheng741/testnetcore/tree/master/Security/AuthenticationTest
Github:https://github.com/lisheng741/testnetcore/tree/master/Security/AuthenticationTest
ASP.NET Core 6.0 官方文档:授权策略提供程序
ASP.NET Core 认证与授权6:授权策略是怎么执行的?(mark:这篇很强!)