C# on My Dev Log

ASP.NET Core JWT 驗證進階

Fri, 04 Apr 2025 15:32:58 +0800

序

原本預計 ASP.NET Core JWT 分成兩篇寫完，不過因為自己也是第一次實作，再加上不想完全照著教學的影片，過於簡單，與實務上還有一段差別，所以我加入了很多我自己在工作上的經驗跟作法，沒想到導致篇幅內容增加，只好分成第三篇，將最後需要加強與改進的部分寫在這一篇中！

本篇重點

Validation：針對進入資料庫的資料進行驗證
Unit Of Work：確保資料的一致性
Exception Handle：統一的錯誤處理機制，方便讓前端在呼叫 API 的時候可以知道系統或相關錯誤。

資料驗證

目前程式架構及資料輸入流如下

使用者從瀏覽器發送請求後，到 Controller 接收會包裝成 Dto 的物件型別，這時候需要做第一層的驗證，驗證使用者的請求，如果有問題，回傳 Http 400
較嚴格的系統可能會在 Controller 傳送 Dto 到 Service 的時候作第二層的驗證，如果這一層有問題統一丟出 Exception，屬於伺服器的錯誤回傳 Http 500

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 ┌──────┐ ┌──────────┐ ┌───────┐ ┌──────┐
 │Client│ │Controller│ │Service│ │Entity│
 └──┬───┘ └────┬─────┘ └───┬───┘ └──┬───┘
 │ │ │ │
 │Request from client│ │ │
 │──────────────────>│ │ │
 │ │ │ │
 │ │[Data Transfer Object]│ │
 │ │─────────────────────>│ │
 │ │ │ │
 │ │ │[Entity class]│
 │ │ │─────────────>│
 ┌──┴───┐ ┌────┴─────┐ ┌───┴───┐ ┌──┴───┐
 │Client│ │Controller│ │Service│ │Entity│
 └──────┘ └──────────┘ └───────┘ └──────┘

整個應用程式共有四個 API，分析如下

註冊：需要驗證註冊資料
登入：需要驗證登入資料，登入時需要產生 RefreshToken 給員工，所以還要再驗證 RefreshToken 及所屬員工資料。
登出：會從 Client 收到 AccessToken 及 RefreshToken，前者從 Header 讀取，後者從 Body 讀取，因為要將 AccessToken 及 RefreshToken 寫入黑名單，兩者都是 token，所以只要驗證 token
更新：會從 Body 收到 RefreshToken，檢查有沒有過期，確認沒有過期後由程式產生一組新的 AccessToken 及 RefreshToken，而員工可以從 RefreshToken 的關聯參考找到這個 RefreshToken 屬於哪一個員工，進而取得員工資料，所以一樣只需要驗證 Token

註冊、登入

其中註冊、登入都會驗證使用者的帳號跟密碼，所以將帳號密碼的驗證寫在一起，可以簡化程式，不用在註冊時寫一次，在登入時在寫一次同樣的驗證邏輯，而且將驗證邏輯抽離，讓 Controller 責任更專一

由於 RegisterDto 及 LoginDto 兩個類別的欄位是一樣的，我為可程式的可讀性才分成兩個，所以本質上要驗證的欄位都一樣，我要新增一個驗證員工用的 interface IEmployeeCredentialDto.cs 標示要驗證的欄位有哪些，如下

之所以加一個驗證用的介面是因為驗證的方法，參數我希望可以使用 Generic 的型別，也就是可以傳入 RegisterDto 或 LoginDto 在同一個方法，不然就要分成兩個方法，一個驗證 RegisterDto，另一個驗證 LoginDto，而且兩個方法的驗證邏輯是一樣的，重寫兩次的話會失去抽離的意義

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 員工驗證欄位介面
/// </summary>
public interface IEmployeeCredentialDto
{
 /// <summary>
 /// 員工帳號
 /// </summary>
 public string Email { get; }
 /// <summary>
 /// 員工密碼
 /// </summary>
 public string Password { get; }
}

接著讓 RegisterDto, LoginDto 實作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


using JWT_Authentication_API.Interfaces;

namespace JWT_Authentication_API.Models;

/// <summary>
/// 使用者登入的資料模型
/// </summary>
public class LoginDto : IEmployeeCredentialDto
{
 /// <summary>
 /// 使用者帳號
 /// </summary>
 public string Email { get; set; } = string.Empty;
 /// <summary>
 /// 使用者密碼（未加密）
 /// </summary>
 public string Password { get; set; } = string.Empty;
}

using JWT_Authentication_API.Interfaces;

namespace JWT_Authentication_API.Models;

/// <summary>
/// 註冊使用者的資料模型
/// </summary>
public class RegisterDto : IEmployeeCredentialDto
{
 /// <summary>
 /// 使用者帳號
 /// </summary>
 public string Email { get; set; } = string.Empty;
 /// <summary>
 /// 使用者密碼（未加密）
 /// </summary>
 public string Password { get; set; } = string.Empty;
}

CredentialHelper

接下來新增驗證用的 Helper，一樣是用 static 的形式，因為只負責登入及註冊的身份驗證，不需要跟資料庫互動如下，新增 CredentialHelper.cs 並實作驗證的邏輯，新增 IsValidEmployeeCredential 方法，因為教學的原故，我只驗證有沒有值而已，實際上還會驗證 Email 的格式，密碼的長度、複雜度…等，相關的驗證邏輯都可以新增在這裡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


using JWT_Authentication_API.Interfaces;

namespace JWT_Authentication_API.Helper;

/// <summary>
/// 身分驗證的輔助類別
/// </summary>
public static class CredentialHelper
{
 /// <summary>
 /// 驗證員工的帳號及密碼
 /// </summary>
 /// <param name="dto"> 要驗證的員工資料 </param>
 /// <typeparam name="T"> 註冊及登入的介面 </typeparam>
 /// <returns> 有沒有通過驗證 </returns>
 public static bool IsValidEmployeeCredential<T>(T dto)
 where T : IEmployeeCredentialDto
 {
 return !string.IsNullOrEmpty(dto.Email) && !string.IsNullOrEmpty(dto.Password);
 }
}

最後回到 AuthController 將有驗證的地方修改如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


#region 註冊
/// <summary>
/// 註冊 API
/// </summary>
/// <param name="registerDto"> 使用者傳送的員工註冊資料 </param>
/// <returns> 註冊結果 </returns>
[AllowAnonymous]
[HttpPost("register")]
public async Task<ActionResult> RegisterAsync(RegisterDto registerDto)
{
 // 驗證註冊資料
 if(!CredentialHelper.IsValidEmployeeCredential(registerDto))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 先查詢有沒有重複的員工資料
 var employee = await _employeeService.GetEmployeeByEmailAsync(registerDto.Email);

 // 如果沒有就註冊新員工
 var registerResult =
 employee == null &&
 await _employeeService.AddEmployeeAsync(registerDto);

 // 回傳註冊結果
 ......
}
#endregion

#region 登入
/// <summary>
/// 登入 API
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[AllowAnonymous]
[HttpPost("login")]
public async Task<ActionResult> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 if (!CredentialHelper.IsValidEmployeeCredential(loginDto))
 return BadRequest("Please provide 'Email' and 'Password'");

 .....
}
#endregion

然後可以發現，在「註冊」方法中，有使用 2 個服務的方法，分別查詢員工有沒有被註冊過，及新增員工資料，一樣在這兩個方法加入驗證

AddEmployeeAsync

開啟 EmployeeService.cs，修改 AddEmployeeAsync 方法，加入驗證的方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


/// <summary>
/// 新增員工資料
/// </summary>
/// <param name="registerDto"> 員工註冊資料 </param>
/// <returns> 註冊結果 </returns>
public async Task<bool> AddEmployeeAsync(RegisterDto registerDto)
{
 if (!CredentialHelper.IsValidEmployeeCredential(registerDto))
 throw new ValidationException("Email or password is required");

 ......
}

GetEmployeeByEmailAsync

由於這個方法只要驗證員工信箱，因此在 CredentialHelper 新增只驗證員工信箱的方法 IsValidEmail 如下，可以同步修改 IsValidEmployeeCredential

這裡只驗證有沒有值，實務上企業內部會使用員工編號或英文姓名作為員工信箱，會有相關的驗證規則

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


/// <summary>
/// 驗證員工的帳號及密碼
/// </summary>
/// <param name="dto"> 要驗證的員工資料 </param>
/// <typeparam name="T"> 註冊及登入的介面 </typeparam>
/// <returns> 有沒有通過驗證 </returns>
public static bool IsValidEmployeeCredential<T>(T dto)
 where T : IEmployeeCredentialDto
{
 // 員工信箱及密碼的驗證規則，只檢查有沒有值
 return IsValidEmail(dto.Email) && !string.IsNullOrEmpty(dto.Password);
}

/// <summary>
/// 驗證員工信箱
/// </summary>
/// <param name="email"> 要驗證的員工信箱 </param>
/// <returns> 驗證結果 </returns>
public static bool IsValidEmail(string email)
{
 // Email 的驗證規則，這裡驗證是否有 Email 的值
 return !string.IsNullOrEmpty(email);
}

接著在 GetEmployeeByEmailAsync 方法加入 Email 驗證的方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


/// <summary>
/// 依帳號取得員工資料
/// </summary>
/// <param name="email"> 登入信箱/註冊信箱 </param>
/// <returns> 員工資料 或 null </returns>
public async Task<EmployeeDto?> GetEmployeeByEmailAsync(string email)
{
 if(!CredentialHelper.IsValidEmail(email))
 throw new ArgumentException("Email is required!");

 ......
}

AddRefreshTokenAsync

另外在登入方法有使用 新增 RefreshToken 的方法，一樣要加入驗證

由最一開始的分析可以知道，除了登入，另外登出及更新方法，都有驗證 RefreshToken 的相關邏輯 這邊為了統一驗證物件及簡化程式，要將這這方法重構，將原本方法的參數改為 RefreshTokenDto，在 Models 新增 RefreshTokenDto.cs 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


namespace JWT_Authentication_API.Models;

/// <summary>
/// RefreshToken 資料物件
/// </summary>
public class RefreshTokenDto
{
 /// <summary>
 /// 員工識別
 /// </summary>
 public Guid EmployeeId { get; set; } = Guid.Empty;
 /// <summary>
 /// RefreshToken
 /// </summary>
 public string RefreshToken { get; set; } = string.Empty;
}

接著開啟 ITokenService.cs 及 TokenService.cs，修改 AddRefreshTokenAsync 方法接收參數為 RefreshTokenDto 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 ......

 /// <summary>
 /// 新增 RefreshToken
 /// </summary>
 /// <param name="refreshToken"> 要新增的 RefreshToken </param>
 /// <returns> 新增的結果 </returns>
 Task<bool> AddRefreshTokenAsync(RefreshTokenDto refreshToken);

 ......
}

using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 /// <summary>
 /// 資料庫物件
 /// </summary>
 private readonly AppDbContext _appDb = context;

 ......

 #region Add Refresh Token
 /// <summary>
 /// 新增 RefreshToken
 /// </summary>
 /// <param name="refreshTokenDto"> 要新增的 RefreshToken </param>
 /// <returns> 新增的結果 </returns>
 public async Task<bool> AddRefreshTokenAsync(RefreshTokenDto refreshTokenDto)
 {
 ......
 }
 #endregion
}

再開啟 TokenHelper.cs 新增 IsValidRefreshToken 方法，用來驗證 RefreshTokenDto 物件如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


using System.Security.Cryptography;
using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Helper;

/// <summary>
/// Token 輔助類別，宣告為 static
/// 主要負責產生及驗證
/// 不需要 DI 可以直接使用
/// </summary>
public static class TokenHelper
{
 ......

 /// <summary>
 /// 驗證 RefreshTokenDto
 /// </summary>
 /// <param name="refreshTokenDto"> 要驗證的 RefreshTokenDto </param>
 /// <returns> 驗證結果 </returns>
 public static bool IsValidRefreshToken(RefreshTokenDto refreshTokenDto)
 {
 return !string.IsNullOrEmpty(refreshTokenDto.RefreshToken) &&
 !refreshTokenDto.EmployeeId.Equals(Guid.Empty);
 }

 ....
}

回到 TokenService.cs 在 AddRefreshTokenAsync 加入上面的驗證方法並重構 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


#region Add Refresh Token
/// <summary>
/// 新增 RefreshToken
/// </summary>
/// <param name="refreshTokenDto"> 要新增的 RefreshToken </param>
/// <returns> 新增的結果 </returns>
public async Task<bool> AddRefreshTokenAsync(RefreshTokenDto refreshTokenDto)
{
 // 驗證要新增的 RefreshToken 物件
 if(!TokenHelper.IsValidRefreshToken(refreshTokenDto))
 throw new ArgumentException(
 $"'{nameof(refreshTokenDto.RefreshToken)}' and '{nameof(refreshTokenDto.EmployeeId)}' is required!");
 // 新增 RefreshToken
 await _appDb.RefreshTokens.AddAsync(new RefreshToken
 {
 Token = refreshTokenDto.RefreshToken,
 // 配合週休二日，設定 5 天後到期
 ExpiresAt = DateTimeOffset.Now.AddDays(5),
 EmployeeId = refreshTokenDto.EmployeeId
 });
 // 新增結果
 return await _appDb.SaveChangesAsync() > 0;
}

最後回到 AuthController 登入方法，修改 AddRefreshTokenAsync 傳入的參數

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#region 登入
/// <summary>
/// 登入 API
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[AllowAnonymous]
[HttpPost("login")]
public async Task<ActionResult> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 if (!CredentialHelper.IsValidEmployeeCredential(loginDto))
 return BadRequest("Please provide 'Email' and 'Password'");

 ......

 var result = await _tokenService.AddRefreshTokenAsync(new RefreshTokenDto
 {
 EmployeeId = employee.Id,
 RefreshToken = refreshToken,
 });
 if(!result) return StatusCode(StatusCodes.Status500InternalServerError);

 ......
}
#endregion

登出

由一開始的分析可以知道登出要驗證 Token（AccessToken 加入黑名單並刪除 RefreshToken），可以利用先前就建立好的 TokenHelper，新增一個 HasToken 方法，接收一個 token 做為要驗證的 token 參數

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#region Validation
/// <summary>
/// 驗證 JWT
/// </summary>
/// <param name="token"> JWT </param>
/// <returns> 驗證結果 </returns>
public static bool HasToken(string token)
{
 return !string.IsNullOrEmpty(token);
}
#endregion

回到 AuthController 對登出方法做重構，將參數改成跟登入一樣 RefreshTokenDto，然後加入上面的驗證方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#region 登出
/// <summary>
/// 登出 API
/// </summary>
/// <param name="refreshTokenDto"> 要刪除的 RefreshToken </param>
/// <returns> 登出結果 </returns>
[Authorize]
[HttpPost("logout")]
public async Task<IActionResult> LogoutAsync(RefreshTokenDto refreshTokenDto)
{
 // 從 header 讀取 JWT(AccessToken) 並進行驗證
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer ", string.Empty, StringComparison.OrdinalIgnoreCase);

 if (!TokenHelper.HasToken(token))
 return BadRequest("'AccessToken' is required!");
 ......
}
#endregion

但這樣的作法其實是比較嚴格的，因為如果沒有提供 Bearer Token 在 [Authorize] 的時候就會被擋下來了

AddTokenToTokenBlackListAsync

登出的時候會將 token 加入黑名單，這裡也加入驗證

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


#region Add into BlackList
/// <summary>
/// 新增 Token 到黑名單
/// </summary>
/// <param name="token"> 要新增的 Token </param>
/// <returns> 新增結果 </returns>
/// <exception cref="ArgumentException"> token 是空值的時候 </exception>
public async Task<bool> AddTokenToTokenBlackListAsync(string token)
{
 // 檢查有沒有提供 token
 if(!TokenHelper.HasToken(token))
 throw new ArgumentException("'Access token' is required!");
 // 新增到黑名單
 await _appDb.TokenBlackLists.AddAsync(new TokenBlackList { Token = token });
 // 新增結果
 return await _appDb.SaveChangesAsync() > 0;
}
#endregion

RemoveRefreshTokenAsync

最後登出會刪除 RefreshToken，同步進行重構，開啟 ITokenService.cs 及 TokenService.cs，修改 RemoveRefreshTokenAsync 方法，將傳入的參數改成 RefreshTokenDto，並加入 Token 的驗證及重構 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 ......

 /// <summary>
 /// 刪除 RefreshToken
 /// </summary>
 /// <param name="refreshTokenDto"> 要刪除的 RefreshToken </param>
 /// <returns> 刪除結果 </returns>
 Task<bool> RemoveRefreshTokenAsync(RefreshTokenDto refreshTokenDto);
}

using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 ......

 #region Remove Refresh Token
 /// <summary>
 /// 刪除 RefreshToken
 /// </summary>
 /// <param name="refreshTokenDto"> 要刪除的 RefreshToken </param>
 /// <returns> 刪除結果 </returns>
 /// <exception cref="KeyNotFoundException"> 找不到要刪除的 RefreshToken </exception>
 /// <exception cref="InvalidOperationException"> 舊的 RefreshToken 新增黑名單失敗 </exception>
 public async Task<bool> RemoveRefreshTokenAsync(RefreshTokenDto refreshTokenDto)
 {
 if (!TokenHelper.HasToken(refreshTokenDto.RefreshToken))
 throw new ArgumentException($"'{nameof(refreshTokenDto.RefreshToken)}' is required!");

 // 先找出要刪除的 refreshToken
 var refreshToken = await _appDb.RefreshTokens
 .FirstOrDefaultAsync(rt => rt.Token == refreshTokenDto.RefreshToken);

 // 找不到要刪除的 RefreshToken
 if (refreshToken is null)
 throw new KeyNotFoundException($"{nameof(refreshTokenDto.RefreshToken)} not found!");

 // 將要刪除的 RefreshToken 新增到黑名單
 var addResult = await AddTokenToTokenBlackListAsync(refreshToken.Token);
 if(!addResult) throw new InvalidOperationException
 ("Failed to add refresh token into black list!");

 // 再將舊的 RefreshToken 刪除
 _appDb.RefreshTokens.Remove(refreshToken);

 return await _appDb.SaveChangesAsync() > 0;
 }
 #endregion
}

IsTokenRevokedAsync

最後要幫登出加上確認 Token 有沒有在黑名單，避免使用者傳送已經用過的 Token，開啟 ITokenService.cs 及 TokenService.cs 加入確認 Token 在黑名單的方法 IsTokenRevokedAsync

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 ......

 /// <summary>
 /// 檢查 Token 有沒有被使用過
 /// </summary>
 /// <param name="token"> 要檢查的 Token </param>
 /// <returns> 檢查結果 </returns>
 Task<bool> IsTokenRevokedAsync(string token);

 ......
}

using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 ......

 #region Check Black list
 /// <summary>
 /// Token 是否被使用過
 /// </summary>
 /// <param name="token"> 要檢查的 Token </param>
 /// <returns> 結果 </returns>
 public async Task<bool> IsTokenRevokedAsync(string token)
 {
 return await _appDb.TokenBlackLists.AsNoTracking()
 .AnyAsync(l => l.Token == token);
 }
 #endregion

 ......
}

最後在 LogoutAsync 方法加入驗證邏輯如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


#region 登出
/// <summary>
/// 登出 API
/// </summary>
/// <param name="refreshTokenDto"> 要刪除的 RefreshToken </param>
/// <returns> 登出結果 </returns>
[Authorize]
[HttpPost("logout")]
public async Task<IActionResult> LogoutAsync(RefreshTokenDto refreshTokenDto)
{
 // 從 header 讀取 JWT(AccessToken) 並進行驗證
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer ", string.Empty, StringComparison.OrdinalIgnoreCase);

 ......

 // 檢查 AccessToken 有沒有被使用過
 if(await _tokenService.IsTokenRevokedAsync(token))
 return Unauthorized($"'{token}' is revoked!");

 ......
}
#endregion

更新

最後一個是更新 RefreshToken 的方法，從分析得知一樣只要驗證 Token，所以要將這個方法進行重構，將這個方法接收的參數改成 RefreshTokenDto 並加入驗證方法 TokenHelper.HasToken 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#region Refresh
/// <summary>
/// 驗證、更新 RefreshToken
/// </summary>
/// <param name="refreshTokenDto"> 要驗證的 RefreshToken </param>
/// <returns> 新的 RefreshToken 或 AccessToken </returns>
[HttpPost("refresh-token")]
public async Task<ActionResult> RefreshTokenAsync([FromBody] RefreshTokenDto refreshTokenDto)
{
 // 驗證 RefreshToken
 if(!TokenHelper.HasToken(refreshTokenDto.RefreshToken))
 return BadRequest($"'{nameof(refreshTokenDto.RefreshToken)}' is required!");
 ......
}

接著需要將原本接收參數的方法都作修改

IsRefreshTokenExpiredAsync

首先是檢查 RefreshToken 有沒過期的方法，開啟 ITokenService.cs 及 TokenService.cs，將接收參數改成 RefreshTokenDto，再將 IsRefreshTokenExpiredAsync 方法加入驗證重構如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 ......

 /// <summary>
 /// 檢查 RefreshToken 是否過期
 /// </summary>
 /// <param name="refreshToken"> 要檢查的 RefreshToken 物件 </param>
 /// <returns> 檢查結果 </returns>
 Task<bool> IsRefreshTokenExpiredAsync(RefreshTokenDto refreshToken);

 ......
}

using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 ......

 #region Validate RefreshToken
 /// <summary>
 /// 檢查 RefreshToken 是否過期
 /// </summary>
 /// <param name="refreshTokenDto"> 要檢查的 RefreshToken </param>
 /// <returns> 檢查結果 </returns>
 /// <exception cref="KeyNotFoundException"> 找不到要檢查的 RefreshToken </exception>
 public async Task<bool> IsRefreshTokenExpiredAsync(RefreshTokenDto refreshTokenDto)
 {
 // 驗證 RefreshToken
 if(!TokenHelper.HasToken(refreshTokenDto.RefreshToken))
 throw new ArgumentException($"'{nameof(refreshTokenDto.RefreshToken)}' is required!");

 // 取得要檢查的 RefreshToken
 var refreshToken = await _appDb.RefreshTokens.AsNoTracking()
 .FirstOrDefaultAsync(rt => rt.Token == refreshTokenDto.RefreshToken);

 // 找不到要檢查的 RefreshToken
 if (refreshToken is null)
 throw new KeyNotFoundException($"'{refreshTokenDto.RefreshToken}' not found!");

 // 回傳是否過期
 return DateTimeOffset.UtcNow > refreshToken.ExpiresAt;
 }
 #endregion

 ......
}

回到 AuthController 的更新方法 RefreshTokenAsync 中，將檢查過期的程式修改如下

1
2
3


// 驗認 RefreshToken 是否過期了
if(await _tokenService.IsRefreshTokenExpiredAsync(refreshTokenDto))
 return BadRequest($"'{nameof(refreshTokenDto.RefreshToken)}' has expired!");

UpdateRefreshTokenAsync

修改更新 RefreshToken 的方法，開啟 ITokenService.cs 及 TokenService.cs，將 UpdateRefreshTokenAsync 方法接收參數改成 RefreshTokenDto，回傳值改為 RefreshTokenDto?

接著修改 UpdateRefreshTokenAsync 的實作並加入驗證方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81



/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 ......

 /// <summary>
 /// 更新 RefreshToken
 /// </summary>
 /// <param name="refreshTokenDto"> 要更新的 RefreshToken </param>
 /// <returns> 更新後的 RefreshToken </returns>
 Task<RefreshTokenDto?> UpdateRefreshTokenAsync(RefreshTokenDto refreshTokenDto);

 ......
}

using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{

 ......

 #region Update Refresh Token
 /// <summary>
 /// 更新 RefreshToken, 將舊的 Token 寫入黑名單
 /// </summary>
 /// <param name="refreshTokenDto"> 要更新的 RefreshToken </param>
 /// <returns> 更新後的 RefreshToken </returns>
 /// <exception cref="KeyNotFoundException"> 找不到要更新的 RefreshToken </exception>
 /// <exception cref="InvalidOperationException"> 新增舊的 RefreshToken 黑名單失敗 </exception>
 public async Task<RefreshTokenDto?> UpdateRefreshTokenAsync(RefreshTokenDto refreshTokenDto)
 {
 // 驗證更新前的 RefreshToken
 if(!TokenHelper.HasToken(refreshTokenDto.RefreshToken))
 throw new ArgumentException($"'{nameof(refreshTokenDto.RefreshToken)}' is required!");

 // 先找出要更新的 refreshToken
 var refreshToken = await _appDb.RefreshTokens.FirstOrDefaultAsync(rt
 => rt.Token == refreshTokenDto.RefreshToken);

 // 如果找不到要刪除的 RefreshToken
 if (refreshToken is null) throw new KeyNotFoundException
 ($"'{nameof(refreshTokenDto.RefreshToken)}' not found!");

 // 將舊的 RefreshToken 新增到黑名單
 var addResult = await AddTokenToTokenBlackListAsync(refreshToken.Token);
 if(!addResult) throw new InvalidOperationException
 ($"Failed to add '{nameof(refreshTokenDto.RefreshToken)}' into black list!");

 // 更新 RefreshToken
 var newToken = TokenHelper.GenerateRefreshToken();
 refreshToken.Token = newToken;
 var result = await _appDb.SaveChangesAsync();

 // 更新失敗
 if (result != 1) throw new Exception("Refresh token update failed!");
 // 更新成功
 return await _appDb.RefreshTokens.AsNoTracking()
 .Select(rt => new RefreshTokenDto
 {
 EmployeeId = rt.EmployeeId,
 RefreshToken = rt.Token,
 })
 .FirstOrDefaultAsync(rt => rt.RefreshToken == newToken);
 }
 #endregion

 ......
}

回到 AuthController 的更新方法 RefreshTokenAsync，因為將產生新的 RefreshToken 交給了 Service 去完成，所以將原本產生新的 RefreshToken 刪除並修改如下

1
2
3
4
5
6
7
8


// 更新 RefreshToken，並取得更新後的 RefreshToken
var result = await _tokenService.UpdateRefreshTokenAsync(refreshTokenDto);
// 更新成功但沒有回傳更新後的結果屬於伺服器錯誤
if (result is null) return StatusCode(StatusCodes.Status500InternalServerError);

// 找出目前使用的員工
var employee = await _employeeService.GetEmployeeByIdAsync(result.EmployeeId);
if (employee is null) return NotFound("Employee not found!");

更新跟登出一樣，需要再加上確認 Token 有沒有過期的驗證

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


#region Refresh
/// <summary>
/// 驗證、更新 RefreshToken
/// </summary>
/// <param name="refreshTokenDto"> 要驗證的 RefreshToken </param>
/// <returns> 新的 RefreshToken 或 AccessToken </returns>
[HttpPost("refresh-token")]
public async Task<ActionResult> RefreshTokenAsync([FromBody] RefreshTokenDto refreshTokenDto)
{
 ......

 // 確認 Token 有沒有被使用過
 if(await _tokenService.IsTokenRevokedAsync(refreshTokenDto.RefreshToken))
 return Unauthorized($"'{refreshTokenDto.RefreshToken}' is revoked!");

 ......
}

基本上驗證的部分就重構完了，接下來可以使用 Postman 來測試，測試可以參考前一篇，在最下方的相關文章可以找到，這裡不再多描述了

資料驗證測試

特別提一下資料驗證的測試方法，因為登出、更新方法的接收參數變了，接收一個 RefreshTokenDto 物件，參考 AddRefreshTokenAsync，有一個 EmployeeId, RefreshToken，而 EmployeeId 提供預設值 Guid.Empty，所以在測試的時候可以只傳送 RefreshToken 就可以了

1
2
3


{
 "refreshToken": "your-refresh-token"
}

UnitOfWork

在測試中有一種情況，在登出的時候，用已使用過的 RefreshToken 去登出的話，會出現「找不到 RefreshToken」的 Http 500，結果看起來沒有錯，不過 再次使用正確的 RefreshToken 登出的話，會出現「這個 AccessToken 出現在黑名單」 中，這是因為在登出方法中，先將 AccessToken 寫入黑名單中，再將 RefreshToken 寫入黑名單如下，只要其中一個操作失敗了，兩個操作都要回到一開始的狀態。

AccessToken 寫入黑名操作順利完成，不過 RefreshToken 寫入黑名單，因為找不到使用中的 RefreshToken 而失敗，理論上來說這一整個操作應該視為失敗，要將原本寫入黑名單的 AccessToken 移除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


#region 登出
/// <summary>
/// 登出 API
/// </summary>
/// <param name="refreshTokenDto"> 要刪除的 RefreshToken </param>
/// <returns> 登出結果 </returns>
[Authorize]
[HttpPost("logout")]
public async Task<IActionResult> LogoutAsync(RefreshTokenDto refreshTokenDto)
{
 // 從 header 讀取 JWT(AccessToken) 並進行驗證
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer ", string.Empty, StringComparison.OrdinalIgnoreCase);

 if (!TokenHelper.HasToken(token)) return BadRequest("'AccessToken' is required!");

 // 檢查 AccessToken 有沒有被使用過
 if(await _tokenService.IsTokenRevokedAsync(token)) return Unauthorized($"'{token}' is revoked!");

 // 將 JWT 加入黑名單
 var result = await _tokenService.AddTokenToTokenBlackListAsync(token);
 if (!result) return BadRequest("Logout failed!");

 // 將 refreshToken 刪除
 result = await _tokenService.RemoveRefreshTokenAsync(refreshTokenDto);
 if (!result) return BadRequest("Logout failed!");

 return Ok("Logout successfully!");
}
#endregion

而 UnitOfWork 就是為了解決這樣的問題而出現的，中文應該是「工作單元」，每一個工作單元包含了所有完成這個方法所需要的資料操作，並且在所有操作完成後統一存儲

ASP.NET Core 實作 JWT Refresh Token

Sun, 23 Mar 2025 13:26:42 +0800

前情提要

前一篇已經完成了註冊、登入、登出，基本功能，不過仍有一些不足的地方，原本是要紀錄在前一篇，但怕篇幅過長，所以將「登出」及「驗證」的部分，寫在本篇並跟前篇做一個銜接，並讓整個 API 機制更加完整。

本篇重點

Authorization：前一篇沒有說明到的是 Token 的驗證，雖然有設定有效期限，實際驗證邏輯是需要寫在程式裡面的
基於角色的驗證：角色授權，通常驗證與授權是一起的，本篇會帶入一點角色驗證的實作
JWT Refresh Token：JWT Refresh Token 機制讓使用者在短期內不需要頻繁登入，通過使用 Refresh Token 可以提供了更好的用戶體驗和安全性。

Authorize

先回到登出方法，加上一個 [Authorize]，代表需要經過驗證的使用者才可以使用這個功能，而登出確實是要登入的使用者才可以執行的動作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


/// <summary>
/// 登出
/// </summary>
/// <returns> 登出結果 </returns>
[Authorize]
[HttpPost("logout")]
public async Task<IActionResult> LogoutAsync()
{
 // 從 header 讀取 JWT
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer", string.Empty, StringComparison.OrdinalIgnoreCase)
 .Trim();
 if (string.IsNullOrEmpty(token))
 return BadRequest("Not token provided!");

 // 將 JWT 加入黑名單
 var result = await _tokenService.AddTokenToTokenBlackListAsync(token);
 if (!result) return BadRequest("Logout failed!");

 return Ok("Logout successfully!");
}
#endregion

再使用 Postman Send 登入的請求取得一個合法的 JWT，接著使用剛剛取得的 JWT Send 一個登出請求，會發現出現了 Exception

System.InvalidOperationException: No authenticationScheme was specified, and there was no DefaultChallengeScheme found. The default schemes can be set using either AddAuthentication(string defaultScheme) or AddAuthentication(Action<AuthenticationOptions> configureOptions).

這是因為當啟用了 [Authorize] 告訴應用程式 LogoutAsync 這個方法是需要驗證過才可以呼叫，但應用程式卻沒有指定要使用什麼驗證機制
常見了驗證機制有

Session 驗證
Cookie 驗證
Token 驗證（JWT 屬於這一類）

AddAuthentication

所以要回到 Program.cs 加入驗證方案的設定，透過 AddAuthentication 方法新增驗證方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


#region Authentication Service
builder.Services
 // 啟用 JWT 驗證
 .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 // Jwt 驗證選項
 .AddJwtBearer(options =>
 {
 // 不使用 Dependency Injection 方式讀取設定檔
 var jwtOptions = builder.Configuration.GetSection(nameof(JwtOptions)).Get<JwtOptions>()!;

 // 回應 JWT 詳細錯誤訊息，方便 Debug，所以只有在非正式環境開啟
 options.IncludeErrorDetails = builder.Environment.IsDevelopment();
 // 要加入這個設定，不然 Sub 會變成 ClaimTypes.NameIdentifier
 options.MapInboundClaims = false;
 // JWT 驗證規則
 options.TokenValidationParameters = new TokenValidationParameters
 {
 // 驗證發行單位
 ValidateIssuer = true,
 ValidIssuer = jwtOptions.Issuer,

 // 不驗證接收單位，不需要瞼證要改成 false, 原始預設是 true
 ValidateAudience = false,

 // 驗證有效期限
 ValidateLifetime = true,

 // 驗證金鑰
 ValidateIssuerSigningKey = true,
 IssuerSigningKey = new SymmetricSecurityKey(
 Encoding.UTF8.GetBytes(jwtOptions.SecretKey))
 };
 });
#endregion

程式碼詳解如下

AddAuthentication：設定驗證的方法，參數是驗證方法的名稱，如果去 JwtBearerDefaults 的原始碼查看，會發現他只是一個字串 “Bearer”，也就是說你也可以寫成 AddAuthentication("Bearer") 效果是一樣的，不過有經驗的工程師以及官方都不會推薦使用 Hard code 的方式來寫，其中一個缺點是程式碼會變得很沒彈性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


AddAuthentication(JwtBearerDefaults.AuthenticationScheme);

// JwtBearerDefaults 原始碼
namespace Microsoft.AspNetCore.Authentication.JwtBearer
{
 /// <summary>
 /// Default values used by <see cref="T:Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerHandler" /> for JWT bearer authentication.
 /// </summary>
 public static class JwtBearerDefaults
 {
 /// <summary>
 /// Default value for AuthenticationScheme property in the <see cref="T:Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions" />.
 /// </summary>
 public const string AuthenticationScheme = "Bearer";
 }
}

AddJwtBearer：設定 JWT 驗證的細節，參數是一個函數，這個函數就是執行設定的 function，指定了驗證方案後，就要針對驗證細節設定
在這個函數一開始先取得了 JwtOptions 的設定值

1
2


// 不使用 Dependency Injection 方式讀取設定檔
var jwtOptions = builder.Configuration.GetSection(nameof(JwtOptions)).Get<JwtOptions>()!;

builder.Configuration 會取得 appsettings.json 設定檔

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*",
 "JwtOptions": {
 "Expiry": 5,
 "Issuer": "JWT-Authentication-API",
 "SecretKey": "This-is-secret-key-for-JWT-Authentication"
 }
}

GetSection：取得設定檔某個設定值的內容，參數是設定值的 Key，nameof 會將 JwtOptions 轉成字串，也就是說這個方法會跟 GetSection("JwtOptions") 是一樣的，並且會取得下面的設定內容

1
2
3
4
5


"JwtOptions": {
 "Expiry": 5,
 "Issuer": "JWT-Authentication-API",
 "SecretKey": "This-is-secret-key-for-JWT-Authentication"
}

Get<T>：會將上一個方法取得的設定轉成 T 類別，也就是上一篇完成的 JwtOptions.cs 相當於將上一個方法取得的設定執行下面的程式，但要記得類別欄位大小寫要一致，不然有些值會無法正確轉換

1
2
3
4
5
6


var jwtOptions = new JwtOptions
{
 Expiry = 5,
 Issuer = "JWT-Authentication-API",
 SecretKey = "This-is-secret-key-for-JWT-Authentication"
};

options.IncludeErrorDetails：詳細錯誤訊息顯示，大部分網站會將詳細錯誤訊息紀錄在資料庫或者 log 的檔案，所以正式產品一般不太會開啟這個設定，只會在測試或開發環境開啟

builder.Environment：會取得現在的環境
IsDevelopment：現在是在開發環境的 bool，如果是開發環境就 true

合起來就是如果是開發環境就開啟詳細 JWT 詳細錯誤訊息顯示

1

options.IncludeErrorDetails = builder.Environment.IsDevelopment();

options.MapInboundClaims：是否將 JWT token 中的 claims 映射到標準的 claim 名稱，這裡調整成 false，不然 Jwt 的 JwtRegisteredClaimNames.Sub 會被轉換成 ClaimTypes.NameIdentifier，後續 ActionFilter 實作 要處理。
options.TokenValidationParameters：設定驗證規則

我只驗證三個

Issuer：發行單位，確定是這個應用程式發出去的
ValidateLifetime：是否過期
IssuerSigningKey：加密金鑰，設定方法跟 JwtHelper.cs 中一樣，參考 產生 JWT，從這邊也可以看出 JWT 是對稱加密，加解密使用同一把 Key

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


options.TokenValidationParameters = new TokenValidationParameters
{
 #region 驗證發行單位
 // 是否驗證發行單位
 ValidateIssuer = true,
 // 正確的發行單位值
 ValidIssuer = jwtOptions.Issuer,
 #endregion

 #region 驗證有效期限
 // 是否驗證有效期限
 ValidateLifetime = true,
 #endregion

 #region 驗證加密金鑰
 // 是否驗證加密金鑰
 ValidateIssuerSigningKey = true,
 // 正確的加密金鑰
 IssuerSigningKey = new SymmetricSecurityKey(
 Encoding.UTF8.GetBytes(jwtOptions.SecretKey))
 #endregion
}

驗證細節都設定好了後，最後在 Program.cs 中加入啟用驗證機制，其中呼叫順序很重要，一定要先呼叫 UseAuthentication 在呼叫 UseAuthorization

Authentication：驗證你是誰
Authorization：知道你是誰後，驗證你有沒有權限做這件事

以整個應用場景延續 產生 JWT，如果有出國經驗，可以想像成，你拿著 護照(Claims) 去日本(Login)，入境時海關會確認你的身份(臺灣人，姓名 - Validate)，如果沒有問題就會放你入境(Authorization)，並給你入境許可(JWT)，因為臺灣免簽入境可以待 90 天(JWT.Exp)，成功入境後，可以去東京迪士尼、大板環球……

前一陣子日本銀山溫泉因為遊客過多，所以有實施管制措施，如果沒有入住當地的溫泉旅館或沒有入場券的遊客，會被禁止進入(Authorization)

1
2
3
4


// 啟用驗證機制
app.UseAuthentication().UseAuthorization();
// 在 app.Run 之前啟用驗證
app.Run();

好了就可以來測試驗證了，先用 Postman 登入取得合法的 Toke，可以看到期限是 5 分鐘後到期

等過了時間再登出，會發現出現了 Http 401 的回應，就是驗證沒過

這樣驗證功能就完成了

Authorize 回顧

在驗證的方法上加上 [Authorize]
AddAuthentication：設定驗證方案
JWT Audience：接收單位預設是會驗證的，不要驗證要設定 false
在 app.Run() 之前啟用驗證及授權 UseAuthentication, UseAuthorization，驗證一定在授權之前呼叫

Authorization

字面上的意思是授權，就是給與某一個使用者權限，有些會公司會使用 角色授權摸式，也就是某些角色可以使用某些特定的功能，有些會也使用 讀寫模式，某些功能只能讀，某些功能可以讀寫，也有可能是兩者結合一起，本篇會實作基於角色的授權模式

為了增加角色，在專案目錄下新增一個 Enums 目錄，並新增一個 UserRole.cs 的類別，加入使用者角色設定如下

1
2
3


JWT_Authentication_API
 └─Enums
 └─UserRole.cs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using System.ComponentModel;

namespace JWT_Authentication_API.Enums;

/// <summary>
/// 使用者角色
/// </summary>
public enum UserRole
{
 [Description("實習生")]
 Intern,
 [Description("人資助理")]
 HrAssistant,
 [Description("人資主管")]
 HrHead
}

為了簡化教學，只設定這三個角色，並直接利用前一篇建立好了 EmployeeService 作為員工資料存取，接著開啟 Entities/Employee.cs，加入使用者角色欄位(int)，同樣為了簡化教學，只在 Employee 加入設定，通常會設計一個角色資料模型，並設定員工與角色的關聯，不過資料庫設計非本篇主題，就不多說明了

不過要特別說明的是

為什麼設成整數型別？是因為 Enum 可以轉換成 int，處理起來比較方便，可以參考 C# Enum
為什麼要多一個 Enum？我個人的看法是為了增加了程式可讀性，可能還有其他的原因，另外這種固定的設定項目，滿常會用 Enum 來實作的

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace JWT_Authentication_API.Entities;
/// <summary>
/// 員工資料模型
/// </summary>
public class Employee
{
 /// <summary>
 /// 員工資料識別（PK）
 /// </summary>
 [Key]
 // 告訴資料庫這是自動產值的欄位，讓資料庫自行產生 key 值
 // 這樣程式就不用處理了
 [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
 public Guid Id { get; set; }

 /// <summary>
 /// 員工信箱：必要欄位
 /// </summary>
 [Required, MaxLength(256)]
 public string Email { get; set; } = string.Empty;

 /// <summary>
 /// 密碼：必要欄位，且是加密過的值
 /// </summary>
 [Required, MaxLength(256)]
 public string PasswordHash { get; set; } = string.Empty;

 /// <summary>
 /// 使用者角色
 /// </summary>
 public int UserRole { get; set; }

 /// <summary>
 /// 員工資料建立的時間，預設值是建立的當下
 /// </summary>
 public DateTimeOffset CreatedOn { get; set; } = DateTimeOffset.UtcNow;

 /// <summary>
 /// 員工資料修改的間，預設值是修改的當下
 /// </summary>
 public DateTimeOffset? ModifiedOn { get; set; } = DateTimeOffset.UtcNow;
}

修改完成後記得使用 Rider 提供的工具，新增 Migration，並 Update Database，可以參考前篇 新增 Migration，連回資料庫確認更新結果，如果有看到多了一個 UserRole 的欄位，就是成功了

接下來將原本的測試註冊時的 peter 改成人資主管 HrHead(2)，Enum 類別的成員，如果沒有特別設定整數值的話，預設是從 0 開始，也就是說由上往下第一個成員是 0，第一個成員是 1，依此類推

這邊我直接使用 SQL 改，在資料庫右鍵 → New → Query Console，會出現 SQL 的查詢編輯器，輸入下面的更新語法

1
2
3
4
5
6


-- 因為我目前只有一個 peter@gmail.com 的帳號，
-- 所以也可以不用 WHERE 條件，不過如果你在測試時有註冊多筆帳號
-- 可能要指定 Email 或 Id 作為條件判斷欄位
UPDATE Employees
SET UserRole = 2
WHERE Email = 'peter@gmail.com'

更新完成後，將更新的語法清除，再輸入下面的語法確認更新結果

1
2
3


SELECT Id, Email, UserRole
FROM Employees
WHERE Email = 'peter@gmail.com'

確認 peter 的角色是不是 2（人資主管）

新增角色資料

接著為了測試角色驗證，我們再新增兩個使用者，不過我就不使用 Auth/register 方法註冊了，因為還要設定指定的使用者角色，就要重新設定 RegisterDto，有興趣可以自己研究，這裡一樣直接使用 SQL 新增使用者資料，為了方便測試，我直接將兩人的密碼設成跟 peter 一樣 parker 的加密值

當然你也可以使用 Auth/register 註冊兩個使用者後，再用上面的更新語法更新它們各自的角色，另外我所使用的是 SQL Server，某些語法能有些不同，可以自己查詢所使用的資料庫對應的 SQL

Adam：人資助理(1)
Heine：實習生(0)

1
2
3
4


INSERT INTO Employees
Values(Id, Email, PasswordHash, UserRole, CreateOn)
('3bf378ee-c168-459b-f067-08dd664a4725', 'Adam@gmail.com', 'AQAAAAIAAYagAAAAEGg06rTvDW9YMxQ9dHKfU+N97g7OnbxDQmVkMAqYmQtYFXC36mQkXY6fxO/J5ngQFg==', 1, GETDATE()),
('23476149-9d29-42fe-85df-27e3e254bd76', 'Heine@gmail.com', 'AQAAAAIAAYagAAAAEGg06rTvDW9YMxQ9dHKfU+N97g7OnbxDQmVkMAqYmQtYFXC36mQkXY6fxO/J5ngQFg==', 0, GETDATE())

新增完成後，用下面的語法確認新增結果

1
2
3


SELECT Email, UserRole
FROM Employees
ORDER BY UserRole DESC

配合角色驗證調整項目

角色設定完成後，要再 AuthController 加入最後的設定，在 RegisterAsync 跟 LoginAsync 方法加入 [AllowAnonymous] 表示登入跟註冊是不需要驗證的，任何使用者都可以使用這兩個方法，

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


/// <summary>
/// 登入 API
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[AllowAnonymous]
[HttpPost("login")]
public async Task<ActionResult> LoginAsync(LoginDto loginDto)
{
 ......
}

/// <summary>
/// 註冊 API
/// </summary>
/// <param name="registerDto"> 使用者傳送的員工註冊資料 </param>
/// <returns> 註冊結果 </returns>
[AllowAnonymous]
[HttpPost("register")]
public async Task<ActionResult> RegisterAsync(RegisterDto registerDto)
{
 ......
}

為了取得使用者角色，需要在下面幾個地方調整

EmployeeDto

再 Model 目錄新增一個 EmployeeDto.cs，紀錄員工與角色的資訊，角色預設為 -1，因為在 UserRole.cs 中定義的最低數值是 Intern(0)，所以為表示沒有角色給 -1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


namespace JWT_Authentication_API.Models;

/// <summary>
/// 員工角色資料
/// </summary>
public class EmployeeDto
{
 /// <summary>
 /// 員工帳號
 /// </summary>
 public string Email { get; set; } = string.Empty;

 /// <summary>
 /// 員工密碼（加密）
 /// </summary>
 public string PasswordHash { get; set; } = string.Empty;

 /// <summary>
 /// 員工角色
 /// </summary>
 public int EmployeeRole { get; set; } = -1;
}

修改 JwtHelper，將傳入參數改成剛剛建立的 EmployeeDto，員工帳號識別，將員工角色寫入 JWT，如下

CreateJwt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


/// <summary>
/// 產生 JWT
/// </summary>
/// <param name="employee"> 員工的登入資訊 </param>
/// <returns> JSON Web Token </returns>
public string CreateJwt(EmployeeDto employee) // 改傳入的參數
{
 var now = DateTimeOffset.UtcNow;

 // 設定 Payload
 List<Claim> claims = [
 // 發行單位
 new(JwtRegisteredClaimNames.Iss, _jwtOptions.Issuer),
 // 員工帳號作為識別
 new(JwtRegisteredClaimNames.Sub, employee.Email),
 // .......
 // 員工角色
 new(ClaimTypes.Role, $"{employee.EmployeeRole}", ClaimValueTypes.Integer)
 ];

 ......
}

GetEmployeeByEmailAsync

這個方法，需要調整 IEmployeeService 及 EmployeeService 的回傳物件型別

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


/// <summary>
/// 員工資料存取介面
/// </summary>
public interface IEmployeeService
{
 ......

 /// <summary>
 /// 依帳號取得員工資料
 /// </summary>
 /// <param name="email"> 員工帳號 </param>
 /// <returns> 員山資料，如果使用者不存在就 null </returns>
 Task<EmployeeDto?> GetEmployeeByEmailAsync(string email); // 這裡改成回傳 `EmployeeDto?`
}

/// <summary>
/// 員工資料存取服務
/// </summary>
public class EmployeeService(AppDbContext dbContext) : IEmployeeService
{
 ......

 /// <summary>
 /// 依帳號取得員工資料
 /// </summary>
 /// <param name="email"> 登入信箱/註冊信箱 </param>
 /// <returns> 員工資料 或 null </returns>
 public async Task<EmployeeDto?> GetEmployeeByEmailAsync(string email)
 {
 var employee = await _appDb.Employees
 .FirstOrDefaultAsync(e => e.Email == email);

 return employee == null
 ? null
 : new EmployeeDto
 {
 Email = employee.Email,
 PasswordHash = employee.PasswordHash,
 EmployeeRole = employee.UserRole
 };
 }
}

ValidateUserAsync

因為驗證密碼的方法也有使用 GetEmployeeByEmailAsync，所以也要調整 AuthService 的驗證部分，在這裡有重複取得員工資料再驗證，改成不再讀取員工資料一次，改成從 AuthController 傳入，這邊一樣要調整 IAuthService，AuthService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 驗證服務介面
/// </summary>
public interface IAuthService
{
 /// <summary>
 /// 驗證員工登入資料是否與資料庫相同
 /// </summary>
 /// <param name="loginDto"> 員工登入資料 </param>
 /// <param name="employeeDto"> 員工資料 </param>
 /// <returns> 驗證結果 </returns>
 bool ValidateUserAsync(LoginDto loginDto, EmployeeDto employeeDto);
}

/// <summary>
/// 驗證服務
/// </summary>
public class AuthService: IAuthService // 將 EmployeeService 拿掉
{
 /// <summary>
 /// 驗證員工登入密碼
 /// </summary>
 /// <param name="loginDto"> 員工登入資料 </param>
 /// <param name="employeeDto"> 員工資料 </param>
 /// <returns> 驗證結果 </returns>
 public bool ValidateUserAsync(LoginDto loginDto, EmployeeDto employeeDto)
 {
 if(string.IsNullOrEmpty(loginDto.Email)
 || string.IsNullOrEmpty(loginDto.Password))
 throw new ArgumentException($"Invalid {nameof(loginDto.Email)} or {nameof(loginDto.Password)}!");

 // 驗證員工資料
 if (employeeDto == null) throw new NullReferenceException("Employee not found!");

 // 回傳驗證結果
 return new PasswordHasher<EmployeeDto>().VerifyHashedPassword(
 employeeDto, employeeDto.PasswordHash, loginDto.Password
 ) == PasswordVerificationResult.Success;
 }
}

LoginAsync

最後回來改 AuthController 的登入方法，驗證方法因為 GetEmployeeByEmailAsync 的改變也改變了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#region 登入
/// <summary>
/// 登入 API
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[AllowAnonymous]
[HttpPost("login")]
public async Task<ActionResult> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 ......

 // 檢查員工帳號
 ......

 // 檢查員工密碼並回傳登入結果
 if (!_authService.ValidateUserAsync(loginDto, employee))
 return BadRequest("Login failed!");

 // 產生 Jwt
 var jwt = _jwtHelper.CreateJwt(employee);

 return Ok(jwt);
}
#endregion

實作驗證

在專案目錄下新增 ActionFilter 目錄，在錄目下新增 RolePermission.cs 作為驗證邏輯

1
2
3


JWT_Authentication_API
 └─ActionFilter
 └─RolePermission.cs

RolePermission

大部分在網路上 Google 到的範例，應該都是使用 ASP.NET Core 預設的驗證，預設的 Filter 只有提供字串，不過我採用自定義 ActionFilter 的方式進行驗證，可以提供更多元的驗證邏輯，要實作一個類別，跟一個介面

1
2
3
4


// 多個使用者，「,」分隔
[Authorize(Roles = "Role1, Role2")]
// 一個使用者
[Authorize(Roles = "Role")]

不過我希望可以套用到自已的 UserRole，所以要實作 Attribute 類別，提供自定義的角色

1
2
3
4
5


namespace JWT_Authentication_API.ActionFilter;

public class RolePermission: Attribute
{
}

另外預設的驗證是實作 IActinFilter，我需要是一個專門在處理權限的驗證，因此會再實作 IAuthorizationFilter，並傳入自定義的角色 UserRole 作為參數，如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


using System.Security.Claims;
using JWT_Authentication_API.Enums;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

namespace JWT_Authentication_API.ActionFilter;
/// <summary>
/// 角色驗證的邏輯
/// </summary>
/// <param name="userRoles"> 允許的角色名單 </param>
public class RolePermission(params UserRole[] userRoles): Attribute, IAuthorizationFilter
{
 /// <summary>
 /// 角色清單
 /// </summary>
 private readonly UserRole[] _userRoles = userRoles;

 /// <summary>
 /// 實際角色驗證的邏輯
 /// </summary>
 /// <param name="context"> 驗證場景，包含 request 的相關資訊 </param>
 public void OnAuthorization(AuthorizationFilterContext context)
 {
 // 從 JWT 中取得使用者角色
 var userRole = context.HttpContext.User?.Claims
 .Where(c => c.Type == ClaimTypes.Role)
 .Select(c => c.Value)
 .FirstOrDefault();

 // 取得失敗
 if (string.IsNullOrEmpty(userRole))
 // Http 403
 context.Result = new ForbidResult();
 // 取出來的角色是 string，為避免轉換失敗，用 TryParse 轉換成 int
 // TryParse 會回傳轉換的結果，如果無法轉換會 回傳 fasle
 // 如果可以轉換，會將轉換的值寫到 out 指定的變數
 if (int.TryParse(userRole, out var role))
 {
 // 如果不在允許的角色清單中
 if (_userRoles.All(u => (int)u != role))
 {
 // Http 403
 context.Result = new ForbidResult();
 }
 else
 {
 // 在行 JWT 中取得角色帳號
 var email = context.HttpContext.User.Claims
 .Where(c => c.Type == JwtRegisteredClaimNames.Sub)
 .Select(c => c.Value)
 .FirstOrDefault();

 // 如果沒有取得使用帳號，回傳 Http 403
 if(string.IsNullOrEmpty(email))
 context.Result = new ForbidResult();

 // 記住現在登入者的角色及帳號
 context.HttpContext.Items.Add(nameof(UserRole), role);
 context.HttpContext.Items.Add("Email", email);
 }
 }
 else
 {
 // 轉換失敗，Http 403
 context.Result = new ForbidResult();
 }
 }
}

EmployeeController

接著我設計一個情境，只有人資主管可以看到所有的員工資料，其他員工只能看到自已的資料，所以需要一個 EmployeeController 來處理員工資料存取的請求，並注入 EmployeeService 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using JWT_Authentication_API.Interfaces;
using Microsoft.AspNetCore.Mvc;

namespace JWT_Authentication_API.Controllers;
/// <summary>
/// 員工資料存取
/// </summary>
/// <param name="employeeService"> 員工資料服務 </param>
[ApiController, Route("api/[controller]")]
public class EmployeeController(IEmployeeService employeeService) : Controller
{
 /// <summary>
 /// 員工資料服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;
}

同時要調整 IEmployeeService 及 EmployeeService 加入取得所有員工資料的方法，如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 員工資料存取介面
/// </summary>
public interface IEmployeeService
{
 ......

 /// <summary>
 /// 取得所有員工資料
 /// </summary>
 /// <returns> 所有員工資料 </returns>
 Task<IEnumerable<EmployeeDto>> GetEmployeesAsync();
}

using System.ComponentModel.DataAnnotations;
using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;

/// <summary>
/// 員工資料存取服務
/// </summary>
/// <param name="dbContext"> 資料庫對映物件 </param>
public class EmployeeService(AppDbContext dbContext) : IEmployeeService
{
 /// <summary>
 /// 資料庫對映物件
 /// </summary>
 private readonly AppDbContext _appDb = dbContext;

 ......

 /// <summary>
 /// 取得所有員工資料
 /// </summary>
 /// <returns> 所有員工資料 </returns>
 public async Task<IEnumerable<EmployeeDto>> GetEmployeesAsync()
 {
 // 從資料庫取得員工資料，由於資料量少，可以直接 ToList，當資料量大的時候建議實作分頁
 return await _appDb.Employees.Select(e => new EmployeeDto
 {
 Email = e.Email,
 EmployeeRole = e.UserRole
 }).ToListAsync();
 }
}

再回到 EmployeeController，加入 Employees 及 GetEmployee 方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


using JWT_Authentication_API.ActionFilter;
using JWT_Authentication_API.Enums;
using JWT_Authentication_API.Interfaces;
using Microsoft.AspNetCore.Mvc;

namespace JWT_Authentication_API.Controllers;
/// <summary>
/// 員工資料存取
/// </summary>
/// <param name="employeeService"> 員工資料服務 </param>
[ApiController, Route("api/[controller]")]
public class EmployeeController(IEmployeeService employeeService) : Controller
{
 /// <summary>
 /// 員工資料服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;
 /// <summary>
 /// 取得單一員工資料
 /// </summary>
 /// <returns> 指定的員工資料 </returns>
 [RolePermission(UserRole.Intern, UserRole.HrAssistant, UserRole.HrHead)]
 [HttpPost("get/employee")]
 public async Task<ActionResult> GetEmployee()
 {
 var userRole = HttpContext.Items[nameof(UserRole)] as string;
 var email = HttpContext.Items["Email"] as string;

 if (string.IsNullOrEmpty(userRole) || string.IsNullOrEmpty(email))
 return BadRequest($"{nameof(userRole)} or {nameof(email)} are required.");
 // 取得員工資料
 var employee = await _employeeService.GetEmployeeByEmailAsync(email);
 if(employee == null)
 return NotFound($"{email} not found.");

 // 密碼不應該回傳
 employee.PasswordHash = string.Empty;
 return Ok(employee);
 }

 /// <summary>
 /// 取得所有員工資料
 /// </summary>
 /// <returns></returns>
 [RolePermission(UserRole.HrHead)]
 [HttpPost("get/employees")]
 public async Task<IActionResult> Employees()
 {
 var employees = await _employeeService.GetEmployeesAsync();
 if(employees == null) return NotFound();

 return Ok(employees.ToList());
 }
}

都完成後就可以使用 Postman 來測試了，測試資料參考

Heine

本例角色是實習生(UserRole = 0)，先用 auth/login 取得 heine 的 JWT：在用下面的相關網址測試權限

get/employee 測試取得自己的員工資料

get/employees 測試取得所有員工資料，會發現是 Http 403 回應，代表實習生是沒有這個權限的

Adam

本例角色是人資助理(UserRole = 1)，應該也只能取得自己的資料，操作同上

get/employee

get/employees

Peter

本例是人資主管(UserRole = 2)，應該要可以取得所有員工資料

get/employee

get/employees

RefreshToken

RefreshToken 簡單來說就是為了取得新的 JWT 的 Token，這個驗證機制分成了兩個部分

AccessToken：以本篇來說，就是 JWT，為了安全性考量，效期比較短（數分 ~ 數小時）。
RefreshToken：更新 AccessToken 的 Token，為了使用者體驗並兼顧安全性，一樣需要設定有效期限，不過期限比較長（數日）。

因為 JWT 的有效期限比較短，假設一個使用者在系統操作某個功能，一段時間後又需要操作另一個功能，但因為時間的關係導致 JWT 過期了，這個時候可能會強制登出，或回傳 Http 401，最後使用者都要重新登入才可以進行接下來的任務，這樣會讓使用者體驗不佳。我個人覺得 RefreshToken 是在安全性及使用者體驗中取得一個平衡，在 JWT 過期時，可以使用 RefreshToken 來更換一個新的 JWT，讓使用者可以不用重新登入，增加使用者體驗

Sequence Diagram

登入的部分可以參考，不過在登入完成後回傳的物件除了 JWT 還增加了一個 RefreshToken，下圖為 RefreshToken 使用場景

當需要某存取伺服器上的資源時，跟原本使用 JWT 一樣，將 JWT 傳送至伺服器驗證
如果 JWT 合法就可以存取相關資源，如果 JWT 過期伺服器會回應 JWT 過期了。
將 RefreshToken 送到伺服器驗證
RefreshToken 合法伺服器會更換新的 JWT，如果 RefreshToken 也過期了或是不合法，就要重新登入。
將新的 JWT 回應給使用者（就像再次登入的意思），至於要不要回傳新的 RefreshToken 會依使用需求而定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 ┌──────┐ ┌──────────────────────┐ ┌─────────┐
 │Client│ │Filter(Validate Token)│ │WebServer│
 └──┬───┘ └──────────┬───────────┘ └────┬────┘
 │ │ │
 │ 1. Request(JWT) │ │
 │─────────────────────────────────>│ │
 │ │ │
 │ │ 2-1. JWT is valid │
 │ │───────────────────────>│
 │ │ │
 │ 2-2. Response(JWT Expired) │ │
 │<─────────────────────────────────│ │
 │ │ │
 │ 3. Request(RefreshToken) │ │
 │─────────────────────────────────>│ │
 │ │ │
 │ │4. RefreshToken is valid│
 │ │───────────────────────>│
 │ │ │
 │4-2 Response(RefreshToken Expired)│ │
 │<─────────────────────────────────│ │
 │ │ │
 │ 5. Response(NewJWT, NewRefreshToken[optional]) │
 │<──────────────────────────────────────────────────────────│
 ┌──┴───┐ ┌──────────┴───────────┐ ┌────┴────┐
 │Client│ │Filter(Validate Token)│ │WebServer│
 └──────┘ └──────────────────────┘ └─────────┘

TokenHelper

為了產生 RefreshToken，在使用者登入時一並回傳，在 Helper 目錄下新增 TokenHelper.cs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


using System.Security.Cryptography;

namespace JWT_Authentication_API.Helper;

/// <summary>
/// Token 輔助類別，宣告為 static
/// 不需要 DI 可以直接使用
/// </summary>
public static class TokenHelper
{
 /// <summary>
 /// 產生 RefreshToken
 /// </summary>
 /// <param name="byteSize"> RefreshToken 的位元長度，預設 32 位元 </param>
 /// <returns> Base64 編碼後的 RefreshToken </returns>
 public static string GenerateRefreshToken(int byteSize = 32)
 {
 var randomBytes = new byte[byteSize];
 var rnd = RandomNumberGenerator.Create();
 rnd.GetBytes(randomBytes);
 return Convert.ToBase64String(randomBytes);
 }
}

RefreshToken Entity

為了驗證 RefreshToken，需要將 RefreshToken 存入資料庫，在 Entities 目錄新增 RefreshToken.cs 如下

其中為了知道這個 RefreshToken 是哪一位員工的，所以加入了 EmployeeId 這個欄位，另外 Employee 導航屬性，會將 EmployeeId 自動關聯到 Employee 的對映物件，不過資料庫不是本篇的重點，所以就不多說明了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace JWT_Authentication_API.Entities;

/// <summary>
/// RefreshToken 的資料模型
/// </summary>
public class RefreshToken
{
 /// <summary>
 /// RefreshToken 的資料識別
 /// </summary>
 [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
 public Guid Id { get; set; }
 /// <summary>
 /// RefreshToken 的值
 /// </summary>
 [Required, MaxLength(512)]
 public string Token { get; set; } = string.Empty;
 /// <summary>
 /// RefreshToken 過期的時間
 /// </summary>
 public DateTimeOffset ExpiresAt { get; set; }
 /// <summary>
 /// RefreshToken 建立的時間，預設是產生的當下
 /// </summary>
 public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.Now;
 /// <summary>
 /// 員工的識別（FK）
 /// </summary>
 public Guid EmployeeId { get; set; }
 /// <summary>
 /// 關聯的 Employee（ORM 的關聯設定）
 /// </summary>
 [ForeignKey("EmployeeId")]
 public Employee Employee { get; set; } = null!;
}

接著在 AppDbContext.cs 加入 RefreshToken 的對映

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Entities;

/// <summary>
/// Database Context
/// </summary>
/// <param name="options"> 資料庫設定 </param>
public class AppDbContext(DbContextOptions<AppDbContext> options)
 : DbContext(options)
{
 /// <summary>
 /// 員工資料表
 /// </summary>
 public DbSet<Employee> Employees { get; set; }
 /// <summary>
 /// Token 黑名單資料表
 /// </summary>
 public DbSet<TokenBlackList> TokenBlackLists { get; set; }
 /// <summary>
 /// RefreshToken 資料表
 /// </summary>
 public DbSet<RefreshToken> RefreshTokens { get; set; }
}

完成後使用 Rider 新增 Migration 並更新資料庫參考

ITokenService

由於 RefreshToken 的驗證機制，我利用上一篇所建立的 TokenService 實作相關功能，所以先定義會用到的方法

新增：員工登入時，產生新的 RefreshToken
驗證：在要更新之前要檢查 RefreshToken 是否過期，如果過期回傳 RefreshToken 過期，沒過期才更新。
更新：JWT 過期時，要產生新的 JWT，同時更新一個新的 RefreshToken，基於安全性考量，我只更新 Token 的值，不更新到期時間
刪除：員工登出時，刪除員工所屬的 RefreshToken，再新增到黑名單

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 /// <summary>
 /// 新增 token 到黑名單
 /// </summary>
 /// <param name="token"> 要新增的 token </param>
 /// <returns> 新增結果 </returns>
 Task<bool> AddTokenToTokenBlackListAsync(string token);

 /// <summary>
 /// 新增 RefreshToken
 /// </summary>
 /// <param name="refreshToken"> 要新增的 RefreshToken </param>
 /// <returns> 新增的結果 </returns>
 Task<bool> AddRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto);

 /// <summary>
 /// 檢查 RefreshToken 是否過期
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要檢查的 RefreshToken 物件 </param>
 /// <returns> 檢查結果 </returns>
 Task<bool> IsRefreshTokenExpiredAsync(RefreshTokenRequestDto refreshTokenRequestDto);

 /// <summary>
 /// 更新 RefreshToken
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要更新的 RefreshToken 物件 </param>
 /// <returns> 更新結果 </returns>
 Task<bool> UpdateRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto);

 /// <summary>
 /// 刪除 RefreshToken
 /// </summary>
 /// <param name="refreshToken"> 要刪除的 RefreshToken </param>
 /// <returns> 刪除結果 </returns>
 Task<bool> RemoveRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto);
}

RefreshTokenRequestDto

上一個完成後會出現錯誤，因為沒有 RefreshTokenRequestDto 這個物件，所以在 Models 下新增這個類別，上面的方法，都會需要知道要異動的是哪一筆 RefreshToken，所以要知道哪一個員工、舊的 RefreshToken 或新的 RefreshToken

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


namespace JWT_Authentication_API.Models;

/// <summary>
/// RefreshToken 的請求物件
/// </summary>
public class RefreshTokenRequestDto
{
 /// <summary>
 /// 員工的識別
 /// </summary>
 public Guid EmployeeId { get; set; } = Guid.Empty;
 /// <summary>
 /// 舊的 RefreshToken
 /// </summary>
 public string OldRefreshToken { get; set; } = string.Empty;
 /// <summary>
 /// 新的 RefreshToken
 /// </summary>
 public string NewRefreshToken { get; set; } = string.Empty;
}

最後傳 ITokenService 補上下面的程式碼就可以了

1

using JWT_Authentication_API.Models;

TokenService

介面定義完成後，就可以開始實作 TokenService 的方法，細節說明如下
更新、刪除都要找出要異動的那一筆資料，因此將查詢要異動的資料查詢方法獨立出來。

開啟 TokenService.cs，新增查詢 RefreshToken 的方法 _getRefreshToken
加入新增、驗證、更新、刪除 RefreshToken 的方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132


using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Helper;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 /// <summary>
 /// 資料庫物件
 /// </summary>
 private readonly AppDbContext _appDb = context;

 /// <summary>
 /// 將需要異動的 RefreshToken 依 token 及員工編號取得
 /// </summary>
 private readonly Func<string, Guid, Task<RefreshToken?>> _getRefreshToken =
 async (token, employeeId) =>
 await context.RefreshTokens.FirstOrDefaultAsync(r
 => r.EmployeeId == employeeId && r.Token == token);

 .......

 #region Add Refresh Token
 /// <summary>
 /// 新增 RefreshToken
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要新增的 RefreshToken </param>
 /// <returns> 新增的結果 </returns>
 /// <exception cref="ArgumentException"> 沒有提供新增的 RefreshToken 或所屬員工 </exception>
 public async Task<bool> AddRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto)
 {
 await _appDb.RefreshTokens.AddAsync(new RefreshToken
 {
 Token = refreshTokenRequestDto.NewRefreshToken,
 // 配合週休二日，設定 5 天後到期
 ExpiresAt = DateTimeOffset.Now.AddDays(5),
 EmployeeId = refreshTokenRequestDto.EmployeeId
 });

 return await _appDb.SaveChangesAsync() > 0;
 }
 #endregion

 #region Validate RefreshToken
 /// <summary>
 /// 檢查 RefreshToken 是否過期
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要檢查的 RefreshToken </param>
 /// <returns> 檢查結果 </returns>
 /// <exception cref="KeyNotFoundException"> 找不到要檢查的 RefreshToken </exception>
 public async Task<bool> IsRefreshTokenExpiredAsync(RefreshTokenRequestDto refreshTokenRequestDto)
 {
 // 取得要檢查的 RefreshToken
 var refreshToken = await _getRefreshToken(
 refreshTokenRequestDto.OldRefreshToken, refreshTokenRequestDto.EmployeeId);

 // 找不到要檢查的 RefreshToken
 if (refreshToken == null)
 throw new KeyNotFoundException("Refresh token not found!");

 // 回傳是否過期
 return DateTimeOffset.UtcNow > refreshToken.ExpiresAt;
 }
 #endregion

 #region Update Refresh Token
 /// <summary>
 /// 更新 RefreshToken
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要更新的 RefreshToken </param>
 /// <returns></returns>
 /// <exception cref="KeyNotFoundException"> 找不到要更新的 RefreshToken </exception>
 /// <exception cref="InvalidOperationException"> 新增舊的 RefreshToken 黑名單失敗 </exception>
 /// <exception cref="Exception"> 更新失敗 </exception>
 public async Task<bool> UpdateRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto)
 {
 // 先找出要更新的 refreshToken
 var refreshToken = await _getRefreshToken(
 refreshTokenRequestDto.OldRefreshToken, refreshTokenRequestDto.EmployeeId);

 // 如果找不到要刪除的 RefreshToken
 if (refreshToken == null)
 throw new KeyNotFoundException("Refresh token not found!");

 // 將舊的 RefreshToken 新增到黑名單
 var addResult = await AddTokenToTokenBlackListAsync(refreshToken.Token);
 if(!addResult) throw new InvalidOperationException
 ("Failed to add refresh token into black list!");

 // 更新 RefreshToken
 refreshToken.Token = refreshTokenRequestDto.NewRefreshToken;
 _appDb.RefreshTokens.Update(refreshToken);
 return await _appDb.SaveChangesAsync() > 0;
 }
 #endregion

 #region Remove Refresh Token
 /// <summary>
 /// 刪除 RefreshToken
 /// </summary>
 /// <param name="refreshTokenRequestDto"> 要刪除的 RefreshToken </param>
 /// <returns> 刪除結果 </returns>
 /// <exception cref="ArgumentException"> 沒有提供舊的 RefreshToken 或所屬員工 </exception>
 /// <exception cref="InvalidOperationException"> 舊的 RefreshToken 新增黑名單失敗 </exception>
 /// <exception cref="Exception"> 刪除失敗 </exception>
 public async Task<bool> RemoveRefreshTokenAsync(RefreshTokenRequestDto refreshTokenRequestDto)
 {

 // 先找出要刪除的 refreshToken
 var refreshToken = await _getRefreshToke(refreshTokenRequestDto.OldRefreshToken, refreshTokenRequestDto.EmployeeId);
 // 如果找不到要刪除的 RefreshToken
 if (refreshToken == null)
 throw new KeyNotFoundException("Refresh token not found!");

 // 將要刪除的 RefreshToken 新增到黑名單
 var addResult = await AddTokenToTokenBlackListAsync(refreshToken.Token);
 if(!addResult) throw new InvalidOperationException
 ("Failed to add refresh token into black list!");

 // 再將舊的 RefreshToken 刪除
 _appDb.RefreshTokens.Remove(refreshToken);

 return await _appDb.SaveChangesAsync() > 0;
 }
 #endregion
}

RefreshTokenResponseDto

在一開始的介紹說明，可以知道 RefreshToken 要回傳兩個物件

AccessToken：就是合法的 JWT
RefreshToken：更新 AccessToken 的 Token

所以要新增一個回傳用的 Model，在 Models 新增 RefreshTokenResponseDto.cs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


namespace JWT_Authentication_API.Models;

/// <summary>
/// RefreshToken 回應
/// </summary>
public class RefreshTokenResponseDto
{
 /// <summary>
 /// JWT
 /// </summary>
 public string AccessToken { get; set; } = string.Empty;
 /// <summary>
 /// RefreshToken
 /// </summary>
 public string RefreshToken { get; set; } = string.Empty;
}

Refresh

最後回到 AuthController.cs 實作 Refresh 檢查及更新 AccessToken 的方法，預期會傳送要更新的 RefreshToken，所以用 RefreshTokenRequestDto 當作參數

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


/// <summary>
/// 驗證、更新 RefreshToken
/// </summary>
/// <param name="requestDto"> 要驗證的 RefreshToken </param>
/// <returns> 新的 RefreshToken 或 AccessToken </returns>
[HttpPost("refresh-token")]
public async Task<ActionResult> RefreshTokenAsync(RefreshTokenRequestDto requestDto)
{
 // 產生一個新的 RefreshToken
 requestDto.NewRefreshToken = TokenHelper.GenerateRefreshToken();
 // 更新 RefreshToken
 var updateResult = await _tokenService.UpdateRefreshTokenAsync(requestDto);

 return Ok(new RefreshTokenResponseDto
 {
 RefreshToken = requestDto.NewRefreshToken
 });
}

完成後，會發現沒有產生新的 JWT 給 AccessToken，參考 CreateJwt，產生 JWT 需要 EmployeeDto，所以要新增一個取得員資料的方法，開啟 IEmployeeService、EmployeeService，加入 GetEmployeeById 方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 員工資料存取介面
/// </summary>
public interface IEmployeeService
{

 ......

 /// <summary>
 /// 依員工的 Id 取得員工資料
 /// </summary>
 /// <param name="id"> 員工識別 </param>
 /// <returns> 員工資料 </returns>
 Task<EmployeeDto?> GetEmployeeByIdAsync(Guid id);

 ...
}

using System.ComponentModel.DataAnnotations;
using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Services;

/// <summary>
/// 員工資料存取服務
/// </summary>
/// <param name="dbContext"> 資料庫對映物件 </param>
public class EmployeeService(AppDbContext dbContext) : IEmployeeService
{
 /// <summary>
 /// 資料庫對映物件
 /// </summary>
 private readonly AppDbContext _appDb = dbContext;

 ......

 /// <summary>
 /// 依員工 Id 找出員工資料
 /// </summary>
 /// <param name="id"> 員工識別 </param>
 /// <returns> 員工資料 </returns>
 public async Task<EmployeeDto?> GetEmployeeByIdAsync(Guid id)
 {
 var employee = await _appDb.Employees.FirstOrDefaultAsync(e => e.Id == id);

 if (employee == null) return null;

 return new EmployeeDto
 {
 Email = employee.Email,
 EmployeeRole = employee.UserRole
 };
 }

 ......
}

最後回到 AuthController 修改 Refresh 方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


/// <summary>
/// 驗證、更新 RefreshToken
/// </summary>
/// <param name="requestDto"> 要驗證的 RefreshToken </param>
/// <returns> 新的 RefreshToken 或 AccessToken </returns>
[HttpPost("refresh-token")]
public async Task<ActionResult> RefreshTokenAsync(RefreshTokenRequestDto requestDto)
{
 // 驗證 RefreshToken
 if(string.IsNullOrEmpty(requestDto.OldRefreshToken) ||
 requestDto.EmployeeId == Guid.Empty)
 return BadRequest("'EmployeeId' or 'OldRefreshToken' cannot be null or empty!");
 if(await _tokenService.IsRefreshTokenExpiredAsync(requestDto))
 return BadRequest("Refresh token expired!");

 // 產生一個新的 RefreshToken
 requestDto.NewRefreshToken = TokenHelper.GenerateRefreshToken();
 // 更新 RefreshToken
 await _tokenService.UpdateRefreshTokenAsync(requestDto);

 // 找出目前使用的員工
 var employee = await _employeeService.GetEmployeeByIdAsync(requestDto.EmployeeId);
 if (employee == null)
 return NotFound("Employee does not exist!");

 // 回傳新的 RefreshTokenResponse
 return Ok(new RefreshTokenResponseDto
 {
 AccessToken = _jwtHelper.CreateJwt(employee!),
 RefreshToken = requestDto.NewRefreshToken
 });
}

最後調整 LoginAsync 及 LogoutAsync 的方法，在登入時要新增 RefreshToken，登出時要將 JWT 及 RefreshToken 加到黑名單，並刪除員工所屬的 RefreshToken

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#region 登出
/// <summary>
/// 登出 API
/// </summary>
/// <returns> 登出結果 </returns>
[Authorize]
[HttpPost("logout")]
public async Task<IActionResult> LogoutAsync(RefreshTokenRequestDto requestDto)
{
 // 從 header 讀取 JWT
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer", string.Empty, StringComparison.OrdinalIgnoreCase)
 .Trim();
 if (string.IsNullOrEmpty(token))
 return BadRequest("Not token provided!");

 // 將 JWT 加入黑名單
 var result = await _tokenService.AddTokenToTokenBlackListAsync(token);
 if (!result) return BadRequest("Logout failed!");

 // 將 refreshToken 刪除
 result = await _tokenService.RemoveRefreshTokenAsync(requestDto);
 if (!result) return BadRequest("Logout failed!");

 return Ok("Logout successfully!");
}
#endregion

登入的部分，因為需要員工的 Id，所以要修改 EmployeeDto，加入 EmployeeId 的欄位

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


namespace JWT_Authentication_API.Models;

/// <summary>
/// 員工角色資料
/// </summary>
public class EmployeeDto
{
 /// <summary>
 /// 員工 Id
 /// </summary>
 public Guid Id { get; set; } = Guid.Empty;

 ...
}

調整 EmployeeService 的 GetEmployeeByEmailAsync 方法，多回傳一個 Id 欄位

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


/// <summary>
/// 依帳號取得員工資料
/// </summary>
/// <param name="email"> 登入信箱/註冊信箱 </param>
/// <returns> 員工資料 或 null </returns>
public async Task<EmployeeDto?> GetEmployeeByEmailAsync(string email)
{
 var employee = await _appDb.Employees
 .FirstOrDefaultAsync(e => e.Email == email);

 return employee == null
 ? null
 : new EmployeeDto
 {
 Id = employee.Id,
 Email = employee.Email,
 PasswordHash = employee.PasswordHash,
 EmployeeRole = employee.UserRole
 };
}

回到 LoginAsync，加入新增 RefreshToken 的方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


#region 登入
/// <summary>
/// 登入 API
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[AllowAnonymous]
[HttpPost("login")]
public async Task<ActionResult> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 if (string.IsNullOrEmpty(loginDto.Email) ||
 string.IsNullOrEmpty(loginDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 檢查員工帳號
 var employee = await _employeeService.GetEmployeeByEmailAsync(loginDto.Email);
 if (employee == null)
 return BadRequest("User does not exist!");

 // 檢查員工密碼並回傳登入結果
 if (!_authService.IsValidateUserAsync(loginDto, employee))
 return BadRequest("Login failed!");

 // 新增 RefreshToken 及產生 Jwt
 var jwt = _jwtHelper.CreateJwt(employee);
 var refreshToken = TokenHelper.GenerateRefreshToken();

 var result = await _tokenService.AddRefreshTokenAsync(new RefreshTokenRequestDto
 {
 EmployeeId = employee.Id,
 NewRefreshToken = refreshToken,
 });
 if(!result) return StatusCode(StatusCodes.Status500InternalServerError);

 return Ok(new RefreshTokenResponseDto
 {
 AccessToken = jwt,
 RefreshToken = refreshToken
 });
}
#endregion

測試

都完成後，就可以來測試 RefreshToken 的驗證機制了

開啟 Postman 使用 peter 登入，如果有成功收到 ResponseToken，將 Response 的 body 整個 copy 下來，在 Save Response 下方有一個複製的按鈕

1
2
3
4


{
 "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJKV1QtQXV0aGVudGljYXRpb24tQVBJIiwic3ViIjoicGV0ZXJAZ21haWwuY29tIiwiZXhwIjoxNzQzMzUxNjk3LCJqdGkiOiI1Y2VlODA5OS0wMGRkLTQzODctYjg0Ny1lNzg3OWNiODliMDEiLCJpYXQiOiIxNzQzMzUxMDk3IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoyfQ.6FD4TNvYlsLNdLLKj5nFmaiGIAxbvtDkSDfxUa9-Mwk",
 "refreshToken": "qRs0NpTz1YHBAwZlYAbtZ0nI3oIxcHvMH2ELehqTaYI="
}

refresh-token

接下來測試 refresh-token，由於需要知道 peter 的 Id，所以開啟 Rider 資料庫工具輸入下面的語法，來取得 Peter 的 Id，也將 Id 複製下來

1
2
3


SELECT Id
FROM Employees
WHERE Email = 'peter@gmail.com'

我的資料庫中 peter 的 Id 如下

1

8d9e431a-e002-416b-21f3-08dd670f7321

在 Postman 中新增一個 refresh-token 的 request，並在 body 中選 raw，最旁邊下拉選 JSON，輸入要傳送的物件格式 RefreshTokenRequestDto 如下

employeeId：上面查詢的 peter Id
oldRefreshToken：一開始登入的 RefreshToken
newRefreshToken：更新不需要提供，由程式自己產生，給空字串

1
2
3
4
5


{
 "employeeId": "8d9e431a-e002-416b-21f3-08dd670f7321",
 "oldRefreshToken": "qRs0NpTz1YHBAwZlYAbtZ0nI3oIxcHvMH2ELehqTaYI=",
 "newRefreshToken": ""
}

最後 Send，看有沒有重新取得一組新的 RefreshTokenResponseDto 物件，如果有可以將它複製下來與第一次登入的對比

1
2
3
4


{
 "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJKV1QtQXV0aGVudGljYXRpb24tQVBJIiwic3ViIjoicGV0ZXJAZ21haWwuY29tIiwiZXhwIjoxNzQzMzUxODIxLCJqdGkiOiJiNDQzYWFiNS1iZWE0LTRjMzUtOTkwMC04NjZmZDFhN2ZlYzQiLCJpYXQiOiIxNzQzMzUxMjIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoyfQ.K7Bc135CScAdUFqun1M4vVrl5CIBw2rApZgGqr5I1Y0",
 "refreshToken": "NVqRHLaHqE3hyHbiAcdRq+kSgdnaeWvl525qhg2KxO4="
}

Logout

最後來測登出，一樣傳入 RefreshTokenRequestDto 物件，不過更新不同的是 oldRefreshToken，要改成上一個測試 refresh-token 拿到的 refreshToken，如果使用第一次登入所拿到的 refreshToken 應該會出現 HTTP 500，因為原本的 refreshToken 在 refresh-token 的時候就己經寫到黑名單了，所以會找不到

1
2
3
4
5


{
 "employeeId": "8d9e431a-e002-416b-21f3-08dd670f7321",
 "oldRefreshToken": "NVqRHLaHqE3hyHbiAcdRq+kSgdnaeWvl525qhg2KxO4=",
 "newRefreshToken": ""
}

另外將更新後的 AccessToken 放到 Authorization，

Send 後看登出結果

最後，使用資料庫工具確認黑名單有沒有資料，理論上來說應該要有 4 筆資料，更新的時候會將第一次登入的兩個 Token 新增到黑單、登出的時候會把 refresh-token 取得的兩個新 Token 寫入，使用下面的語法查詢

1
2


SELECT *
FROM TokenBlackLists

RefreshToken 應該要是 0 筆，因為 peter 已經登出了

1
2


SELECT *
FROM dbo.RefreshTokens

結語

內容很長，終於完成了！不過這個版本的程式仍然有一些問題，例如：在登出的時候同時新增了黑名單，刪除 RefreshToken，而這兩個操作各自儲存了異動，容易造成資料不一致

也就是說，新增黑名單完成後，如果在刪除 RefreshToken 出現錯誤導致 RefreshToken 並沒有被刪除，但就已經出現在黑名單了，這樣的資料不應該新增進黑名單，應該是兩個操作同時完成後再一次儲存。

所以如果同時要操作多個資料表，需要所有操作都完成後再一次儲存所有異動

第二個問題是，我在 Service 層中丟出了很多系統執行時的 Exception，但沒有在 Controller 中處理，應該要在 Controller 統一處理，因此需要統一回應物件格式，這些會在下一篇一一說明並實作。

ASP.NET Core 實作 JWT 認證

Sat, 15 Mar 2025 16:43:21 +0800

為什麼會寫這一篇

在開發 ASP.NET Core Web API 時，JWT（JSON Web Token）是一種常見的認證方式。然而，在 Google 搜尋相關教學時，我發現大多數的範例都使用 ASP.NET Core Identity，但在企業內部系統中，很多公司會使用 自行設計權限與認證機制，在我的經驗中，系統登入/登出 是非常常見的功能，因此我想結合我的經驗實作一個 JWT 的認證。如果你希望在 ASP.NET Core Web API 中自行管理 JWT 認證，這篇文章會是一個不錯的參考。

本篇重點

Rider
JWT（JSON Web Token）
Entity Framework Core
登入/登出/註冊
Web API（Application Programming Interface）

閱讀說明書

本篇適合

有 C# 基礎
有 JSON 基礎
有 API 基礎知識
有 ASP.NET Core(MVC) 基礎

JWT（JSON Web Token）

JWT 全名是 JSON Web Token，是一種 輕量級的認證與授權機制，常用於 Web API 的身份驗證。它是一種 基於 Token 的驗證方式，不需要在伺服器端維護使用者的登入狀態，適合 無狀態（stateless） 應用，例如 RESTful API。

無狀態（stateless）

指 伺服器不會記住客戶狀態，使用者登入的資訊會記錄在客戶端的瀏覽器（使用 Cookie）

與之相對的就是 有狀態（stateful），早期 JSON 還沒發成熟時，很多系統會 將使用者登入資訊記錄在伺服器（使用 Session）來進行身份驗證，由於資料都是記錄在伺服器，所以容易造成伺服器運算效能問題，同時要記錄使用者登入資訊、進行使用者身份驗證……。

當然，由於使用者登入資訊記錄在使用者電腦瀏覽器中，會造成管理上的問題以及資訊安全風險，因些需要進行一些設定來防止資料外洩，下面實作會再介紹。

格式

接下來說明一下 JWT 的格式，由三個部分組成，每一個部分用「.」區隔

用來說明 Token 的類型及加密所使用的演算法，最後由 Base64Url 編碼整段 Header

typ：Token 的類型，通常是 JWT(JSON Web Token)
alg：加密演算法，通常是 SH256（HMAC SHA256）

1
2
3
4


{
 "typ": "JWT",
 "alg": "SH256"
}

Payload

JWT 的主要資訊，通常包含使用者的登入資訊（Claims）, 同樣也使用 Base64Url 編碼整個資訊

iss：發行這個 Token 的單位，通常是 Server 自己
sub：JWT 的使用者，通常會放使用者的 ID
name：使用者的名稱，通常是使用者帳號
aud：JWT 的接收單位，如果有開放給第三方使用的話，這裡會是呼叫端的 domain
exp：JWT 的有效期限，以 UNIX Timestamp 表示，會是一串數字，為了安全性考量，不會讓使用者無限期登入
iat：JWT 的產生時間，同上是一串數字，也就是這個 Token 是什麼時候建立的

其他通常會放企業自訂的資訊，如使用者角色「role」、部門「department」等

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "iss": "https://serverdomain.com/",
 "sub": "6dced4f8-e22a-4a5e-87d9-81e8de14dc24",
 "name": "useraccount@mail.com",
 "aud": "https://thirdpartydomain.com",
 "exp": 1712682600,
 "iat": 1712675400,
 "role": "admin",
 "department": "IT"
}

由於 Payload 資訊使用 Base64Url 編碼（非加密），所以是可以還原的，因此不建議加入機密資料，如：使用者密碼、或身份證明資訊。

Signature

中文應該是翻成數位簽章之類的，就是將 Header，Payload 的資料加起來，用 Header 的加密演算法及伺服器的 Private Key 加密的結果，最後用這個結果確認登入資料有沒有被竄改。

程式邏輯以 JavaScript 表示看起來會像下面這樣

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 假設有 3 個方法
// 1. createSignature，負責產生 Signature
// 2. base64Url，將物件進行 base64 編碼
// 3. HMACSHA256，將資料進行 SHA256 加密

// 參數傳入一個 jwt 物件
createSignature(jwt) {
 // 加密的 private key
 string secretKey = "thisissecretkey";
 // 加密資料
 return HMACSHA256(
 `${base64Url(jwt.Header)}.${base64Url(jwt.Payload)}`,
 secretKey
 );
}

PrivateKey（私鑰）是加密的關鍵之一，應該保存在伺服器，不可以外流
PrivateKey 及 Base64 非本編重點，這邊就不多加說明了

開發工具

其實我自己也是第一次作 JWT 驗證功能，最下方有我實作時看的影片，可以參考，但由於我的 .NET 版本是 8 版，所以有些地方略略有不同。

Rider
本來想用 Visual Studio 開發，不過由於要紀錄自己開發的過程，所以希望介面可以有善一點，最後決定使用 Rider 來作開發，也順便體驗 Rider 開發的感覺與 VS Code 有什麼不同。
Google Cloud
主要作為資料庫，因為我的作業系統是 MacOS，所以使用 MS SQL Server 有一些不方便，所以在雲端上開了一個 MS SQL Server 作為資料庫連線使用，且在現實情境下，大部分的資料庫不會在同一個 Server，這邊也當作模擬真實的情景。

建立專案

開啟 Rider 新增一個 Web API 專案，輸入資訊如下

Solution name：方案名稱
Project name：專案名稱
Solution directory：方案要存放的目錄
Target framework：.NET 的版本，選「net8.0」就是 .NET8
Language：使用的語言，選「C#」
Create Git repository：要不要上傳版本控制，自己決定
Template：專案範本，選「Web API」

其他可以不要動，如下圖

接著可以執行，按下右上角 綠色 bug 旁邊有一個 綠色 play

如果有看到 Swagger 的畫面而且網頁的主標題是專案名稱就是專案建立成功

開啟 Program.cs，將預設的 api 程式碼清掉，保留部分如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

WebApplication app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.Run();

安裝套件

我採用 Database-First 方式開發，也就是先建立資料模型再產生資料庫，其中會使用到 ORM（Object Relation Mapping） 物件關連對映的技術，所以會用到幾個 Nuget 的套件

EntityFrameworkCore.Design
EntityFrameworkCore.SqlServer

可以採用指令安裝或介面安裝

介面安裝

在 Rider 左下有一欄選單，可以找到 NuGet

在搜尋框中輸入套件名稱「EntityFrameworkCore.SqlServer」，通常第一個就會是我們要的結果，在 NuGet 視窗右半邊會看到版本，由於 .NET8 可以相容到 9.0.3 的版本，所以版本選「9.0.3」，當然你也可以選擇適合你本機環境的版本，如果你不是使用 .NET8 的話

在右半邊下方會看到專案的列表，我目前只有一個專案，所以只會出現一個，接著在要安裝的專案按下「+」就會安裝了，如下圖

會出現提示安裝的對話框，按下確定，另外一個套件再操作一次同樣的步驟

指令安裝

在 Rider 開啟終端機（Terminal）

輸入安裝指令如下，我撰寫這一篇文的時候是最新穩定版是 9.0.3，之後可能會更新，可以在上方 安裝套件 找到最新資訊

1
2


dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.3
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.3

建立資料模型

以 ORM 的概念來說，可以把一個 Entity 想像成一張資料表

在專案目錄下新增一個 Entities 的目錄，參考下圖，在「class/interface」選項下有一個「Directory」的選項，點擊後輸入目錄名稱 Entities，這個目錄將存放所有與資料庫互動的資料模型檔

Employee

以註冊、登入、登出這三個功能來說，一張員工的資料表已經夠了

並 Entities 目錄下新增 Employee.cs 檔案，作為員工資料模型，如下圖

員工資料模型內容如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace JWT_Authentication_API.Entities;
/// <summary>
/// 員工資料模型
/// </summary>
public class Employee
{
 /// <summary>
 /// 員工資料識別（PK）
 /// </summary>
 [Key]
 // 告訴資料庫這是自動產值的欄位，讓資料庫自行產生 key 值
 // 這樣程式就不用處理了
 [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
 public Guid Id { get; set; }

 /// <summary>
 /// 員工信箱：必要欄位
 /// </summary>
 [Required]
 public string Email { get; set; } = string.Empty;

 /// <summary>
 /// 密碼：必要欄位，且是加密過的值
 /// </summary>
 [Required]
 public string PasswordHash { get; set; } = string.Empty;

 /// <summary>
 /// 員工資料建立的時間，預設值是建立的當下
 /// </summary>
 public DateTimeOffset CreatedOn { get; set; } = DateTimeOffset.UtcNow;

 /// <summary>
 /// 員工資料修改的間，預設值是修改的當下
 /// </summary>
 public DateTimeOffset? ModifiedOn { get; set; }
}

欄位說明如註解，特別說明幾個重點

Email：員工的信箱，一般來而會使用員工的英文名字 + 公司內部的 mail server，因此已包含了姓名相關的資訊，所以為了教學我簡化了姓名「Name」欄位
CreateOn, ModifyOn：公司內部有時候會有某筆資料出問題的，經由某位員工或使用者反應，如登入失敗，為了要追查使用軌跡，會加入相關的時間欄位
Password：密碼應該要加密後再存入資料庫，所以這個欄位會存放加密後的值。

建立 DBContext

在建立資料模型有提到，在 ORM 中一個 Entity 是資料表的概念，那 DBContext 就是一個資料庫的概念，所以要建立一個專屬資料庫的類別作為資料庫的 Mapping，這個類別需要繼承「DBContext」

下面在 Entities 中建立一個 AppDbContext.cs 的類別

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Entities;

/// <summary>
/// Database Context
/// </summary>
/// <param name="options"> 資料庫連線相關設定，以 DI 形式 </param>
public class AppDbContext(DbContextOptions<AppDbContext> options)
 : DbContext(options)
{
 /// <summary>
 /// 員工資料表
 /// </summary>
 public DbSet<Employee> Employees { get; set; }
}

建立實體資料庫

資料模型及 DBContext 都建立好了之後，就可以建立實體資料庫了，在根目錄下開啟 appsettings.json 並**新增 ConnectionString（資料庫的連線字串）**如下

由於連線字串涉及我的資料庫帳號密碼，這邊需要改成自己的資料庫連線字串，參數說明如下

Server：資料庫伺服器的 IP，如果像我一樣架在雲端，就會是雲端主機的對外 IP，「,」後面接資料庫的 port，通常都是 1433。
Database：資料庫的名稱，也就是要連線到的目標資料庫
user：資料庫使用者的帳號，如果有建立「sa」的話就可以寫 sa
sa(System Admin)，是微軟 SQL Server 預設的最高權限帳號，通常安裝資料庫的時候會一起設定。
password：使用者密碼
TrustServerCertificate：是否信任伺服器的 SSL 憑證，如果 True 就不會檢查 Server 的憑證，可以自己決定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*",
 "ConnectionString": {
 "AppDb": "Server=YourServerIP,1433;Database=YourDatabaseName;user=username;password=YourDatabasePassword;TrustServerCertificate=True;"
 }
}

注入資料庫服務

開啟根目錄 Program.cs，注入資料庫服務

1
2
3
4
5
6
7


// Add SQL Server Database Service
// builder.Configuration 會參考到 `appsettings.json`
// GetConnectionString 方法會抓到資料庫連線字串，參數傳入上面設定的連線字串名字
builder.Services.AddDbContext<AppDbContext>(optionsBuilder =>
{
 optionsBuilder.UseSqlServer(builder.Configuration.GetConnectionString("AppDb"));
});

新增 Migration

接著在專案右鍵 → Entity Framework Core → Add Migration

按下「OK」

會在下方看到 EF Core 建立 Migration 的結果，如果沒有錯誤訊息（如下），就是成功了

成功後會看到專案下出現了 Migration 的目錄，並且出現兩個檔案，是紀錄資料模型的變更，每更新一次模型，就會再多出兩個檔，其中一個檔案會以「timestamp_MigrationName」命名

更新資料庫

接下來要將變更的模型，對映到資料庫，以產生實際的資料表
在專案右鍵 → Entity Framework Core → Update Database

出現更新對話框，Target migration，要設成上面產生的 migration 檔，確認後按下 OK

會在下方 EF Core 的視窗中看到執行更新資料庫的過程及執行的 SQL 語法，如果沒有看到錯誤訊息，就是成功了

驗證資料庫

Rider 提供了一個資料庫的圖型介面，讓我們可以確認資料庫的內容，在最右邊會看到一個資料庫的 icon，點擊後有一個「+」，選擇 Connect to Database

出現對話框後，選擇「use connection string」，將 建立實體資料庫 中的連線字串值（AppDB 不用）複製並貼上

貼上後等它跑一下，會出現 Test Connection，可以測試連線字串正確性，但一般來說，在貼上的時候，Rider 就會自動幫你測試了，確認無誤後可以按下「Connect to Database」連線到資料庫

就可以順利看到資料庫了

資料庫建立完成後，就可以開始實作「註冊」、「登入」、「登出」功能了

AuthController

首先新增一個 Controllers 目錄，在目錄中再新增 AuthController.cs 作為所有驗證行為的端點

新增完成後，將下 AuthController.cs 預設的方法刪掉，並宣告成 ApiController 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


using Microsoft.AspNetCore.Mvc;

namespace JWT_Authentication_API.Controllers;
/// <summary>
/// 將 AuthController 宣告成為 ApiController
/// 並定義路由規則（網址）=> domain/api/auth
/// </summary>
[ApiController, Route("api/[controller]")]
public class AuthController : Controller
{

}

ApiController：將目標控制器宣告成 API 控制器
Route：定義路由規則，[controller] 會變成目標控制器的名字，最後與 domain 組合成 API 網址

註冊

在 AuthController.cs 中新增註冊方法 register，並且使用 HttpPost 方式呼叫，其中參數 “register” 是路由的一部分，會加在網址的最後，有寫過 ASP.NET NVC 的話，很像傳統 MVC 的路由機制 Controller/Action，所以這個 [HttpPost(“register”)] 最後會變成 domain/api/auth/register 這個網址

1
2
3
4
5


[HttpPost("register")]
public ActionResult Register()
{

}

RegisterDto

接著需要一個 model 來負責接收註冊資料，在根目錄下新增 Models 目錄，在目錄下新增 RegisterDto.cs

如果有寫過 ASP.NET MVC 的話，也可以把它想像成是 ViewModels，不過因為 Api 沒有 View 的部分，我怕混淆所以改放在 Models

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


namespace JWT_Authentication_API.Models;

/// <summary>
/// 註冊使用的資料模型
/// </summary>
public class RegisterDto
{
 /// <summary>
 /// 使用者帳號
 /// </summary>
 public string Email { get; set; } = string.Empty;
 /// <summary>
 /// 使用者密碼（未加密）
 /// </summary>
 public string Password { get; set; } = string.Empty;
}

Register with HttpPost

回到 AuthController.cs 補上註冊方法的程式碼如下，說明如註解

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


/// <summary>
/// 註冊 API
/// </summary>
/// <param name="registerDto"> 使用者傳送的員工註冊資料 </param>
/// <returns> 註冊完成的員工資料 </returns>
[HttpPost("register")]
public ActionResult Register(RegisterDto registerDto)
{
 // 驗證註冊資料
 if (string.IsNullOrEmpty(registerDto.Email)
 || string.IsNullOrEmpty(registerDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 建立員工資料
 Employee employee = new() { Email = registerDto.Email };
 // 將密碼加密
 employee.PasswordHash = new PasswordHasher<Employee>()
 .HashPassword(employee, registerDto.Password);

 // 回傳建立完成的員工資料
 return Ok(employee);
}

安裝 scalar

註冊方法完成後，為方便測試，需要安裝 scalar 套件，在 NuGet 中搜尋「scalar」找到「Scalar.AspNetCore」並安裝

在 Program.cs 進行 scalar 的服務注入，影片中使用的版本是 .NET 9 的版本配置方式，我的環境是 .NET 8 的版本，所以略有不同
可以參考 Scalar 基本設定 及 .NET 8 的 Scalar 設定方式

開啟 Program.cs，改寫如下，其中 if 區塊是原本就有的，只需要更改區塊內的內容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
// 補上服務對控制器的注入
builder.Services.AddControllers();

#region Swagger Service
// Add Swagger service
builder.Services
 .AddEndpointsApiExplorer()
 .AddSwaggerGen();
#endregion

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
 // See https://github.com/scalar/scalar/blob/main/integrations/aspnetcore/README.md#usage
 app.UseSwagger(options =>
 options.RouteTemplate = "swagger/{documentName}/swagger.json"
 );
 // 因為要使用 scalar 的 UI，所以這邊將 Swagger UI 關閉
 // app.UseSwaggerUI();

 // See https://github.com/scalar/scalar/blob/main/documentation/integrations/dotnet.md#openapi-document-route
 app.MapScalarApiReference(options =>
 options.WithOpenApiRoutePattern("swagger/{documentName}/swagger.json"));
}

// 啟用控制器的 Route
app.MapControllers();

參考 建立專案 的執行方式執行網站，將網址改成 http://localhost:7274/scalar/v1，你的 port 可能跟我的不一樣

測試註冊

有兩種測試方式

執行後使用瀏覽器測試
使用 Postman 測試

瀏覽器測試

這裡先採用瀏覽測試的方法，在上面執行的網頁畫面，點 Auth 下面的 Api 網址，再按下「Test Request」

接著輸入要註冊的帳號密碼如下圖，只要有看到 200 及使用者註冊資料回傳就算成功了

當然也可以測試，沒有帳號或沒有密碼的情況，看看驗證訊息是否正確，參考 Register 方法 的第 10 ~ 12 行，有得到預期的驗證訊息就算成功了

跟註冊一樣，需要一個 Model 來紀錄傳送的登入資訊，所以在 Model 目錄下新增 LoginDto.cs
由於教學的場景假設「註冊」與「登入」都只有傳送「帳號/密碼」，所以可以偷懶一點直接繼承 RegisterDto.cs，但其他真實的場景可能會有一些差異，因些不建議直接繼承，且基於可讀性原則，我還是建一個 LoginDto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


namespace JWT_Authentication_API.Models;

/// <summary>
/// 使用者登入的資料模型
/// </summary>
public class LoginDto
{
 /// <summary>
 /// 使用者帳號
 /// </summary>
 public string Email { get; set; } = string.Empty;
 /// <summary>
 /// 使用者密碼（未加密）
 /// </summary>
 public string Password { get; set; } = string.Empty;
}

偷懶的作法

1
2
3
4
5
6


namespace JWT_Authentication_API.Models;

public class LoginDto: RegisterDto
{

}

分層架構

接下來要將 Register 方法做一些修改，將使用者註冊資料存到資料庫中，好讓之後的「登入」方法可以使用，並採用分層架構，讓程式碼可讀性更高

首先將建立員工資料的部分抽出來，不直接將資料存取功能放在 Controller，在專案下建立 Services 及 Interfaces 兩個目錄

Services：用來放存取資料的相關服務
Interfaces：服務的介面，供服務實作

當然分層架構還可以再抽出一層 Repository 不過這篇為教學簡化，所以只先抽 Service

IEmployeeService

在 Interfaces 目錄下新增 IEmployeeService.cs，新增員工服務介面，用來定義員工資料的存取功能，註冊就是新增一筆員工資料，所以在介面加入方法定義如下

新增員工
取得員工資料：用來檢查是否有重複註冊

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 員工資料存取介面
/// </summary>
public interface IEmployeeService
{
 /// <summary>
 /// 新增員工資料
 /// </summary>
 /// <param name="registerDto"> 員工註冊資料 </param>
 /// <returns> 註冊結果 </returns>
 Task<bool> AddEmployeeAsync(RegisterDto registerDto);

 /// <summary>
 /// 依帳號取得員工資料
 /// </summary>
 /// <param name="email"> 員工帳號 </param>
 /// <returns> 員工資料，如果找不到就 null </returns>
 Task<RegisterDto?> GetEmployeeByEmailAsync(string email);
}

EmployeeService

在 Services 目錄新增一個 EmployeeService.cs 並實作 IEmployeeService.cs 介面定義的方法如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


using System.ComponentModel.DataAnnotations;
using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Identity;

namespace JWT_Authentication_API.Services;

/// <summary>
/// 員工資料存取服務
/// </summary>
public class EmployeeService(AppDbContext dbContext) : IEmployeeService
{
 private readonly AppDbContext _appDb = dbContext;

 /// <summary>
 /// 新增員工資料
 /// </summary>
 /// <param name="registerDto"> 員工註冊資料 </param>
 /// <returns> 註冊結果 </returns>
 public async Task<bool> AddEmployeeAsync(RegisterDto registerDto)
 {
 // 這裡也可以不用檢查，`Controller` 檢查過一次了
 // 但基於安全性，我再檢查一次
 if (string.IsNullOrEmpty(registerDto.Email)
 || string.IsNullOrEmpty(registerDto.Password))
 throw new ValidationException("Email or password is required");

 // Create new employee data.
 Employee employee = new() { Email = registerDto.Email };
 // Hash password
 employee.PasswordHash = new PasswordHasher<Employee>()
 .HashPassword(employee, registerDto.Password);
 // Insert into database
 await _appDb.Employees.AddAsync(employee);
 // Save changes
 var result = await _appDb.SaveChangesAsync();

 return result > 0;
 }

 /// <summary>
 /// 依帳號取得員工資料
 /// </summary>
 /// <param name="email"> 註冊信箱/登入信箱 </param>
 /// <returns> 員工資料 或 null </returns>
 public async Task<RegisterDto?> GetEmployeeByEmailAsync(string email)
 {
 var employee = await _appDb.Employees
 .FirstOrDefaultAsync(e => e.Email == email);

 return employee == null
 ? null
 : new RegisterDto
 {
 Email = employee.Email,
 Password = employee.PasswordHash
 };
 }
}

修改註冊方法

回到 AuthController 的 Register 方法並加入員工服務物件的注入，修改如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Mvc;

namespace JWT_Authentication_API.Controllers;

/// <summary>
/// 將 AuthController 宣告成為 ApiController
/// 並定義路由規則（網址）=> domain/api/auth
/// </summary>
/// <param name="employeeService"> 員工資料存取服務 </param>
[ApiController, Route("api/[controller]")]
public class AuthController(IEmployeeService employeeService) : Controller
{
 /// <summary>
 /// 員工資料存取的服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;

 /// <summary>
 /// 註冊 API
 /// </summary>
 /// <param name="registerDto"> 使用者傳送的員工註冊資料 </param>
 /// <returns> 註冊完成的員工資料 </returns>
 [HttpPost("register")]
 public async Task<ActionResult> RegisterAsync(RegisterDto registerDto)
 {
 // 驗證註冊資料
 if (string.IsNullOrEmpty(registerDto.Email)
 || string.IsNullOrEmpty(registerDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 先查詢有沒有重複的員工資料
 var employee = await _employeeService.GetEmployeeByEmailAsync(registerDto.Email);

 // 如果沒有就透過服務註冊員工資料
 var registerResult =
 employee == null &&
 await _employeeService.AddEmployeeAsync(registerDto);

 // 回傳註冊結果
 return registerResult
 ? Ok("Register successfully!")
 : employee != null
 ? BadRequest("User already exists!")
 : BadRequest("Failed to register user");
 }
}

Employee DI

因為 AuthController 使用了 EmployeeService 依賴注入，所以需要去 Program.cs 註冊 EmployeeService 的服務，讓 AuthController 可以透過建構函式注入服務

特別注意一定要新增在 builder.Build() 的上面任一地方，因為呼叫 Build 方法後，就不能在註冊服務了

1
2
3
4
5


#region CustomService
builder.Services.AddScoped<IEmployeeService, EmployeeService>();
#endregion

WebApplication app = builder.Build();

正式開始實作登入，在 AuthController.cs 新增 Login 方法，接收參數為使用者輸入的帳號密碼
登入的部分可以分成兩步

檢查有沒有註冊這個員工，上面在 分層架構 已經完成了，如果沒有就回傳錯誤訊息。
驗證員工帳號密碼：如果第 1 步有找到註冊的員工資料，就要驗證輸入的帳號密碼，最後回傳驗證結果。

流程圖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 ┌─────┐
 │Start│
 └──┬──┘
 _______▽________ _________________
 ╱ ╲ ╱ ╲ ┌─────────────────────┐
 ╱ Missing Username ╲__________________________________________╱ Missing Username? ╲___│Username is required!│
 ╲ or Password ╱yes ╲ ╱yes└──────────┬──────────┘
 ╲________________╱ ╲_________________╱ │
 │no │no │
 ┌────────▽───────┐ ┌──────────▽─────────┐ │
 │Check Username │ │Password is required│ │
 │and PasswordHash│ └──────────┬─────────┘ │
 └────────┬───────┘ │ │
 _______▽________ │ │
 ╱ ╲ ┌──────────────────┐ │ │
 ╱ Invalid Username ╲_____________________│Username not found│ │ │
 ╲ ╱yes └─────────┬────────┘ │ │
 ╲________________╱ │ │ │
 │no │ │ │
┌──────────▽──────────┐ │ │ │
│Validate PasswordHash│ │ │ │
└──────────┬──────────┘ │ │ │
 _________▽__________ │ │ │
 ╱ ╲ ┌──────────────┐ │ │ │
╱ Invalid PasswordHash ╲___│Wrong Password│ │ │ │
╲ ╱yes└───────┬──────┘ │ │ │
 ╲____________________╱ │ │ │ │
 │no │ │ │ │
 ┌─────────▽────────┐ │ │ │ │
 │Login successfully│ │ │ │ │
 └─────────┬────────┘ │ │ │ │
 └───────────────────────┴┬────────────────┴────────────────────┴────────────────────────┘
 ┌─▽─┐
 │End│
 └───┘

新增一個 [HttpPost] 的 LoginAsync 方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


/// <summary>
/// 登入
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[HttpPost("login")]
public async Task<string> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 if (string.IsNullOrEmpty(loginDto.Email) ||
 string.IsNullOrEmpty(loginDto.Password))
 return "Please provide 'Email' and 'Password'";

 // 檢查員工帳號
 if (await _employeeService.GetEmployeeByEmailAsync(loginDto.Email) == null)
 return "User does not exist!";

 // 檢查員工密碼並回傳登入結果
 return result;
}

驗證員工密碼

員工密碼的檢查屬於「驗證」的範疇，所以不能寫在 Employee 的相關服務及定義
在 Interface 目錄下新增 IAuthService.cs，在 Services 目錄下新增 AuthService.cs

目錄結構如下

1
2
3
4
5


JwtAuthenticationAPI.csproj
 ├─Services
 │ └─AuthService.cs
 └─Interfaces
 └─IAuthService.cs

在 IAuthService.cs 新增驗證密碼方法定義

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using JWT_Authentication_API.Models;

namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// 驗證服務介面
/// </summary>
public interface IAuthService
{
 /// <summary>
 /// 驗證員工登入
 /// </summary>
 /// <param name="loginDto"> 員工登入資料 </param>
 /// <returns> 驗證結果</returns>
 Task<bool> ValidateUserAsync(LoginDto loginDto);
}

在 AuthService.cs 實作驗證方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Identity;

namespace JWT_Authentication_API.Services;

/// <summary>
/// 驗證服務
/// </summary>
public class AuthService(IEmployeeService employeeService): IAuthService
{
 /// <summary>
 /// 員工資料存取服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;

 /// <summary>
 /// 驗證員工登入密碼
 /// </summary>
 /// <param name="loginDto"> 員工登入資料 </param>
 /// <returns> 驗證結果 </returns>
 public async Task<bool> ValidateUserAsync(LoginDto loginDto)
 {
 if(string.IsNullOrEmpty(loginDto.Email)
 || string.IsNullOrEmpty(loginDto.Password))
 throw new ArgumentException($"Invalid {nameof(loginDto.Email)} or {nameof(loginDto.Password)}!");

 // 取得員工資料進行驗證
 var employee = await _employeeService.GetEmployeeByEmailAsync(loginDto.Email);
 if (employee == null) throw new NullReferenceException("Employee not found!");

 // 回傳驗證結果
 return new PasswordHasher<RegisterDto>().VerifyHashedPassword(employee,
 employee.Password, loginDto.Password)
 == PasswordVerificationResult.Success;
 }
}

最後再回到 AuthController.cs 注入驗證的服務物件，並在 LoginAsync 方法加入驗證的程式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


using JWT_Authentication_API.Interfaces;
using JWT_Authentication_API.Models;
using Microsoft.AspNetCore.Mvc;

namespace JWT_Authentication_API.Controllers;

/// <summary>
/// 將 AuthController 宣告成為 ApiController
/// 並定義路由規則（網址）=> domain/api/auth
/// </summary>
/// <param name="employeeService"> 員工資料存取服務 </param>
/// <param name="authService"> 登入驗證服務 </param>
[ApiController, Route("api/[controller]")]
public class AuthController(
 IEmployeeService employeeService,
 IAuthService authService) : Controller
{
 /// <summary>
 /// 員工資料存取的服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;
 /// <summary>
 /// 登入驗證的服務
 /// </summary>
 private readonly IAuthService _authService = authService;

 /// <summary>
 /// 註冊 API
 /// </summary>
 /// <param name="registerDto"> 使用者傳送的員工註冊資料 </param>
 /// <returns> 註冊完成的員工資料 </returns>
 [HttpPost("register")]
 public async Task<ActionResult> RegisterAsync(RegisterDto registerDto)
 {
 // 驗證註冊資料
 if (string.IsNullOrEmpty(registerDto.Email)
 || string.IsNullOrEmpty(registerDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 先查詢有沒有重複的員工資料
 var employee = await _employeeService.GetEmployeeByEmailAsync(registerDto.Email);

 // 如果沒有就註冊新員工
 var registerResult =
 employee == null &&
 await _employeeService.AddEmployeeAsync(registerDto);

 // 回傳註冊結果
 return registerResult
 ? Ok("Register successfully!")
 : employee != null
 ? BadRequest("User already exists!")
 : BadRequest("Failed to register user");
 }

 /// <summary>
 /// 登入
 /// </summary>
 /// <param name="loginDto"> 使用者的輸入資料 </param>
 /// <returns> 登入結果 </returns>
 [HttpPost("login")]
 public async Task<string> LoginAsync(LoginDto loginDto)
 {
 // 登入資料驗證
 if (string.IsNullOrEmpty(loginDto.Email) ||
 string.IsNullOrEmpty(loginDto.Password))
 return "Please provide 'Email' and 'Password'";

 // 檢查員工帳號
 if (await _employeeService.GetEmployeeByEmailAsync(loginDto.Email) == null)
 return "User does not exist!";

 // 檢查員工密碼並回傳登入結果
 return await _authService.ValidateUserAsync(loginDto)
 ? "jwt-token"
 : "Login failed";
 }
}

基本上，就完成了，下面 JWT 實作的時候會再改成所產生的 JWT，最後因為有注入 IAuthService 驗證相關的服務，所以要去 Program.cs 註冊如下

1
2
3
4
5


#region CustomService
builder.Services
 .AddScoped<IEmployeeService, EmployeeService>()
 .AddScoped<IAuthService, AuthService>();
#endregion

這邊示範用 Postman 進行測試，請先執行專案，確認執行成功後開啟 Postman，並按下「+」新增一個 Request 分頁

將 Request 改成「POST」，並輸入 API 網址，可以參考 測試註冊 章節最後一張圖的網址

下方選擇「Body」，在 Body 下方圈選「raw」，row 旁邊下拉改成「JSON」並輸入要註冊的帳號密碼如下，完成後按下「Send」，結果就會出現在下方，如下圖

1
2
3
4


{
 "email": "",
 "password": ""
}

要測試登入，所以一定要先註冊一個使用者，也順便用 Postman 測試註冊功能

將網址改成登入的 API 網址，測試登入

JWT

接下來要實作產生 JWT 的方法，並將上一節 LoginAsync 方法回傳值改成所產生的 JWT

下圖簡單的說明 JWT 的驗證流程
1, 2, 3 上一節已經實作了，不再說明

如果登入登入成功，就合回傳一個合法的 JWT
使用者需要存取授權的資源時，會將 JWT 傳送至 Server 進行驗證
如果驗證通過，就會回傳授權的資源；
如果未通過有兩種情況
- 正確的 Token，但權限不夠，如：業務部門無法存取會計部門的帳務資料
  會回傳 Http 403
- 錯誤的 Token，如 Token 過期或遭竄改，會回傳 Http 401（未授權）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


┌───────────┐ ┌──────────┐ ┌────────┐
│Client User│ │Web Server│ │Database│
└─────┬─────┘ └────┬─────┘ └───┬────┘
 │ │ │
 │ 1. Login with Username and Password │ │
 │────────────────────────────────────>│ │
 │ │ │
 │ │2. Check user data and validate│
 │ │──────────────────────────────>│
 │ │ │
 │ │ 3. Valid user data │
 │ │<──────────────────────────────│
 │ │ │
 │ 4. Send JWT(Bearer token) │ │
 │<────────────────────────────────────│ │
 │ │ │
 │ 5. Request for protected data │ │
 │ Send Bearer token │ │
 │────────────────────────────────────>│ │
 │ │ │
 │ 6. Token is valid and │ │
 │ Send protected data │ │
 │<────────────────────────────────────│ │
 │ │ │
 │6. Token is invalid or no permission │ │
 │ return Http 401 or Http 403 │ │
 │<────────────────────────────────────│ │
┌─────┴─────┐ ┌────┴─────┐ ┌───┴────┐
│Client User│ │Web Server│ │Database│
└───────────┘ └──────────┘ └────────┘

安裝 JwtBearer

為了產生 JWT 及驗證 JWT，需要安裝這個套件，不過我沒有想到篇幅會這麼長，所以驗證的部分我會拉到下一篇教學，開啟 NuGet，輸入 Microsoft.AspNetCore.Authentication.JwtBearer，並安裝，安裝流程可以參考 安裝套件，記得安裝符合自已的 .NET 版本，我的本機是 .NET 8 所以我只能安裝 8.x.x 的版本，詳細可以參考 NuGet JwtBearer

修改登入方法

由上面的流程圖可以知道，JWT 的驗證，會回傳 Http 的結果，因此要統一每個 API 回傳的型別，原 LoginAsync 方法回傳的登入的相關訊息（string），現在為了回傳 Http XXX 要修改回傳資料的型別如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


/// <summary>
/// 登入
/// </summary>
/// <param name="loginDto"> 使用者的輸入資料 </param>
/// <returns> 登入結果 </returns>
[HttpPost("login")]
// 原本回傳型別是 Task<string> 是上一節為了測試而簡化
// 改成 Task<ActionResult<string>>，為了可以回傳 Http 結果
// Ok, BadRequest 都是繼承自 ActionResult 的類別
// 所以可以用 ActionResult 封裝
// Ok 會變成 Http 200
// BadRequest 會變成 Http 400
public async Task<ActionResult<string>> LoginAsync(LoginDto loginDto)
{
 // 登入資料驗證
 if (string.IsNullOrEmpty(loginDto.Email) ||
 string.IsNullOrEmpty(loginDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 檢查員工帳號
 if (await _employeeService.GetEmployeeByEmailAsync(loginDto.Email) == null)
 return BadRequest("User does not exist!");

 // 檢查員工密碼並回傳登入結果
 if (!await _authService.ValidateUserAsync(loginDto))
 return BadRequest("Login failed!");

 // 產生 Jwt 方法

 return Ok("JWT Token");
}

JWT 設定

回故一下，JWT 所需要的加載的資料內容，參考 JWT Payload，有一些資料是相對靜態的，所以可以設定在 appsettings.json 中，從設定檔中讀取，如 iss（發行單位），到期時間。

這要要特別說明一下 到期時間，通常會是指從 發行 JWT 之後，持續多久（月，天，分），並不是指一個故定的到期時間點，所以這個持續多久是可以固定下來的，因此可以寫在設定檔。如果是某一固定時間點的話，會變成不管什麼時候發行的 Token，都會在那一個時間點失效，即使是在有效期之後發行的也是一樣，會造成還沒發行就失效了，所以不合理。

開啟 appsettings.json，新增「JwtOptions」設定，如明如下

Expiry：有效期限（分），我預設是分鐘，比較方便測試，有需要也可以當成天
Issuer：發行單位，我輸入這個專案的名稱
SecretKey：加密金鑰，隨便輸入的字，不一定要跟我一樣，另外這只是因為教學紀錄的專案，並沒有涉及機密資料，實際的產品應用上，是不能洩漏加密金鑰的

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*",
 "JwtOptions": {
 "Expiry": 5,
 "Issuer": "JWT-Authentication-API",
 "SecretKey": "This-is-secret-key-for-JWT-Authentication"
 }
}

加載 JWT 設定

有兩種方式可以讀取設定檔

使用 Configuration 注入

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 用建構函數傳入
public class TargetClass(IConfiguration configuration)
{
 // 在要被注入的類別中宣告 Configuration 的物件
 private readonly IConfiguration _configuration = configuration;

 public void Foo() {
 // 讀取設定值 "第一層Key:第二層Key"
 var secretKey = _configuration.GetValue<string>("JwtSettings:SecretKey");
 // 或
 // 用 GetSection 方法先取得第一層的物件
 // 再用 GetValue 取得第二層 Key 的設定值
 var secretKey = _configuration.GetSection("JwtSettings").GetValue<string>("SecretKey");

 // 上面兩種寫法效果是一樣的
 }
}

自定義一個設定類別，將設定值物件化

JwtOptions

我採用第二個方法，為強化資料型別的管理，但會比較麻煩，可以自行取舍，在專案下新增 Options 目錄，用來存放設定物件的類別，在目錄下新增一個 JwtOptions.cs，並依 appsettings.json 的相關設定定義資料欄位如下

※ 同樣都是承載資料的模型物件，為什麼不放在 Models 目錄？因為 Settings 或 Options 相關的資料物件只會用在程式中資料的設定，不會與資料庫的資庫互動，這樣語意更清析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


namespace JWT_Authentication_API.Options;

/// <summary>
/// Jwt 的設定物件
/// </summary>
public class JwtOptions
{
 /// <summary>
 /// 有效期限（分），預設 10 分鐘
 /// </summary>
 public int Expiry { get; set; } = 10;

 /// <summary>
 /// 發行單位
 /// </summary>
 public string Issuer { get; set; } = "JWT_Authentication_API";

 /// <summary>
 /// 加密金鑰
 /// </summary>
 public string SecretKey { get; set; } = Guid.NewGuid().ToString();
}

接下來在 Program.cs 中註冊這個自定定的 JwtOption 類別，並封裝在 IOptions 的類別中，在 AddScoped 方法的後面加入註冊方法如下

1
2
3
4
5
6
7


#region CustomService
builder.Services
 .AddScoped<IEmployeeService, EmployeeService>()
 .AddScoped<IAuthService, AuthService>()
 // 註冊這個 JwtOptions 的物件，並封裝成 IOptions 型別，讓其他類別可以注入使用
 .Configure<JwtOptions>(builder.Configuration.GetSection(nameof(JwtOptions)));
#endregion

設定的前置就完成了，可以在 Jwt 相關類別中使用

產生 JWT

為了產生合法的 JWT，在專案下新增一個 Helper 目錄，用來存放輔助的相關類別，在目錄下新增一個 JwtHelper.cs 用來加載 JWT 的設定並產生 JWT

注入 JwtOptions

先注入 JWT 的相關設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using JWT_Authentication_API.Options;
using Microsoft.Extensions.Options;

namespace JWT_Authentication_API.Helper;

/// <summary>
/// JSON Web Token 輔助工具
/// 注入 JwtOptions
/// </summary>
public class JwtHelper(IOptions<JwtOptions> jwtOptions)
{
 /// <summary>
 /// Jwt 的相關設定
 /// </summary>
 private readonly JwtOptions _jwtOptions = jwtOptions.Value;
}

將使用者登入資訊加入 Payload 中

使用者資訊會使用 List<Claim> 中，一個 Claim 就是使用者的其中一項資料，可以想成 出國用的護照

護照號碼：是一個 Claim
中文姓名：是一個 Claim
英文姓名（拼音）：是一個 Claim
照片：是一個 Claim
國籍：是一個 Claim

而上面這麼多個 Claim 就會組成護照，變成出國用的身分證明，只是在網路的世界，使用者的身份證明變成了 List<Claim> 型式，而在 JWT 的應用場景中，Claim 變成了 JWT 所需要的資料，在 JwtHelper 中新增一個 CreateJwt 方法，並傳入使用者資料，寫入 payload，如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


/// <summary>
/// 產生 JWT
/// </summary>
/// <param name="loginDto"> 使用者的登入資訊 </param>
/// <returns> JSON Web Token </returns>
public string CreateJwt(LoginDto loginDto)
{
 var now = DateTimeOffset.UtcNow;

 // 設定 Payload
 List<Claim> claims = [
 // 發行單位
 new(JwtRegisteredClaimNames.Iss, _jwtOptions.Issuer),
 // 使用者帳號作為識別
 new(JwtRegisteredClaimNames.Sub, loginDto.Email),
 // Token 的有效期限，從現在開始到 5 分鐘後
 new(JwtRegisteredClaimNames.Exp, $"{now.AddMinutes(_jwtOptions.Expiry)
 .ToUnixTimeSeconds()}"),
 // 這個 JWT 的識別
 new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
 // 這個 JWT 的發行時間
 new(JwtRegisteredClaimNames.Iat, $"{now.ToUnixTimeSeconds()}")
 ];
 // 產生使用者身分證明
 ClaimsIdentity userClaimsIdentity = new(claims);
 // 產生私鑰供後續加密使用
 SymmetricSecurityKey securityKey = new(Encoding.UTF8.GetBytes(_jwtOptions.SecretKey));
 // 產生數位簽章憑證，使用 SHA256 加密演算
 SigningCredentials credentials = new(securityKey, SecurityAlgorithms.HmacSha256);

 // 產生 JWT
 JwtSecurityToken securityToken = new(
 issuer: _jwtOptions.Issuer, // issuer
 claims: userClaimsIdentity.Claims, // payload
 signingCredentials: credentials, // signature
 expires: now.AddMinutes(_jwtOptions.Expiry).UTCDateTime); // expiry time

 // 輸出 JWT 並轉換成字串
 return new JwtSecurityTokenHandler().WriteToken(securityToken);
}

在 Program.cs 中，註冊 JwtHelper，因為 JwtHelper 的設定是固定不變的，所以不像 EmployeeService 只會存在某些特定的 Controller 中，一但 Request 的生命週期結束，依賴的 Service 就必需要結束，所以 JwtHelper 要使用 AddSingleton 來註冊

1
2


// 註冊 JwtHelper
builder.Services.AddSingleton<JwtHelper>();

回到 AuthController 將產生 JWT 的部分補上

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


/// <summary>
/// 將 AuthController 宣告成為 ApiController
/// 並定義路由規則（網址）=> domain/api/auth
/// </summary>
/// <param name="employeeService"> 員工資料存取服務 </param>
/// <param name="authService"> 登入驗證服務 </param>
/// <param name="jwtHelper"> JWT 輔助工具 </param>
[ApiController, Route("api/[controller]")]
public class AuthController(
 IEmployeeService employeeService,
 IAuthService authService,
 JwtHelper jwtHelper) : Controller
{
 /// <summary>
 /// 員工資料存取的服務
 /// </summary>
 private readonly IEmployeeService _employeeService = employeeService;
 /// <summary>
 /// 登入驗證的服務
 /// </summary>
 private readonly IAuthService _authService = authService;
 /// <summary>
 /// JWT 輔助工具，負責生成 JWT
 /// </summary>
 private readonly JwtHelper _jwtHelper = jwtHelper;

 #region 註冊
 ......
 #endregion

 #region 登入
 /// <summary>
 /// 登入
 /// </summary>
 /// <param name="loginDto"> 使用者的輸入資料 </param>
 /// <returns> 登入結果 </returns>
 [HttpPost("login")]
 public async Task<ActionResult<string>> LoginAsync(LoginDto loginDto)
 {
 // 登入資料驗證
 if (string.IsNullOrEmpty(loginDto.Email) ||
 string.IsNullOrEmpty(loginDto.Password))
 return BadRequest("Please provide 'Email' and 'Password'");

 // 檢查員工帳號
 if (await _employeeService.GetEmployeeByEmailAsync(loginDto.Email) == null)
 return BadRequest("User does not exist!");

 // 檢查員工密碼並回傳登入結果
 if (!await _authService.ValidateUserAsync(loginDto))
 return BadRequest("Login failed!");

 // 產生 Jwt
 var jwt = _jwtHelper.CreateJwt(loginDto);

 return Ok(jwt);
 }
 #endregion
}

驗證 JWT

完成 JWT 的部分後，就可以來測試了，由於在 Login．已經註冊過 peter 這個帳號了，現在用 peter 這個帳號來測試會不會回傳 JWT，也可以順便知道資料庫的運作，是不是真會存在 peter 這筆帳號資料

如果有看到 JWT 成功回傳，就代表登入方法成功了，同時也確認資料庫存取是沒有問題的接著請把 JWT 複製，貼到 JWT IO 的網站，它會協助驗證 JWT 的格式有沒有正確

由上面的結果可以知道，JWT 結果和我寫入的一樣，這樣登入功能就完成了，這邊順便說一下，右下方的 Secret 驗證，其實是驗證金鑰的正確性，一般來說不會把金鑰公開，不過我這邊為了範例，我測試一下，把 appsettings.json 的 SecretKey 複製貼上

會發現 SecretKey 也是 ok 的，這樣就驗證完成了

登出

最後要來做登出功能了，這邊採用比較簡單且直觀的方式「黑名單」，也就是將已經使用過的 JWT 寫入黑名單來代表登出，這樣就無法再次使用一樣的 token 進行其他操作。

為了建立黑名單，要先建立一個「黑名單的資料模型」，在 Entities 目錄新增 TokenBlackList.cs 如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace JWT_Authentication_API.Entities;

/// <summary>
/// JWT 的黑名單
/// </summary>
public class TokenBlackList
{
 /// <summary>
 /// 資料識別（PK）
 /// </summary>
 [Required, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
 public Guid Id { get; set; }
 /// <summary>
 /// 使用過的 Token
 /// </summary>
 [Required]
 public string Token { get; set; } = string.Empty;
 /// <summary>
 /// 資料新增的時間，也是 Token 過期的時間
 /// </summary>
 public DateTimeOffset CreateTime { get; set; } = DateTimeOffset.Now;
}

接著在 AppDbContext.cs 加入 TokenBlackList 的對映參考，加完程式碼會變成下面這樣

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


using Microsoft.EntityFrameworkCore;

namespace JWT_Authentication_API.Entities;

/// <summary>
/// Database Context
/// </summary>
/// <param name="options"></param>
public class AppDbContext(DbContextOptions<AppDbContext> options)
 : DbContext(options)
{
 /// <summary>
 /// 員工資料表
 /// </summary>
 public DbSet<Employee> Employees { get; set; }
 /// <summary>
 /// Token 黑名單資料表
 /// </summary>
 public DbSet<TokenBlackList> TokenBlackLists { get; set; }
}

然後參考 新增 Migration 加入新的資料表，然後為了要新增 Token 到黑名單，再新增相關服務及介面
在 Interfaces 目錄下新增 ITokenService.cs
在 Services 目錄下新增 TokenService.cs 並實作 ITokenService

ITokenService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


namespace JWT_Authentication_API.Interfaces;

/// <summary>
/// Token 相關服務的介面
/// </summary>
public interface ITokenService
{
 /// <summary>
 /// 新增 token 到黑名單
 /// </summary>
 /// <param name="token"> 要新增的 token </param>
 /// <returns> 新增結果 </returns>
 Task<bool> AddTokenToTokenBlackListAsync(string token);
}

TokenService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


using JWT_Authentication_API.Entities;
using JWT_Authentication_API.Interfaces;

namespace JWT_Authentication_API.Services;
/// <summary>
/// Token 資料存取服務
/// </summary>
/// <param name="context"> 資料庫物件 </param>
public class TokenService(AppDbContext context): ITokenService
{
 /// <summary>
 /// 資料庫物件
 /// </summary>
 private readonly AppDbContext _appDb = context;

 /// <summary>
 /// 新增 Token 到黑名單
 /// </summary>
 /// <param name="token"> 要新增的 Token </param>
 /// <returns> 新增結果 </returns>
 public async Task<bool> AddTokenToTokenBlackListAsync(string token)
 {
 await _appDb.TokenBlackLists.AddAsync(new TokenBlackList { Token = token });
 var result = await _appDb.SaveChangesAsync();

 return result > 0;
 }
}

註冊 TokenService

Program.cs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


#region CustomService
builder.Services
 // 註冊 EmployeeService
 .AddScoped<IEmployeeService, EmployeeService>()
 // 註冊 AuthService
 .AddScoped<IAuthService, AuthService>()
 // 註冊 TokenService
 .AddScoped<ITokenService, TokenService>()
 // 註冊這個 JwtOptions 的物件，並封裝成 IOptions 型別，讓其他類別可以注入使用
 .Configure<JwtOptions>(builder.Configuration.GetSection(nameof(JwtOptions)));
// 註冊 JwtHelper
builder.Services.AddSingleton<JwtHelper>();
#endregion

Logout

回到 AuthController.cs 加入 ITokenService 的注入，並新增 LogoutAsync 方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


/// <summary>
/// 將 AuthController 宣告成為 ApiController
/// 並定義路由規則（網址）=> domain/api/auth
/// </summary>
/// <param name="employeeService"> 員工資料存取服務 </param>
/// <param name="authService"> 登入驗證服務 </param>
/// <param name="jwtHelper"> JWT 輔助工具 </param>
[ApiController, Route("api/[controller]")]
public class AuthController(
 IEmployeeService employeeService,
 IAuthService authService,
 ITokenService tokenService,
 JwtHelper jwtHelper) : Controller
{
 ......

 /// <summary>
 /// Token 相關服務
 /// </summary>
 private readonly ITokenService _tokenService = tokenService;

 #region 註冊
 ......
 #endregion

 #region 登入
 ......
 #endregion

 #region 登出
 /// <summary>
 /// 登出
 /// </summary>
 /// <returns> 登出結果 </returns>
 [HttpPost("logout")]
 public async Task<IActionResult> LogoutAsync()
 {
 // 從 header 讀取 JWT
 var token = $"{HttpContext.Request.Headers.Authorization}"
 .Replace("Bearer", string.Empty, StringComparison.OrdinalIgnoreCase)
 .Trim();
 if (string.IsNullOrEmpty(token))
 return BadRequest("Not token provided!");

 // 將 JWT 加入黑名單
 var result = await _tokenService.AddTokenToTokenBlackListAsync(token);
 if (!result) return BadRequest("Logout failed!");

 return Ok("Logout successfully!");
 }
 #endregion
}

測試登出

最後來測試登出功能，啟動專案並執行 Postman，網址輸入登出的，下面的頁籤選「Authorization」，Type 選第三個「Bearer Token」

接著按下「Send」

會發現出現沒 Token 的訊息，因為我們沒有提供 Token（上面的輸入框），同時也代表登出的檢查有成功，現在先去登入取得一個 Token 並複製下來，參考 驗證 JWT，貼上「Token 輸入框」，按下 Send

如果有看到登出訊息就是成功了

到這邊，註冊、登入、登出就完成了，下篇下會介紹及實作 Refresh Token，並將專案加入角色驗證，讓專案更完整。