基於.NetCore3.1系列 ——認證授權方案之Swagger加鎖
阿新 • • 發佈:2020-07-14
# 一、前言
在之前的使用Swagger做Api文件中,我們已經使用Swagger進行開發介面文件,以及更加方便的使用。這一轉換,讓更多的介面可以以通俗易懂的方式展現給開發人員。而在後續的內容中,為了對api資源的保護,我們引入了認證授權方案,利用HTTP提供了一套標準的身份驗證框架,服務端可以用來針對客戶端的請求傳送質詢(challenge),客戶端根據質詢提供應答身份驗證憑證,進而實現對資源的保護。
因為之前在使用Swagger的系列中還沒有加身份認證授權這一塊,所以我們使用的介面都是沒有進行資源保護的,而再後續又對認證授權這一塊進行講解又沒有將Swagger好好的利用起來,使得每一次要測試授權認證的時候,都得使用postman在Hearer請求頭中加入Authorization屬性,導致每測試一個介面就得輸入一次token令牌來實現認證,重複操作頻繁,降低工作效率。
這個時候,我們剛好發現,Swagger已經幫我們是實現了一次輸入令牌,不同介面多次呼叫,提高效率。這樣,我們就可以將之前的Swagger系列和認證授權系列相結合。
說幹就幹。。。
![img](https://i02piccdn.sogoucdn.com/d9d838bbc0216c46)
# 二、回顧
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
# 四、執行
在**未加鎖**的情況下,效果如下:
![認證授權](https://img2020.cnblogs.com/blog/1576550/202007/1576550-20200713213630012-923688763.png)
加**上鎖**的程式後,執行後發現,
![認證授權](https://img2020.cnblogs.com/blog/1576550/202007/1576550-20200713213641713-1722828546.png)
**執行效果**:
![認證授權](https://img2020.cnblogs.com/blog/1576550/202007/1576550-20200713214044778-1002737085.gif)
# 五、總結
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%