---
# System prepended metadata

title: ASP.NET Core Web Api 實作JWT驗證筆記
tags: [ASP.NET Core]

---

---
title: ASP.NET Core Web Api 實作JWT驗證筆記
tags: ASP.NET Core
---

# `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

透過下方指令確認是否安裝無誤，正常會出現版本號
```shell=
dotnet --version
```

# 專案建置

## 建立方案檔(sln)
```shell=
dotnet new sln -n jyu.lab.jwt
```

> `-n` 為方案檔名稱

## 建立`.gitignore`
```shell=
dotnet new gitignore
```
> 這裡可以視需要再做

## 建立WebApi專案
```shell=
dotnet new webapi -n Lab_JWT
```

> `-n` 為設置專案名稱

透過下方指令將專案加入至方案內
```shell=
dotnet sln add .\Lab_JWT\Lab_JWT.csproj
```

設置信任`ASP.NET Core HTTPS` 開發憑證
```shell=
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
```shell=
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 5.0.6
```

* `NLog`
https://www.nuget.org/packages/NLog/
```shell=
dotnet add package NLog --version 4.7.10
```

* `NLog.Web.AspNetCore`
https://www.nuget.org/packages/NLog.Web.AspNetCore/4.13.0-readme-preview
```shell=
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`在裡面加入下方配置
```xml=
<ItemGroup>    
    <Content Update="nlog.config">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
 </ItemGroup>
```
> 這裡用意是在**建置**/**發佈**階段時，指定將`nlog.config`複製一份到`bin/`底下對應的各階段目錄內去。
> 如果沒設置的話在執行的時候NLog不會正常運作起來。
> 複製條件為`Always`代表無論有沒有更動內容都複製更新。

將以下內容複製到`nlog.config`
```xml=
<?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`，並引入以下套件
```csharp=
using NLog.Web;
```

在`Main`區塊將原始內容更改為以下
```csharp=
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`區塊將原始內容更改為以下
```csharp=
 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/`
```csharp=
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/`
```csharp=
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/`
```csharp=
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`進行配置
```csharp=
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
引入套件
```csharp=
using Microsoft.AspNetCore.Authentication.JwtBearer;
```

在這裡驗證邏輯流程如下
* 設置驗證方式
```csharp=
services.AddAuthentication(
    JwtBearerDefaults.AuthenticationScheme
)
```
> 這裡作用為告訴app驗證方式為JWT Token驗證
> 有關驗證可以參考
> https://docs.microsoft.com/zh-tw/aspnet/core/security/authentication/?view=aspnetcore-5.0

* 驗證項目設置
```csharp=
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
加入驗證
```csharp=
app.UseAuthentication();
```

加入授權
```csharp=
app.UseAuthorization();
```
> 需要注意的是，這個要包在`app.UseRouting()`跟`app.UseEndpoints`中間
> 否則會再請求進來時，發生錯誤產生。
> 這個會跟Action上方Tag`[Authorize]`與`[AllowAnonymous]`有關

## 服務功能

### 產生JWT Token

`GetJWT()` 用來產生取得JWT Token字串。

功能所需要的參數
* `secretKey`、`issuer`、`expireMinutes` 
都會跟`appsettings.json`內`JWTConfig`配置相對應。
* `jWTCliam`
在呼叫此功能上一端會將聲明資訊內容透過`JWTCliam`Data 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` --> 如果有錯誤發生，這裡會放置錯誤訊息。

![](https://i.imgur.com/kJj29V3.png)

## 模擬呼叫需驗證Token Api
`https://localhost:5001/api/get/info`

對應**Action** --> `GetTokenInfo()`

模擬一個發送請求途中，在**Header**內帶有驗證Token，格式如下
```json=
Authorization: Bearer + Token
```
> `Bearer`跟Token之間記得要加上一個空白符號隔開

這支Api只是單純模擬需要帶有Token驗證Htpp請求，根據在`Starup.cs`內設置的驗證配置來進行，最後會簡單的分析讀取Token發行者(Issuer)資訊。

最後會回傳一組JSON
* `JwtToken` --> 因為不是請求登入取得Token，所以這裡會是字串空值。
* `Status` --> 請求處理結果是否正常狀態，型態為一個布林值。
* `Msg` --> 如果有錯誤發生，這裡會放置錯誤訊息，反之則會是Token發行者(Issuer)資訊。

![](https://i.imgur.com/ONB42q2.png)


# 參考連結
* 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/%E9%BA%A5%E5%85%8B%E7%9A%84%E5%8D%8A%E8%B7%AF%E5%87%BA%E5%AE%B6%E7%AD%86%E8%A8%98/%E7%AD%86%E8%A8%98-%E9%80%8F%E9%81%8E-jwt-%E5%AF%A6%E4%BD%9C%E9%A9%97%E8%AD%89%E6%A9%9F%E5%88%B6-2e64d72594f8
* https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims#custom-claims



