使用.NET 6開發TodoList應用(24)——實作基于JWT的Identity功能-有解無憂

系列導航及源代碼

使用.NET 6開發TodoList應用文章索引

需求

在.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機制，

參考資料

IdentityServer
ASP.NET Core 6 and Authentication Servers

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/412727.html

標籤：.NET Core

上一篇：使用.NET 6開發TodoList應用(23)——實作請求限流

下一篇：使用.NET 6開發TodoList應用(25)——實作RefreshToken