系列導航及源代碼
需求
在.NET Web API開發中還有一個很重要的需求是關於身份認證和授權的，這個主題非常大，所以本文不打算面面俱到地介紹整個主題，而僅使用.NET框架自帶的認證和授權中間件去實現基於JWT的身份認證和授權功能。一些關於這個主題的基本概念也不會花很多的篇幅去講解，我們還是專注在實現上。
目標
為TodoList項目增加身份認證和授權功能。
原理與思路
為了實現身份認證和授權功能，我們需要使用.NET自帶的Authentication和Authorization組件。在本文中我們不會涉及Identity Server的相關內容，這是另一個比較大的主題，因為許可證的變更，Identity Server 4將不再能夠免費應用於盈利超過一定限額的商業應用中，詳情見官網IdentityServer。微軟同時也在將廣泛使用的IdentityServer的相關功能逐步集成到框架中：ASP.NET Core 6 and Authentication Servers，在本文中同樣暫不會涉及。
實現
引入Identity組件
我們在Infrastructure項目中添加以下Nuget包：
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.1" />
<PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="6.0.1" />
並新建Identity目錄用於存放有關認證和授權的具體功能，首先添加用戶類ApplicationUser：
ApplicationUser.cs
using Microsoft.AspNetCore.Identity;
namespace TodoList.Infrastructure.Identity;
public class ApplicationUser : IdentityUser
{
// 不做定制化實現，僅使用原生功能
}
由於我們希望使用現有的SQL Server數據庫來存儲認證相關的信息，所以還需要修改DbContext：
TodoListDbContext.cs
public class TodoListDbContext : IdentityDbContext<ApplicationUser>
{
private readonly IDomainEventService _domainEventService;
public TodoListDbContext(
DbContextOptions<TodoListDbContext> options,
IDomainEventService domainEventService) : base(options)
{
_domainEventService = domainEventService;
}
// 省略其他...
}
為了后面演示的方便，我們還可以在添加種子數據的邏輯里增加內置用戶數據：
TodoListDbContextSeed.cs
// 省略其他...
public static async Task SeedDefaultUserAsync(UserManager<ApplicationUser> userManager, RoleManager<IdentityRole> roleManager)
{
var administratorRole = new IdentityRole("Administrator");
if (roleManager.Roles.All(r => r.Name != administratorRole.Name))
{
await roleManager.CreateAsync(administratorRole);
}
var administrator = new ApplicationUser { UserName = "admin@localhost", Email = "admin@localhost" };
if (userManager.Users.All(u => u.UserName != administrator.UserName))
{
// 創建的用戶名為admin@localhost，密碼是admin123，角色是Administrator
await userManager.CreateAsync(administrator, "admin123");
await userManager.AddToRolesAsync(administrator, new[] { administratorRole.Name });
}
}
並在ApplicationStartupExtensions中修改：
ApplicationStartupExtensions.cs
public static class ApplicationStartupExtensions
{
public static async Task MigrateDatabase(this WebApplication app)
{
using var scope = app.Services.CreateScope();
var services = scope.ServiceProvider;
try
{
var context = services.GetRequiredService<TodoListDbContext>();
context.Database.Migrate();
var userManager = services.GetRequiredService<UserManager<ApplicationUser>>();
var roleManager = services.GetRequiredService<RoleManager<IdentityRole>>();
// 生成內置用戶
await TodoListDbContextSeed.SeedDefaultUserAsync(userManager, roleManager);
// 省略其他...
}
catch (Exception ex)
{
throw new Exception($"An error occurred migrating the DB: {ex.Message}");
}
}
}
最后我們需要來修改DependencyInjection部分，以引入身份認證和授權服務：
DependencyInjection.cs
// 省略其他....
// 配置認證服務
// 配置認證服務
services
.AddIdentity<ApplicationUser, IdentityRole>(o =>
{
o.Password.RequireDigit = true;
o.Password.RequiredLength = 6;
o.Password.RequireLowercase = true;
o.Password.RequireUppercase = false;
o.Password.RequireNonAlphanumeric = false;
o.User.RequireUniqueEmail = true;
})
.AddEntityFrameworkStores<TodoListDbContext>()
.AddDefaultTokenProviders();
添加認證服務
在Applicaiton/Common/Interfaces中添加認證服務接口IIdentityService：
IIdentityService.cs
namespace TodoList.Application.Common.Interfaces;
public interface IIdentityService
{
// 出於演示的目的，只定義以下方法，實際使用的認證服務會提供更多的方法
Task<string> CreateUserAsync(string userName, string password);
Task<bool> ValidateUserAsync(UserForAuthentication userForAuthentication);
Task<string> CreateTokenAsync();
}
然后在Infrastructure/Identity中實現IIdentityService接口：
IdentityService.cs
namespace TodoList.Infrastructure.Identity;
public class IdentityService : IIdentityService
{
private readonly ILogger<IdentityService> _logger;
private readonly IConfiguration _configuration;
private readonly UserManager<ApplicationUser> _userManager;
private ApplicationUser? User;
public IdentityService(
ILogger<IdentityService> logger,
IConfiguration configuration,
UserManager<ApplicationUser> userManager)
{
_logger = logger;
_configuration = configuration;
_userManager = userManager;
}
public async Task<string> CreateUserAsync(string userName, string password)
{
var user = new ApplicationUser
{
UserName = userName,
Email = userName
};
await _userManager.CreateAsync(user, password);
return user.Id;
}
public async Task<bool> ValidateUserAsync(UserForAuthentication userForAuthentication)
{
User = await _userManager.FindByNameAsync(userForAuthentication.UserName);
var result = User != null && await _userManager.CheckPasswordAsync(User, userForAuthentication.Password);
if (!result)
{
_logger.LogWarning($"{nameof(ValidateUserAsync)}: Authentication failed. Wrong username or password.");
}
return result;
}
public async Task<string> CreateTokenAsync()
{
// 暫時還不來實現這個方法
throw new NotImplementedException();
}
}
並在DependencyInjection中進行依賴注入：
DependencyInjection.cs
// 省略其他...
// 注入認證服務
services.AddTransient<IIdentityService, IdentityService>();
現在我們來回顧一下已經完成的部分：我們配置了應用程序使用內建的Identity服務並使其使用已有的數據庫存儲；我們生成了種子用戶數據；還實現了認證服務的功能。
在繼續下一步之前，我們需要對數據庫做一次Migration，使認證鑒權相關的數據表生效：
$ dotnet ef database update -p src/TodoList.Infrastructure/TodoList.Infrastructure.csproj -s src/TodoList.Api/TodoList.Api.csproj
Build started...
Build succeeded.
[14:04:02 INF] Entity Framework Core 6.0.1 initialized 'TodoListDbContext' using provider 'Microsoft.EntityFrameworkCore.SqlServer:6.0.1' with options: MigrationsAssembly=TodoList.Infrastructure, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
# 創建相關數據表...
[14:04:03 INF] Executed DbCommand (43ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
CREATE TABLE [AspNetRoles] (
[Id] nvarchar(450) NOT NULL,
[Name] nvarchar(256) NULL,
[NormalizedName] nvarchar(256) NULL,
[ConcurrencyStamp] nvarchar(max) NULL,
CONSTRAINT [PK_AspNetRoles] PRIMARY KEY ([Id])
);
# 省略中間的部分..
[14:04:03 INF] Executed DbCommand (18ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20220108060343_AddIdentities', N'6.0.1');
Done.
運行Api程序，然后去數據庫確認一下生成的數據表：
種子用戶：
以及角色：
到目前為止，我已經集成了Identity框架，接下來我們開始實現基於JWT的認證和API的授權功能：
使用JWT認證和定義授權方式
在Infrastructure項目的DependencyInjection中添加JWT認證配置：
DependencyInjection.cs
// 省略其他...
// 添加認證方法為JWT Token認證
services
.AddAuthentication(opt =>
{
opt.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
opt.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = true,
ValidateAudience = true,
ValidateLifetime = true,
ValidateIssuerSigningKey = true,
ValidIssuer = configuration.GetSection("JwtSettings")["validIssuer"],
ValidAudience = configuration.GetSection("JwtSettings")["validAudience"],
// 出於演示的目的，我將SECRET值在這里fallback成了硬編碼的字符串，實際環境中，最好是需要從環境變量中進行獲取，而不應該寫在代碼中
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("SECRET") ?? "TodoListApiSecretKey"))
};
});
// 添加授權Policy是基於角色的，策略名稱為OnlyAdmin，策略要求具有Administrator角色
services.AddAuthorization(options =>
options.AddPolicy("OnlyAdmin", policy => policy.RequireRole("Administrator")));
引入認證授權中間件
在Api項目的Program中，MapControllers上面引入：
Program.cs
// 省略其他...
app.UseAuthentication();
app.UseAuthorization();
添加JWT配置
appsettings.Development.json
"JwtSettings": {
"validIssuer": "TodoListApi",
"validAudience": "http://localhost:5050",
"expires": 5
}
增加認證用戶Model
在Application/Common/Models中添加用於用戶認證的類型：
UserForAuthentication.cs
using System.ComponentModel.DataAnnotations;
namespace TodoList.Application.Common.Models;
public record UserForAuthentication
{
[Required(ErrorMessage = "username is required")]
public string? UserName { get; set; }
[Required(ErrorMessage = "password is required")]
public string? Password { get; set; }
}
實現認證服務CreateToken方法
因為本篇文章我們沒有使用集成的IdentityServer組件，而是應用程序自己去發放Token，那就需要我們去實現CreateTokenAsync方法：
IdentityService.cs
// 省略其他...
public async Task<string> CreateTokenAsync()
{
var signingCredentials = GetSigningCredentials();
var claims = await GetClaims();
var tokenOptions = GenerateTokenOptions(signingCredentials, claims);
return new JwtSecurityTokenHandler().WriteToken(tokenOptions);
}
private SigningCredentials GetSigningCredentials()
{
// 出於演示的目的，我將SECRET值在這里fallback成了硬編碼的字符串，實際環境中，最好是需要從環境變量中進行獲取，而不應該寫在代碼中
var key = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("SECRET") ?? "TodoListApiSecretKey");
var secret = new SymmetricSecurityKey(key);
return new SigningCredentials(secret, SecurityAlgorithms.HmacSha256);
}
private async Task<List<Claim>> GetClaims()
{
// 演示了返回用戶名和Role兩類Claims
var claims = new List<Claim>
{
new(ClaimTypes.Name, User!.UserName)
};
var roles = await _userManager.GetRolesAsync(User);
claims.AddRange(roles.Select(role => new Claim(ClaimTypes.Role, role)));
return claims;
}
private JwtSecurityToken GenerateTokenOptions(SigningCredentials signingCredentials, List<Claim> claims)
{
// 配置JWT選項
var jwtSettings = _configuration.GetSection("JwtSettings");
var tokenOptions = new JwtSecurityToken
(
jwtSettings["validIssuer"],
jwtSettings["validAudience"],
claims,
expires: DateTime.Now.AddMinutes(Convert.ToDouble(jwtSettings["expires"])),
signingCredentials: signingCredentials
);
return tokenOptions;
}
添加認證接口
在Api項目中新建一個Controller用於實現獲取Token的接口：
AuthenticationController.cs
using Microsoft.AspNetCore.Mvc;
using TodoList.Application.Common.Interfaces;
using TodoList.Application.Common.Models;
namespace TodoList.Api.Controllers;
[ApiController]
public class AuthenticationController : ControllerBase
{
private readonly IIdentityService _identityService;
private readonly ILogger<AuthenticationController> _logger;
public AuthenticationController(IIdentityService identityService, ILogger<AuthenticationController> logger)
{
_identityService = identityService;
_logger = logger;
}
[HttpPost("login")]
public async Task<IActionResult> Authenticate([FromBody] UserForAuthentication userForAuthentication)
{
if (!await _identityService.ValidateUserAsync(userForAuthentication))
{
return Unauthorized();
}
return Ok(new { Token = await _identityService.CreateTokenAsync() });
}
}
保護API資源
我們准備使用創建TodoList接口來演示認證和授權功能，所以添加屬性如下：
// 省略其他...
[HttpPost]
// 演示使用Policy的授權
[Authorize(Policy = "OnlyAdmin")]
[ServiceFilter(typeof(LogFilterAttribute))]
public async Task<ApiResponse<Domain.Entities.TodoList>> Create([FromBody] CreateTodoListCommand command)
{
return ApiResponse<Domain.Entities.TodoList>.Success(await _mediator.Send(command));
}
驗證
驗證1: 驗證直接訪問創建TodoList接口
啟動Api項目，直接執行創建TodoList的請求：
得到了401 Unauthorized結果。
驗證2: 獲取Token
請求獲取Token的接口：
可以看到我們已經拿到了JWT Token，把這個Token放到JWT解析一下可以看到：
主要在payload中可以看到兩個Claims和其他配置的信息。
驗證3: 攜帶Token訪問創建TodoList接口
選擇Bearer Token驗證方式並填入獲取到的Token，再次請求創建TodoList:
驗證4: 更換Policy
修改Infrastructure/DependencyInjection.cs
// 省略其他...
// 添加授權Policy是基於角色的，策略名稱為OnlyAdmin，策略要求具有Administrator角色
services.AddAuthorization(options =>
{
options.AddPolicy("OnlyAdmin", policy => policy.RequireRole("Administrator"));
options.AddPolicy("OnlySuper", policy => policy.RequireRole("SuperAdmin"));
});
並修改創建TodoList接口的授權Policy：
// 省略其他...
[Authorize(Policy = "OnlySuper")]
還是使用admin@locahost用戶的用戶名和密碼獲取最新的Token后，攜帶Token請求創建新的TodoList：
得到了403 Forbidden返回，並且從日志中我們可以看到：
告訴我們需要一個具有SuperAdmin角色的用戶的合法Token才會被授權。
那么到此為止，我們已經實現了基於.NET自帶的Identity框架，發放Token，完成認證和授權的功能。
一點擴展
關於在.NET Web API項目中進行認證和授權的主題非常龐大，首先是認證的方式可以有很多種，除了我們在本文中演示的基於JWT Token的認證方式以外，還有OpenId認證，基於Azure Active Directory的認證，基於OAuth協議的認證等等；其次是關於授權的方式也有很多種，可以是基於角色的授權，可以是基於Claims的授權，可以是基於Policy的授權，也可以自定義更多的授權方式。然后是具體的授權服務器的實現，有基於Identity Server 4的實現，當然在其更改過協議后，我們可以轉而使用.NET中移植進來的IdentityServer組件實現，配置的方式也有很多。
由於IdentityServer涉及的知識點過於龐雜，所以本文並沒有試圖全部講到，考慮后面單獨出一個系列來講關於IdentityServer在.NET 6 Web API開發中的應用。
總結
在本文中，我們實現了基於JWT Token的認證和授權。下一篇文章我們來看看為什么需要以及如何實現Refresh Token機制。