基于.NetCore3.1系列 ——认证授权方案之Swagger加锁

一、前言

在之前的使用Swagger做Api文档中，我们已经使用Swagger进行开发接口文档，以及更加方便的使用。这一转换，让更多的接口可以以通俗易懂的方式展现给开发人员。而在后续的内容中，为了对api资源的保护，我们引入了认证授权方案，利用HTTP提供了一套标准的身份验证框架，服务端可以用来针对客户端的请求发送质询(challenge)，客户端根据质询提供应答身份验证凭证，进而实现对资源的保护。

因为之前在使用Swagger的系列中还没有加身份认证授权这一块，所以我们使用的接口都是没有进行资源保护的，而再后续又对认证授权这一块进行讲解又没有将Swagger好好的利用起来，使得每一次要测试授权认证的时候，都得使用postman在Hearer请求头中加入Authorization属性，导致每测试一个接口就得输入一次token令牌来实现认证，重复操作频繁，降低工作效率。

这个时候，我们刚好发现，Swagger已经帮我们是实现了一次输入令牌，不同接口多次调用，提高效率。这样，我们就可以将之前的Swagger系列和认证授权系列相结合。

说干就干。。。

二、回顾

Swagger系列：

基于.NetCore3.1系列 —— 使用Swagger做Api文档 (上篇)

基于.NetCore3.1系列 —— 使用Swagger做Api文档 (下篇)

基于.NetCore3.1系列 —— 使用Swagger导出文档 (番外篇)

基于.NetCore3.1系列 —— 使用Swagger导出文档 (补充篇)

JWT认证授权系列：

基于.NetCore3.1系列 —— 认证方案之初步认识JWT

基于.NetCore3.1系列 —— 认证授权方案之JwtBearer认证

基于.NetCore3.1系列 —— 认证授权方案之授权初识

基于.NetCore3.1系列 —— 认证授权方案之授权揭秘 (上篇)

基于.NetCore3.1系列 —— 认证授权方案之授权揭秘 (下篇)

三、开始

3.1. 添加Swagger

这里我们使用之前Swagger系列中的源码，可以发现这个在没有使用配置我们认证授权代码的情况下，资源api都是处于没有保护的情况下，任何人都可以调用使用，没有安全性。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Version = "V1",   //版本
                    Title = $"XUnit.Core 接口文档-NetCore3.1",  //标题
                    Description = $"XUnit.Core Http API v1",    //描述
                    Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },
                    License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }
                });
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
               //var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名
                c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释
                // c.IncludeXmlComments(xmlPath,true); //这个是controller的注释
            });
            services.AddControllers();
        }

3.2. 添加认证授权

基于之前的认证授权方案系列，我们这一节的认证授权就使用之前使用的基于自定义策略授权的方式，实现授权。

3.2.1. 定义权限策略

定义一个权限策略PermissionRequirement，这个策略并包含一些属性。

public class PermissionRequirement: IAuthorizationRequirement
{
    public string _permissionName { get; }

    public PermissionRequirement(string PermissionName)
    {
        _permissionName = PermissionName;
    }
}

3.2.2. 再定义一个策略处理类

public class PermissionRequirementHandler : AuthorizationHandler<PermissionRequirement>
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, PermissionRequirement requirement)
    {
        var role = context.User.FindFirst(c => c.Type == ClaimTypes.Role);
        if (role != null)
        {
            var roleValue = role.Value;
            if (roleValue==requirement._permissionName)
            {
                context.Succeed(requirement);
            }
        }
        return Task.CompletedTask;
    }
}

3.2.3. 下面展示了如何将自定义要求添加到策略

（请注意，由于这是自定义要求，因此没有扩展方法，而必须继续处理策略对象的整个 Requirements 集合）：

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        //基于自定义策略授权
        services.AddAuthorization(options =>
        {
            options.AddPolicy("customizePermisson",
              policy => policy
                .Requirements
                .Add(new PermissionRequirement("admin")));
        });
        //此外，还需要在 IAuthorizationHandler 类型的范围内向 DI 系统注册新的处理程序：
        services.AddScoped<IAuthorizationHandler, PermissionRequirementHandler>();
        // 如前所述，要求可包含多个处理程序。如果为授权层的同一要求向 DI 系统注册多个处理程序，有一个成功就足够了。

    }

3.2.4. 应用自定义的策略的特性

指定当前用户必须是应用对控制器或控制器内的操作，如

   [Authorize(Policy = "customizePermisson")]
    public class MovieController : ControllerBase
    {
    }

3.3. 添加Swagger锁

利用Swagger为我们提供的接口，在AddSwaggerGen服务中，添加保护api资源的描述。

  var openApiSecurity = new OpenApiSecurityScheme
  {
      Description = "JWT认证授权，使用直接在下框中输入Bearer {token}（注意两者之间是一个空格）\"",
      Name = "Authorization",  //jwt 默认参数名称
      In = ParameterLocation.Header,  //jwt默认存放Authorization信息的位置（请求头）
      Type = SecuritySchemeType.ApiKey
  };

添加请求头的Header中的token,传递到后台。

c.OperationFilter<SecurityRequirementsOperationFilter>();

开启加权锁

c.OperationFilter<AddResponseHeadersFilter>();
c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();

代码整合如下：在ConfigureServices服务中

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("V1", new OpenApiInfo
            {
                Version = "V1",   //版本
                Title = $"XUnit.Core 接口文档-NetCore3.1",  //标题
                Description = $"XUnit.Core Http API v1",    //描述
                Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },
                License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }
            });
            var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
           //var basePath = AppContext.BaseDirectory;
            var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//这个就是刚刚配置的xml文件名
           // c.IncludeXmlComments(xmlPath);//默认的第二个参数是false,对方法的注释
             c.IncludeXmlComments(xmlPath,true); // 这个是controller的注释

			#region 加锁
            var openApiSecurity = new OpenApiSecurityScheme
            {
                Description = "JWT认证授权，使用直接在下框中输入Bearer {token}（注意两者之间是一个空格）\"",
                Name = "Authorization",  //jwt 默认参数名称
                In = ParameterLocation.Header,  //jwt默认存放Authorization信息的位置（请求头）
                Type = SecuritySchemeType.ApiKey
            };

            c.AddSecurityDefinition("oauth2", openApiSecurity);
            c.OperationFilter<AddResponseHeadersFilter>();
            c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
            c.OperationFilter<SecurityRequirementsOperationFilter>();
            #endregion
        });

c.AddSecurityDefinition("oauth2", openApiSecurity); 这里的方案名称必须是oauth2

四、运行

在未加锁的情况下，效果如下：

加上锁的程序后，执行后发现，

执行效果：

五、总结

1. 通过上面的汇总，我们已经实现将Swagger和net core身份认证授权才能访问接口
2. 在以后测试接口授权的时候，就可以直接通过Swagger中的锁来调试运行，减少重复添加令牌进行操作。
3. 源码地址