基於.NetCore3.1系列 ——認證授權方案之Swagger加鎖
阿新 • • 發佈：2020-07-14
# 一、前言
在之前的使用Swagger做Api文件中，我們已經使用Swagger進行開發介面文件，以及更加方便的使用。這一轉換，讓更多的介面可以以通俗易懂的方式展現給開發人員。而在後續的內容中，為了對api資源的保護，我們引入了認證授權方案，利用HTTP提供了一套標準的身份驗證框架，服務端可以用來針對客戶端的請求傳送質詢(challenge)，客戶端根據質詢提供應答身份驗證憑證，進而實現對資源的保護。
因為之前在使用Swagger的系列中還沒有加身份認證授權這一塊，所以我們使用的介面都是沒有進行資源保護的，而再後續又對認證授權這一塊進行講解又沒有將Swagger好好的利用起來，使得每一次要測試授權認證的時候，都得使用postman在Hearer請求頭中加入Authorization屬性，導致每測試一個介面就得輸入一次token令牌來實現認證，重複操作頻繁，降低工作效率。
這個時候，我們剛好發現，Swagger已經幫我們是實現了一次輸入令牌，不同介面多次呼叫，提高效率。這樣，我們就可以將之前的Swagger系列和認證授權系列相結合。
說幹就幹。。。
# 二、回顧
Swagger系列：
[基於.NetCore3.1系列 —— 使用Swagger做Api文件 (上篇)](https://www.cnblogs.com/i3yuan/p/12539597.html)
[基於.NetCore3.1系列 —— 使用Swagger做Api文件 (下篇)](https://www.cnblogs.com/i3yuan/p/12542291.html)
[基於.NetCore3.1系列 —— 使用Swagger匯出文件 (番外篇)](https://www.cnblogs.com/i3yuan/p/12633768.html)
[基於.NetCore3.1系列 —— 使用Swagger匯出文件 (補充篇)](https://www.cnblogs.com/i3yuan/p/12682728.html)
JWT認證授權系列：
[基於.NetCore3.1系列 —— 認證方案之初步認識JWT](https://www.cnblogs.com/i3yuan/p/11519431.html)
[基於.NetCore3.1系列 —— 認證授權方案之JwtBearer認證](https://www.cnblogs.com/i3yuan/p/13160022.html)
[基於.NetCore3.1系列 —— 認證授權方案之授權初識](https://www.cnblogs.com/i3yuan/p/13198355.html)
[基於.NetCore3.1系列 —— 認證授權方案之授權揭祕 (上篇)](https://www.cnblogs.com/i3yuan/p/13236777.html)
[基於.NetCore3.1系列 —— 認證授權方案之授權揭祕 (下篇)](https://www.cnblogs.com/i3yuan/p/13275774.html)
# 三、開始
## 3.1. 新增Swagger
這裡我們使用之前Swagger系列中的[原始碼](https://files-cdn.cnblogs.com/files/i3yuan/XUnit.Core%E7%95%AA%E5%A4%96%E7%AF%87.rar)，可以發現這個在沒有使用配置我們認證授權程式碼的情況下，資源api都是處於沒有保護的情況下，任何人都可以呼叫使用，沒有安全性。
```C#
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. 新增認證授權
基於之前的認證授權方案系列，我們這一節的認證授權就使用之前使用的[基於自定義策略授權](https://www.cnblogs.com/i3yuan/p/13198355.html#autoid-9-0-0)的方式，實現授權。
### 3.2.1. 定義許可權策略
定義一個許可權策略`PermissionRequirement`，這個策略幷包含一些屬性。
```c#
public class PermissionRequirement: IAuthorizationRequirement
{
public string _permissionName { get; }
public PermissionRequirement(string PermissionName)
{
_permissionName = PermissionName;
}
}
```
### 3.2.2. 再定義一個策略處理類
```c#
public class PermissionRequirementHandler : AuthorizationHandler
{
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` 集合）：
```C#
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
//基於自定義策略授權
services.AddAuthorization(options =>
{
options.AddPolicy("customizePermisson",
policy => policy
.Requirements
.Add(new PermissionRequirement("admin")));
});
//此外，還需要在 IAuthorizationHandler 型別的範圍內向 DI 系統註冊新的處理程式：
services.AddScoped();
// 如前所述，要求可包含多個處理程式。如果為授權層的同一要求向 DI 系統註冊多個處理程式，有一個成功就足夠了。
}
```
### 3.2.4. 應用自定義的策略的特性
指定當前使用者必須是應用對控制器或控制器內的操作，如
```c#
[Authorize(Policy = "customizePermisson")]
public class MovieController : ControllerBase
{
}
```
## 3.3. 新增Swagger鎖
利用Swagger為我們提供的介面，在AddSwaggerGen服務中，新增保護api資源的描述。
```c#
var openApiSecurity = new OpenApiSecurityScheme
{
Description = "JWT認證授權，使用直接在下框中輸入Bearer {token}（注意兩者之間是一個空格）\"",
Name = "Authorization", //jwt 預設引數名稱
In = ParameterLocation.Header, //jwt預設存放Authorization資訊的位置（請求頭）
Type = SecuritySchemeType.ApiKey
};
```
新增請求頭的Header中的token,傳遞到後臺。
```c#
c.OperationFilter();
```
開啟加權鎖
```c#
c.OperationFilter();
c.OperationFilter();
```
**程式碼整合如下**：在**ConfigureServices**服務中
```c#
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();
c.OperationFilter();
c.OperationFilter();
#endregion
});
```
> `c.AddSecurityDefinition("oauth2", openApiSecurity);` 這裡的方案名稱必須是oauth2
# 四、執行
在**未加鎖**的情況下，效果如下：
加**上鎖**的程式後，執行後發現，
**執行效果**：
# 五、總結
1. 通過上面的彙總，我們已經實現將Swagger和net core身份認證授權才能訪問介面
2. 在以後測試介面授權的時候，就可以直接通過Swagger中的鎖來除錯執行，減少重複新增令牌進行操作。
3. [原始碼地址](https://files-cdn.cnblogs.com/files/i3yuan/%E8%AE%A4%E8%AF%81%E6%8E%88%E6%9D%83Swagger%E5%8A%A0%E9%94%