基於.NetCore3.1系列 ——認證授權方案之Swagger加鎖

艾三元發表於2020-07-14
NetCoreSwagger

一、前言

在之前的使用Swagger做Api文件中，我們已經使用Swagger進行開發介面文件，以及更加方便的使用。這一轉換，讓更多的介面可以以通俗易懂的方式展現給開發人員。而在後續的內容中，為了對api資源的保護，我們引入了認證授權方案，利用HTTP提供了一套標準的身份驗證框架，服務端可以用來針對客戶端的請求傳送質詢(challenge)，客戶端根據質詢提供應答身份驗證憑證，進而實現對資源的保護。

因為之前在使用Swagger的系列中還沒有加身份認證授權這一塊，所以我們使用的介面都是沒有進行資源保護的，而再後續又對認證授權這一塊進行講解又沒有將Swagger好好的利用起來，使得每一次要測試授權認證的時候，都得使用postman在Hearer請求頭中加入Authorization屬性，導致每測試一個介面就得輸入一次token令牌來實現認證，重複操作頻繁，降低工作效率。

這個時候，我們剛好發現，Swagger已經幫我們是實現了一次輸入令牌，不同介面多次呼叫，提高效率。這樣，我們就可以將之前的Swagger系列和認證授權系列相結合。

說幹就幹。。。

img

二、回顧

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. 原始碼地址

相關文章