ASP.NET Core Web Api實作JWT驗證筆記
此為紀錄筆者實作JWT驗證過程筆記。 專案使用.Net 5，並使用.Net Core CLI進行建置 使用Visual Code作為開發工具
有關.Net Core CLI 可參考 https://docs.microsoft.com/zh-tw/dotnet/core/tools/
GitHub https://github.com/s123600g/jyu.lab.jwt
環境建置
下載.Net Core SDK選擇.Net 5版本並安裝 https://dotnet.microsoft.com/download
透過下方指令確認是否安裝無誤，正常會出現版本號
專案建置
建立方案檔(sln)
dotnet new sln -n jyu.lab.jwt
-n 為方案檔名稱
建立.gitignore
這裡可以視需要再做
建立WebApi專案
dotnet new webapi -n Lab_JWT
-n 為設置專案名稱
透過下方指令將專案加入至方案內
dotnet sln add .\Lab_JWT\Lab_JWT.csproj
設置信任ASP.NET Core HTTPS 開發憑證
dotnet dev-certs https --trust
可以參考 https://docs.microsoft.com/zh-tw/aspnet/core/security/enforcing-ssl?view=aspnetcore-5.0&tabs=visual-studio#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos
建立好了之後，請在終端機透過cd指令進入專案目錄內，下方步驟需要再專案目錄內進行。
安裝Nuget套件
Microsoft.AspNetCore.Authentication.JwtBearer https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 5.0.6
NLog https://www.nuget.org/packages/NLog/
dotnet add package NLog --version 4.7.10
NLog.Web.AspNetCore https://www.nuget.org/packages/NLog.Web.AspNetCore/4.13.0-readme-preview
dotnet add package NLog.Web.AspNetCore --version 4.12.0
配置NLog
關於配置可以參考Getting started with ASP.NET Core 5 https://github.com/NLog/NLog/wiki/Getting-started-with-ASP.NET-Core-5
在配置之前要先完成安裝必要的Nuget套件，在上方步驟有安裝指令。
在專案目錄內建立一個nlog.config檔案，並在方案檔加入必要設置，請透過Visual Code進行操作。
開啟Lab_JWT.csproj在裡面加入下方配置
<ItemGroup>
<Content Update="nlog.config">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
<CopyToPublishDirectory>Always</CopyToPublishDirectory>
</Content>
</ItemGroup>
這裡用意是在建置/發佈階段時，指定將nlog.config複製一份到bin/底下對應的各階段目錄內去。 如果沒設置的話在執行的時候NLog不會正常運作起來。 複製條件為Always代表無論有沒有更動內容都複製更新。
將以下內容複製到nlog.config
<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
internalLogLevel="Trace"
internalLogFile="${basedir}\Log\internal_nlog\internal-nlog.txt">
<!-- enable asp.net core layout renderers -->
<extensions>
<add assembly="NLog.Web.AspNetCore"/>
</extensions>
<!-- the targets to write to -->
<targets>
<!-- write logs to file -->
<target xsi:type="File" name="allfile" fileName="${basedir}\Log\web\nlog-all-${shortdate}.log"
layout="${longdate} [${uppercase:${level}}] ${message} ${newline}${exception:format=tostring}" />
<!-- another file log, only own logs. Uses some ASP.NET core renderers -->
<target xsi:type="File" name="ownFile-web" fileName="${basedir}\Log\coreown\nlog-own-${shortdate}.log"
layout="${longdate} [${uppercase:${level}}] ${logger} | ${message} ${newline}${exception:format=tostring} | url: ${aspnet-request-url} action: ${aspnet-mvc-action}" />
<target xsi:type="Console" name="lifetimeConsole"
layout="${date} [${uppercase:${level}}] ${message} ${newline}${exception}" />
</targets>
<!-- rules to map from logger name to target -->
<rules>
<!--All logs, including from Microsoft-->
<logger name="*" minlevel="Info" writeTo="allfile" />
<!--Output hosting lifetime messages to make Docker / Visual Studio happy -->
<logger name="Microsoft.Hosting.Lifetime" level="Info" writeTo="lifetimeConsole, ownFile-web" final="true" />
<!--Skip non-critical Microsoft logs and so log only own logs-->
<logger name="Microsoft.*" maxlevel="Info" final="true" /> <!-- BlackHole without writeTo -->
<logger name="*" minlevel="Trace" writeTo="ownFile-web" />
</rules>
</nlog>
在專案啟動時會在專案目錄下自動建置Log/，裡面會放置NLog產生的紀錄檔案 通常會看的是在coreown/與web/底下的紀錄檔 關於配置內容設定可以參考 https://github.com/NLog/NLog/wiki/Configuration-file
註冊NLog為Log提供者
開啟專案內Program.cs，並引入以下套件
在Main區塊將原始內容更改為以下
public static void Main(string[] args)
{
NLog.Logger logger = NLogBuilder.ConfigureNLog("nlog.config").GetCurrentClassLogger();
try
{
logger.Debug("The app init main");
CreateHostBuilder(args).Build().Run();
}
catch (Exception exception)
{
//NLog: catch setup errors
logger.Error(exception, "Stopped program because of exception");
throw;
}
finally
{
// 確保當App結束時，NLog正常結束釋放掉
// Ensure to flush and stop internal timers/threads before application-exit (Avoid segmentation fault on Linux)
NLog.LogManager.Shutdown();
}
}
在第一行為最重要，他會載入nlog.config依據裡面的內容進行配置NLog。 可以看到原始只有一行CreateHostBuilder(args).Build().Run();，經過配置NLog變成包覆在try-catch-finally裡面結構。 確保app啟動過程中如果發生意外而導致啟動失敗，可以啟動失敗錯誤紀錄，前提是NLog有先被正常載入。 在finally區塊內NLog.LogManager.Shutdown();是為了當app被關掉後，讓NLog程序正常關閉。
在CreateHostBuilder區塊將原始內容更改為以下
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
})
// 重新設置app Log配置
.ConfigureLogging(logging =>
{
// 清除app預設Log Provider
logging.ClearProviders();
// 設定Log輸出最小層級
logging.SetMinimumLevel(LogLevel.Trace);
})
.UseNLog(); // NLog: Setup NLog for Dependency injection);
這裡透過ConfigureLogging來進行app預設Log提供者解除，並設定要輸出的最低Log層級。 最後透過UseNLog()來注入NLog服務成為app預設Log提供者。
JWT服務
實作一個專門處理JWT處理的服務，並透過DI(Dependency Injection)注入方式供app使用。
使用擴充方法來註冊服務群組 https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-5.0#register-groups-of-services-with-extension-methods
建立JWTCliam.cs，並放置在專案Models/
namespace Lab_JWT.Models
{
public class JWTCliam
{
/// <summary>
/// 聲明資訊-發行者
/// </summary>
/// <value></value>
public string iss { set; get; }
/// <summary>
/// 聲明資訊-User內容
/// </summary>
/// <value></value>
public string sub { set; get; }
/// <summary>
/// 聲明資訊-接收者
/// </summary>
/// <value></value>
public string aud { set; get; }
/// <summary>
/// 聲明資訊-有效期限
/// </summary>
/// <value></value>
public string exp { set; get; }
/// <summary>
/// 聲明資訊-起始時間
/// </summary>
/// <value></value>
public string nbf { set; get; }
/// <summary>
/// 聲明資訊-發行時間
/// </summary>
/// <value></value>
public string iat { set; get; }
/// <summary>
/// 聲明資訊-獨立識別ID
/// </summary>
/// <value></value>
public string jti { set; get; }
}
}
放置聲明資訊(Claim)內容各項預設參數內容Data Model。 在api接收到請求後，內部處理會先封裝好聲明資訊內容，再呼叫JWT處理服務內功能時會帶此Data Model。 有關於聲明資訊(Claim)可以參考 https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims#reserved-claims
建立JWTConfig.cs，並放置在專案Models/
namespace Lab_JWT.Models
{
public class JWTConfig
{
/// <summary>
/// 發行者
/// </summary>
/// <value></value>
public string Issuer { set; get; }
/// <summary>
/// 加密金鑰
/// </summary>
/// <value></value>
public string SignKey { set; get; }
/// <summary>
/// 設置Token存活多久(分鐘)
/// </summary>
/// <value></value>
public int ExpireDateTime { set; get; }
}
}
放置有關Token相關設定項目內容Data Model。 這裡設定項目跟Token本身有關，會跟appsettings.json內JWTConfig配置相對應 在api接收到請求後，內部處理會先封裝Token本身設定內容，再呼叫JWT處理服務內功能時會帶此Data Model。
建立JWTServices.cs，並放置在專案Services/
using Microsoft.Extensions.Logging;
using Microsoft.IdentityModel.Tokens;
using System;
using System.Collections.Generic;
using System.Security.Claims;
using System.Text;
using System.IdentityModel.Tokens.Jwt;
using Lab_JWT.Models;
namespace Lab_JWT.Services
{
public interface JWTBase
{
/// <summary>
/// 產生JWT Token
/// </summary>
/// <param name="jWTCliam">Token 資訊聲明內容物件</param>
/// <param name="secretKey">加密金鑰，用來做加密簽章用</param>
/// <param name="issur">Token 發行者資訊</param>
/// <param name="expireMinutes">Token 有效期限(分鐘)</param>
/// <returns>回應內容物件，內容屬性jwt放置Token字串</returns>
RunStatus GetJWT(
JWTCliam jWTCliam,
string secretKey,
string issuer,
int expireMinutes = 30
);
}
public class JWTServices : JWTBase
{
private readonly ILogger<JWTServices> log;
public JWTServices(ILogger<JWTServices> logger)
{
log = logger;
}
public RunStatus GetJWT(
JWTCliam jWTCliam,
string secretKey,
string issuer,
int expireMinutes = 30
)
{
RunStatus response = new RunStatus();
try
{
#region Step 1. 取得資訊聲明(claims)集合
List<Claim> claims = GenCliams(jWTCliam);
#endregion
#region Step 2. 建置資訊聲明(claims)物件實體，依據上面步驟產生Data來做
ClaimsIdentity userClaimsIdentity = new ClaimsIdentity(claims);
#endregion
#region Step 3. 建立Token加密用金鑰
SymmetricSecurityKey securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey));
#endregion
#region Step 4. 建立簽章，依據金鑰
// 使用HmacSha256進行加密
SigningCredentials signingCredentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256Signature);
#endregion
#region Step 5. 建立Token內容實體
SecurityTokenDescriptor tokenDescriptor = new SecurityTokenDescriptor
{
Issuer = issuer, // 設置發行者資訊
Audience = issuer, // 設置驗證發行者對象，如果需要驗證Token發行者，需要設定此項目
NotBefore = DateTime.Now, // 設置可用時間， 預設值就是 DateTime.Now
IssuedAt = DateTime.Now, // 設置發行時間，預設值就是 DateTime.Now
Subject = userClaimsIdentity, // Token 針對User資訊內容物件
Expires = DateTime.Now.AddMinutes(expireMinutes), // 建立Token有效期限
SigningCredentials = signingCredentials // Token簽章
};
#endregion
#region Step 6. 產生JWT Token並轉換成字串
JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler(); // 建立一個JWT Token處理容器
SecurityToken securityToken = tokenHandler.CreateToken(tokenDescriptor); // 將Token內容實體放入JWT Token處理容器
string serializeToken = tokenHandler.WriteToken(securityToken); // 最後將JWT Token處理容器序列化，這一個就是最後會需要的Token 字串
#endregion
response.isSuccess = true; // 告訴使用此請求一方Token成功產生
response.jwt = serializeToken; // 放置產生的Token字串
response.msg = "Done.";
}
catch (Exception ex)
{
log.LogError($"{ex.Message}\n{ex.StackTrace}");
response.isSuccess = false;
response.jwt = string.Empty;
response.msg = "產生Token 過程發生錯誤.";
}
return response;
}
// https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims#custom-claims
/// <summary>
/// 建置資訊聲明集合
/// </summary>
/// <param name="jWTCliam">Token資訊聲明內容物件</param>
/// <returns>一組收集資訊聲明集合</returns>
private List<Claim> GenCliams(JWTCliam jWTCliam)
{
List<Claim> claims = new List<Claim>();
// (audience)
// 設定Token接受者，用在驗證接收者驗證是否相符
if (jWTCliam.aud != null && jWTCliam.aud != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Aud, jWTCliam.aud));
}
// (expiration time)
// Token過期時間，一但超過這時間此Token就失效
if (jWTCliam.exp != null && jWTCliam.exp != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Exp, jWTCliam.exp));
}
// (issued at time)
// Token發行時間，用在後面檢查Token發行多久
if (jWTCliam.iat != null && jWTCliam.iat != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Iat, jWTCliam.iat));
}
// (issuer)
// 發行者資訊
if (jWTCliam.iss != null && jWTCliam.iss != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Iss, jWTCliam.iss));
}
// (JWT ID)
// Token ID，避免Token重複在被套用
if (jWTCliam.jti != null && jWTCliam.jti != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Jti, jWTCliam.jti));
}
// (not before time)
// Token有效起始時間，用來驗證Token可用時間
if (jWTCliam.nbf != null && jWTCliam.nbf != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Nbf, jWTCliam.nbf));
}
// (subject)
// Token 主題，放置該User內容
if (jWTCliam.sub != null && jWTCliam.sub != string.Empty)
{
claims.Add(new Claim(JwtRegisteredClaimNames.Sub, jWTCliam.sub));
}
return claims;
}
}
public class RunStatus
{
/// <summary>
/// Token是否有成功產生狀態
/// </summary>
/// <value>布林值</value>
public bool isSuccess { set; get; }
/// <summary>
/// Token
/// </summary>
/// <value>字串</value>
public string jwt { set; get; }
/// <summary>
/// 處理訊息
/// </summary>
/// <value>字串</value>
public string msg { set; get; }
}
}
在此服務架構中 透過介面(JWTBase)去定義有什麼功能和需要帶什麼參數，作為一個Service Base。 介面功能定義好後，將此Service Base去實作出來，完成介面定義功能內處理邏輯。
註冊服務與設置驗證方法
註冊服務
在Startup.cs內ConfigureServices進行配置
services.AddSingleton<JWTBase, JWTServices>();
透過相依性注入(Dependency Injection) 泛型結構<介面,實作類別> 可以參考使用擴充方法來註冊服務群組 https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-5.0#register-groups-of-services-with-extension-methods 關於注入的服務留存期可參考，在這是使用單一 https://docs.microsoft.com/zh-tw/dotnet/core/extensions/dependency-injection#service-lifetimes
設置驗證
在Startup.cs內進行配置，在以下兩個區塊進行
ConfigureServices
引入套件
using Microsoft.AspNetCore.Authentication.JwtBearer;
在這裡驗證邏輯流程如下
services.AddAuthentication(
JwtBearerDefaults.AuthenticationScheme
)
這裡作用為告訴app驗證方式為JWT Token驗證 有關驗證可以參考 https://docs.microsoft.com/zh-tw/aspnet/core/security/authentication/?view=aspnetcore-5.0
AddJwtBearer(options =>
{
// You need to import package as follow
// using Microsoft.IdentityModel.Tokens;
options.TokenValidationParameters = new TokenValidationParameters
{
#region 配置驗證發行者
ValidateIssuer = true, // 是否要啟用驗證發行者
ValidIssuer = Configuration.GetSection("JWTConfig").GetValue<string>("Issuer"),
#endregion
#region 配置驗證接收方
ValidateAudience = false, // 是否要啟用驗證接收者
// ValidAudience = "" // 如果不需要驗證接收者可以註解
#endregion
#region 配置驗證Token有效期間
ValidateLifetime = true, // 是否要啟用驗證有效時間
#endregion
#region 配置驗證金鑰
ValidateIssuerSigningKey = false, // 是否要啟用驗證金鑰，一般不需要去驗證，因為通常Token內只會有簽章
#endregion
#region 配置簽章驗證用金鑰
// 這裡配置是用來解Http Request內Token加密
// 如果Secret Key跟當初建立Token所使用的Secret Key不一樣的話會導致驗證失敗
IssuerSigningKey = new SymmetricSecurityKey(
Encoding.UTF8.GetBytes(
Configuration.GetSection("JWTConfig").GetValue<string>("SignKey")
)
)
#endregion
};
});
接續在services.AddAuthentication()後面，透過.來進行串接。 這裡主要用來設置Token驗證的項目設定。
Configure
加入驗證
app.UseAuthentication();
加入授權
app.UseAuthorization();
需要注意的是，這個要包在app.UseRouting()跟app.UseEndpoints中間 否則會再請求進來時，發生錯誤產生。 這個會跟Action上方Tag[Authorize]與[AllowAnonymous]有關
服務功能
產生JWT Token
GetJWT() 用來產生取得JWT Token字串。
功能所需要的參數
secretKey、issuer、expireMinutes 都會跟appsettings.json內JWTConfig配置相對應。
jWTCliam 在呼叫此功能上一端會將聲明資訊內容透過JWTCliamData Model封裝，並帶入給此功能參數。
最後會回傳一組Token字串，這組字串內容是經過加密後的字串。
測試
透過Controllers/LoginController.cs Api進行測試
模擬登入取得Token
https://localhost:5001/api/signin
對應Action --> SignIn()
關於User資訊聲明(Cliam)產生，會在此自動做一個簡單內容，使用上方JWTCliam進行資訊內容封裝Data Model，在呼叫JWT處理服務內產生JWT Token功能時，會將此封裝好Data Model帶入參數給予。
最後會回傳一組JSON
JwtToken --> 產生的JWT Token 字串。
Status --> 請求處理結果是否正常狀態，型態為一個布林值。
Msg --> 如果有錯誤發生，這裡會放置錯誤訊息。
模擬呼叫需驗證Token Api
https://localhost:5001/api/get/info
對應Action --> GetTokenInfo()
模擬一個發送請求途中，在Header內帶有驗證Token，格式如下
Authorization: Bearer + Token
Bearer跟Token之間記得要加上一個空白符號隔開
這支Api只是單純模擬需要帶有Token驗證Htpp請求，根據在Starup.cs內設置的驗證配置來進行，最後會簡單的分析讀取Token發行者(Issuer)資訊。
最後會回傳一組JSON
JwtToken --> 因為不是請求登入取得Token，所以這裡會是字串空值。
Status --> 請求處理結果是否正常狀態，型態為一個布林值。
Msg --> 如果有錯誤發生，這裡會放置錯誤訊息，反之則會是Token發行者(Issuer)資訊。
參考連結
https://blog.miniasp.com/post/2019/12/16/How-to-use-JWT-token-based-auth-in-aspnet-core-31
https://blog.poychang.net/authenticating-jwt-tokens-in-asp-net-core-webapi/
https://mgleon08.github.io/blog/2018/07/16/jwt/
https://medium.com/麥克的半路出家筆記/筆記-透過-jwt-實作驗證機制-2e64d72594f8
https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims#custom-claims
