IAuthenticationHandler 接口

IAuthenticationHandler 接口是 ASP.NET Core 中用于实现自定义身份验证方案的一个核心接口。它定义了处理身份验证（authentication）的基本机制，包括验证凭证、处理身份验证失败、签入和签出等操作。

ASP.NET Core 中的身份验证（Authentication）机制是基于中间件的，而 IAuthenticationHandler 接口就是实现这种身份验证机制的关键。

`IAuthenticationHandler` 接口的主要方法

IAuthenticationHandler 接口有以下几个核心方法，它们定义了处理身份验证的生命周期：

public interface IAuthenticationHandler
{
    Task<AuthenticateResult> AuthenticateAsync();
    Task ChallengeAsync(AuthenticationProperties properties);
    Task ForbidAsync(AuthenticationProperties properties);
    Task InitializeAsync(AuthenticationScheme scheme, HttpContext context);
}

1. `Task InitializeAsync(AuthenticationScheme scheme, HttpContext context)`

作用: 初始化身份验证处理程序，并与当前的 HTTP 请求上下文关联。
参数:
- AuthenticationScheme scheme: 提供当前处理程序所属的身份验证方案的名称和配置。
- HttpContext context: 当前 HTTP 请求的上下文。
用途: 该方法通常在每个请求的开头调用，用于初始化处理程序，例如将上下文与身份验证方案进行绑定。

2. `Task<AuthenticateResult> AuthenticateAsync()`

作用: 处理身份验证并返回身份验证结果。
返回值: AuthenticateResult 是身份验证的结果，可以表示成功、失败或没有信息。
用途: 当应用程序需要认证用户时，会调用这个方法。通常用于从请求中提取和验证用户凭据（如 JWT Token、Cookie 等）。如果验证成功，它将返回一个包含用户身份的 ClaimsPrincipal。

3. `Task ChallengeAsync(AuthenticationProperties properties)`

作用: 处理身份验证挑战（Challenge）。
参数:
- AuthenticationProperties properties: 与当前身份验证方案相关的属性信息。
用途: 当请求需要用户认证时，但用户没有认证凭据（例如访问需要登录才能访问的页面但用户没有登录），就会触发这个方法。通常用于重定向用户到登录页面或返回 401 未授权状态。

4. `Task ForbidAsync(AuthenticationProperties properties)`

作用: 处理授权失败（Forbid）。
参数:
- AuthenticationProperties properties: 与当前身份验证方案相关的属性信息。
用途: 当用户已经经过身份验证，但没有足够的权限访问某个资源时，就会调用这个方法。通常用于返回 403 禁止访问状态。

如何使用 `IAuthenticationHandler` 实现自定义身份验证

要实现一个自定义的身份验证方案，通常需要创建一个类，继承 IAuthenticationHandler 接口并实现它的所有方法。下面是一个基于自定义 Token 的身份验证方案的简单示例。

示例：自定义 Token 身份验证处理程序

public class CustomTokenAuthenticationHandler : IAuthenticationHandler
{
    private HttpContext _context;
    private AuthenticationScheme _scheme;

    public Task InitializeAsync(AuthenticationScheme scheme, HttpContext context)
    {
        _scheme = scheme;
        _context = context;
        return Task.CompletedTask;
    }

    public async Task<AuthenticateResult> AuthenticateAsync()
    {
        // 从请求头中提取 Token
        var token = _context.Request.Headers["Authorization"].FirstOrDefault()?.Split(" ").Last();

        if (token == null)
        {
            return AuthenticateResult.NoResult();
        }

        // 验证 Token（此处为简单示例，可集成 JWT 验证等）
        if (token == "valid-token")
        {
            var claims = new[] { new Claim(ClaimTypes.Name, "User") };
            var identity = new ClaimsIdentity(claims, _scheme.Name);
            var principal = new ClaimsPrincipal(identity);
            var ticket = new AuthenticationTicket(principal, _scheme.Name);

            return AuthenticateResult.Success(ticket);
        }
        else
        {
            return AuthenticateResult.Fail("Invalid Token");
        }
    }

    public Task ChallengeAsync(AuthenticationProperties properties)
    {
        _context.Response.StatusCode = StatusCodes.Status401Unauthorized;
        return Task.CompletedTask;
    }

    public Task ForbidAsync(AuthenticationProperties properties)
    {
        _context.Response.StatusCode = StatusCodes.Status403Forbidden;
        return Task.CompletedTask;
    }
}

主要流程：

InitializeAsync 初始化处理程序，绑定当前的 HttpContext 和身份验证方案。
AuthenticateAsync 从请求头中提取 Token，并验证 Token。如果验证通过，返回一个 AuthenticateResult.Success，否则返回失败。
ChallengeAsync 在未认证时返回 401 状态码。
ForbidAsync 在用户认证但无权限访问资源时返回 403 状态码。

注册自定义身份验证处理程序

为了让 ASP.NET Core 使用自定义的身份验证处理程序，您需要将它注册到服务中。首先，创建一个继承自 AuthenticationHandler<TOptions> 的处理程序，然后在 Startup.cs 或 Program.cs 中将它注册。

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication("CustomTokenScheme")
        .AddScheme<AuthenticationSchemeOptions, CustomTokenAuthenticationHandler>("CustomTokenScheme", null);

    services.AddAuthorization(); // 添加授权服务
}

这里，CustomTokenScheme 是你为该自定义方案定义的名称。然后在需要保护的控制器上使用 [Authorize(AuthenticationSchemes = "CustomTokenScheme")] 来指定使用自定义的 Token 验证方案。

.NET 6中的注册方式

//注册鉴权架构
builder.Services.AddAuthentication(op =>
{
    op.AddScheme<SessionAuthenticationHandler>("session", "ctmSession");
    op.DefaultAuthenticateScheme = "session";
    op.DefaultChallengeScheme= "session";
    op.DefaultForbidScheme= "session";
});

总结

IAuthenticationHandler 定义了身份验证方案的基本行为，包括初始化、认证、挑战、禁止访问等操作。
通过实现 IAuthenticationHandler，你可以创建自定义的身份验证机制，比如基于 JWT 或自定义的 Token 验证。
在 AuthenticateAsync 中你可以实现自定义的凭据验证逻辑，返回认证成功或失败。
注册自定义身份验证方案时，可以将其添加到 ASP.NET Core 的身份验证服务中，并在控制器中使用。

IAuthenticationHandler 接口