Asp.Net Core遇到Swagger(五)-Swashbuckle-Jwt篇
1
前言
結(jié)合Asp.Net Core認(rèn)證-Jwt-基礎(chǔ)篇，本篇文章將講解基于Swashbuckle的實(shí)踐應(yīng)用操作和配置。Swashbuckle 基于 Jwt 實(shí)現(xiàn)安全認(rèn)證。
2
實(shí)踐技巧
使用 Swagger 添加 Jwt 安全認(rèn)證的前提是，當(dāng)前項(xiàng)目已經(jīng)引入 Jwt 驗(yàn)證，實(shí)現(xiàn)基本的 Jwt 生成和認(rèn)證功能。此處將不再重復(fù)講解，具體可參考[Asp.Net Core認(rèn)證-Jwt-基礎(chǔ)篇]https://blog.csdn.net/qq_28806349/article/details/120191348，以下為 基礎(chǔ)篇 中引入Swashbuckle相關(guān)類庫(kù)時(shí)，需要的如下操作。
2.1、引入依賴
Nuget引入庫(kù)依賴，項(xiàng)目中依賴版本如下：
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="3.1.17" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="6.0.0" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.0.0" />
</ItemGroup>
</Project>2.2、配置服務(wù)
Startup.cs中添加服務(wù)與啟用對(duì)應(yīng)中間件，代碼如下：
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
//設(shè)置secret
byte[] secret = System.Text.Encoding.UTF8.GetBytes("1234567890123456");
//添加認(rèn)證服務(wù)
services.AddAuthentication(config => {
//設(shè)置默認(rèn)架構(gòu)
config.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
//默認(rèn)認(rèn)證架構(gòu)
//config.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
})
//添加Jwt自定義配置
.AddJwtBearer(config => {
//設(shè)置Token驗(yàn)證參數(shù)項(xiàng)
config.TokenValidationParameters = new TokenValidationParameters
{
//認(rèn)證秘鑰
IssuerSigningKey = new SymmetricSecurityKey(secret),
//是否調(diào)用對(duì) securityToken 簽名的
//Microsoft.IdentityModel.Tokens.SecurityKey 的驗(yàn)證
ValidateIssuerSigningKey = true,
//頒發(fā)者
ValidIssuer = "ggcy",
//是否驗(yàn)證頒發(fā)者
ValidateIssuer = true,
//受眾
ValidAudience = "Audience",
//是否驗(yàn)證受眾
ValidateAudience = true,
//是否驗(yàn)證憑證有效時(shí)限
ValidateLifetime = true,
ClockSkew = TimeSpan.FromMinutes(5)
};
});
services.AddSwaggerGen(options => {
#region Jwt
//定義安全方案
options.AddSecurityDefinition("oauth2", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
{
//描述信息
Description = "請(qǐng)輸入帶有Bearer的Token，形如 “Bearer {Token}” ",
//Header對(duì)應(yīng)名稱
Name = "Authorization",
//驗(yàn)證類型，此處使用Api Key
Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
//設(shè)置 API 密鑰的位置
In = Microsoft.OpenApi.Models.ParameterLocation.Header
});
//指定方案應(yīng)用范圍
options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement {
{
new Microsoft.OpenApi.Models.OpenApiSecurityScheme {
Reference = new Microsoft.OpenApi.Models.OpenApiReference
{ Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,Id="oauth2"}
},
new []{
"readAccess",
"writeAccess"
}
}
});
#endregion
});
}2.3、啟用中間件
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
// 1、啟用靜態(tài)文件中間件
app.UseStaticFiles();
// 2、添加Swagger中間件到管道中
app.UseSwagger();
// 3、添加SwaggerUI到管道中
app.UseSwaggerUI();
app.UseRouting();
//啟用認(rèn)證管道中間件
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}需要注意的是，由于SwaggerUI需要請(qǐng)求服務(wù)端的靜態(tài)資源，所以需要在啟用SwaggerUI中間件前，開(kāi)啟靜態(tài)資源中間件，建議測(cè)試使用時(shí)，依據(jù)注釋部分進(jìn)行中間件引入。
2.4、測(cè)試認(rèn)證
配置完成后，調(diào)試運(yùn)行，訪問(wèn)默認(rèn)地址 http://localhost:5000/swagger/index.html ，出現(xiàn)如下結(jié)果：
1）獲取Token
請(qǐng)求文檔中的 Token 接口，獲取到認(rèn)證的之后的 Token 值，操作如下：
2）請(qǐng)求接口
再次請(qǐng)求，能夠依靠 Token ，通過(guò)認(rèn)證，訪問(wèn)到對(duì)應(yīng) Api 數(shù)據(jù)。
以上為引入Jwt，再結(jié)合 Swashbuckle 實(shí)現(xiàn)的基礎(chǔ)安全操作。具體細(xì)化操作，可閱讀筆者其他內(nèi)容。
往期推薦