.NET 6實現(xiàn)基于JWT的Identity功能方法詳解

更新時間：2022年01月11日 08:45:25 作者：CODE4NOTHING

在.NET Web API開發(fā)中還有一個很重要的需求是關(guān)于身份認證和授權(quán)的。本文將介紹使用.NET框架自帶的認證和授權(quán)中間件去實現(xiàn)基于JWT的身份認證和授權(quán)功能的方法詳解，需要的可以參考一下

需求

在.NET Web API開發(fā)中還有一個很重要的需求是關(guān)于身份認證和授權(quán)的，這個主題非常大，所以本文不打算面面俱到地介紹整個主題，而僅使用.NET框架自帶的認證和授權(quán)中間件去實現(xiàn)基于JWT的身份認證和授權(quán)功能。一些關(guān)于這個主題的基本概念也不會花很多的篇幅去講解，我們還是專注在實現(xiàn)上。

目標

為TodoList項目增加身份認證和授權(quán)功能。

原理與思路

為了實現(xiàn)身份認證和授權(quán)功能，我們需要使用.NET自帶的Authentication和Authorization組件。在本文中我們不會涉及Identity Server的相關(guān)內(nèi)容，這是另一個比較大的主題，因為許可證的變更，Identity Server 4將不再能夠免費應(yīng)用于盈利超過一定限額的商業(yè)應(yīng)用中，詳情見官網(wǎng)IdentityServer。微軟同時也在將廣泛使用的IdentityServer的相關(guān)功能逐步集成到框架中：ASP.NET Core 6 and Authentication Servers，在本文中同樣暫不會涉及。

實現(xiàn)

引入Identity組件

我們在Infrastructure項目中添加以下Nuget包：

<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.1" />
<PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="6.0.1" />

并新建Identity目錄用于存放有關(guān)認證和授權(quán)的具體功能，首先添加用戶類ApplicationUser：

ApplicationUser.cs

using Microsoft.AspNetCore.Identity;

namespace TodoList.Infrastructure.Identity;

public class ApplicationUser : IdentityUser
{
    // 不做定制化實現(xiàn)，僅使用原生功能
}

由于我們希望使用現(xiàn)有的SQL Server數(shù)據(jù)庫來存儲認證相關(guān)的信息，所以還需要修改DbContext：

TodoListDbContext.cs

public class TodoListDbContext : IdentityDbContext<ApplicationUser>
{
    private readonly IDomainEventService _domainEventService;

    public TodoListDbContext(
        DbContextOptions<TodoListDbContext> options,
        IDomainEventService domainEventService) : base(options)
    {
        _domainEventService = domainEventService;
    }
    // 省略其他...
}

為了后面演示的方便，我們還可以在添加種子數(shù)據(jù)的邏輯里增加內(nèi)置用戶數(shù)據(jù)：

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))
    {
        // 創(chuàng)建的用戶名為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>>();
            // 生成內(nèi)置用戶
            await TodoListDbContextSeed.SeedDefaultUserAsync(userManager, roleManager);
            // 省略其他...
        }
        catch (Exception ex)
        {
            throw new Exception($"An error occurred migrating the DB: {ex.Message}");
        }
    }
}

最后我們需要來修改DependencyInjection部分，以引入身份認證和授權(quán)服務(wù)：

DependencyInjection.cs

// 省略其他....
// 配置認證服務(wù)
// 配置認證服務(wù)
services
    .AddDefaultIdentity<ApplicationUser>(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;
    })
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<TodoListDbContext>()
    .AddDefaultTokenProviders();

添加認證服務(wù)

在Applicaiton/Common/Interfaces中添加認證服務(wù)接口IIdentityService：

IIdentityService.cs

namespace TodoList.Application.Common.Interfaces;

public interface IIdentityService
{
    // 出于演示的目的，只定義以下方法，實際使用的認證服務(wù)會提供更多的方法
    Task<string> CreateUserAsync(string userName, string password);
    Task<bool> ValidateUserAsync(UserForAuthentication userForAuthentication);
    Task<string> CreateTokenAsync();
}

然后在Infrastructure/Identity中實現(xiàn)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()
    {
        // 暫時還不來實現(xiàn)這個方法
        throw new NotImplementedException();
    }
}

并在DependencyInjection中進行依賴注入：

DependencyInjection.cs

// 省略其他...
// 注入認證服務(wù)
services.AddTransient<IIdentityService, IdentityService>();

現(xiàn)在我們來回顧一下已經(jīng)完成的部分：我們配置了應(yīng)用程序使用內(nèi)建的Identity服務(wù)并使其使用已有的數(shù)據(jù)庫存儲；我們生成了種子用戶數(shù)據(jù)；還實現(xiàn)了認證服務(wù)的功能。

在繼續(xù)下一步之前，我們需要對數(shù)據(jù)庫做一次Migration，使認證鑒權(quán)相關(guān)的數(shù)據(jù)表生效：

$ 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
# 創(chuàng)建相關(guān)數(shù)據(jù)表...
[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程序，然后去數(shù)據(jù)庫確認一下生成的數(shù)據(jù)表：

種子用戶：

以及角色：

到目前為止，我已經(jīng)集成了Identity框架，接下來我們開始實現(xiàn)基于JWT的認證和API的授權(quán)功能：

使用JWT認證和定義授權(quán)方式

在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成了硬編碼的字符串，實際環(huán)境中，最好是需要從環(huán)境變量中進行獲取，而不應(yīng)該寫在代碼中
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("SECRET") ?? "TodoListApiSecretKey"))
        };
    });

// 添加授權(quán)Policy是基于角色的，策略名稱為OnlyAdmin，策略要求具有Administrator角色
services.AddAuthorization(options => 
    options.AddPolicy("OnlyAdmin", policy => policy.RequireRole("Administrator")));

引入認證授權(quán)中間件

在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; }
}

實現(xiàn)認證服務(wù)CreateToken方法

因為本篇文章我們沒有使用集成的IdentityServer組件，而是應(yīng)用程序自己去發(fā)放Token，那就需要我們?nèi)崿F(xiàn)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成了硬編碼的字符串，實際環(huán)境中，最好是需要從環(huán)境變量中進行獲取，而不應(yīng)該寫在代碼中
    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用于實現(xiàn)獲取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資源

我們準備使用創(chuàng)建TodoList接口來演示認證和授權(quán)功能，所以添加屬性如下：

// 省略其他...
[HttpPost]
// 演示使用Policy的授權(quán)
[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: 驗證直接訪問創(chuàng)建TodoList接口

啟動Api項目，直接執(zhí)行創(chuàng)建TodoList的請求：

得到了401 Unauthorized結(jié)果。

驗證2: 獲取Token

請求獲取Token的接口：

可以看到我們已經(jīng)拿到了JWT Token，把這個Token放到JWT解析一下可以看到：

主要在payload中可以看到兩個Claims和其他配置的信息。

驗證3: 攜帶Token訪問創(chuàng)建TodoList接口

選擇Bearer Token驗證方式并填入獲取到的Token，再次請求創(chuàng)建TodoList:

驗證4: 更換Policy

修改Infrastructure/DependencyInjection.cs

// 省略其他...
// 添加授權(quán)Policy是基于角色的，策略名稱為OnlyAdmin，策略要求具有Administrator角色
services.AddAuthorization(options =>
{
    options.AddPolicy("OnlyAdmin", policy => policy.RequireRole("Administrator"));
    options.AddPolicy("OnlySuper", policy => policy.RequireRole("SuperAdmin"));
});

并修改創(chuàng)建TodoList接口的授權(quán)Policy：

// 省略其他...
[Authorize(Policy = "OnlySuper")]

還是使用admin@locahost用戶的用戶名和密碼獲取最新的Token后，攜帶Token請求創(chuàng)建新的TodoList：

得到了403 Forbidden返回，并且從日志中我們可以看到：

告訴我們需要一個具有SuperAdmin角色的用戶的合法Token才會被授權(quán)。

那么到此為止，我們已經(jīng)實現(xiàn)了基于.NET自帶的Identity框架，發(fā)放Token，完成認證和授權(quán)的功能。

一點擴展

關(guān)于在.NET Web API項目中進行認證和授權(quán)的主題非常龐大，首先是認證的方式可以有很多種，除了我們在本文中演示的基于JWT Token的認證方式以外，還有OpenId認證，基于Azure Active Directory的認證，基于OAuth協(xié)議的認證等等；其次是關(guān)于授權(quán)的方式也有很多種，可以是基于角色的授權(quán)，可以是基于Claims的授權(quán)，可以是基于Policy的授權(quán)，也可以自定義更多的授權(quán)方式。然后是具體的授權(quán)服務(wù)器的實現(xiàn)，有基于Identity Server 4的實現(xiàn)，當然在其更改過協(xié)議后，我們可以轉(zhuǎn)而使用.NET中移植進來的IdentityServer組件實現(xiàn)，配置的方式也有很多。

由于IdentityServer涉及的知識點過于龐雜，所以本文并沒有試圖全部講到，考慮后面單獨出一個系列來講關(guān)于IdentityServer在.NET 6 Web API開發(fā)中的應(yīng)用。