AspNetCore3.1_Secutiry源码解析_4_Authentication_JwtBear

文章目录

• AspNetCore3.1_Secutiry源码解析_1_目录
• AspNetCore3.1_Secutiry源码解析_2_Authentication_核心项目
• AspNetCore3.1_Secutiry源码解析_3_Authentication_Cookies
• AspNetCore3.1_Secutiry源码解析_4_Authentication_JwtBear
• AspNetCore3.1_Secutiry源码解析_5_Authentication_OAuth
• AspNetCore3.1_Secutiry源码解析_6_Authentication_OpenIdConnect
• AspNetCore3.1_Secutiry源码解析_7_Authentication_其他
• AspNetCore3.1_Secutiry源码解析_8_Authorization_授权框架

JwtBear简介

首先回想一下Cookie认证，Cookie认证在用户登录成功之后将用户信息加密后写入浏览器Cookie中，服务端通过解析Cookie内容来验证用户登录状态。这样做有几个缺陷：

• Cookie加密方式是微软自己定义的，并非国际标准，其他语言无法识别。
• 依赖Cookie，在跨域场景下，存在诸多限制。
  • CORS除非设置白名单否则是不允许带Cookie的；
  • 大部分浏览器对跨域设置Cookie有严格的限制。比如：A网站使用iframe嵌套B网站来实现集成，B网站依赖Cookie来维持登录态，如果是Chrome浏览器，需要将Cookie的Secure设置为true，即必须使用https，同时将SameSite设置为None，这样可以解决问题但是存在跨站访问攻击（CSRF）的安全漏洞，而Safari则是完全禁止设置跨站Cookie的）

JwtBear可以解决上面的缺点

• Jwt是国际标准
• Jwt不依赖Cookie，不存在跨站访问攻击问题

依赖注入

提供了四个重载方法，主要设置配置类 JwtBearerOptions。

默认添加名称为Bearer的认证Schema，JwtBearerHandler为处理器类。

  public static class JwtBearerExtensions
    {
        public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder)
            => builder.AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, _ => { });

        public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, Action<JwtBearerOptions> configureOptions)
            => builder.AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, configureOptions);

        public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, string authenticationScheme, Action<JwtBearerOptions> configureOptions)
            => builder.AddJwtBearer(authenticationScheme, displayName: null, configureOptions: configureOptions);

        public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action<JwtBearerOptions> configureOptions)
        {
            builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<JwtBearerOptions>, JwtBearerPostConfigureOptions>());
            return builder.AddScheme<JwtBearerOptions, JwtBearerHandler>(authenticationScheme, displayName, configureOptions);
        }
    }

通常来说用默认配置就够了。

    public class JwtBearerOptions : AuthenticationSchemeOptions
    {
        /// <summary>
        /// Gets or sets if HTTPS is required for the metadata address or authority.
        /// The default is true. This should be disabled only in development environments.
        /// </summary>
        public bool RequireHttpsMetadata { get; set; } = true;

        /// <summary>
        /// Gets or sets the discovery endpoint for obtaining metadata
        /// </summary>
        public string MetadataAddress { get; set; }

        /// <summary>
        /// Gets or sets the Authority to use when making OpenIdConnect calls.
        /// </summary>
        public string Authority { get; set; }

        /// <summary>
        /// Gets or sets a single valid audience value for any received OpenIdConnect token.
        /// This value is passed into TokenValidationParameters.ValidAudience if that property is empty.
        /// </summary>
        /// <value>
        /// The expected audience for any received OpenIdConnect token.
        /// </value>
        public string Audience { get; set; }

        /// <summary>
        /// Gets or sets the challenge to put in the "WWW-Authenticate" header.
        /// </summary>
        public string Challenge { get; set; } = JwtBearerDefaults.AuthenticationScheme;

        /// <summary>
        /// The object provided by the application to process events raised by the bearer authentication handler.
        /// The application may implement the interface fully, or it may create an instance of JwtBearerEvents
        /// and assign delegates only to the events it wants to process.
        /// </summary>
        public new JwtBearerEvents Events
        {
            get { return (JwtBearerEvents)base.Events; }
            set { base.Events = value; }
        }

        /// <summary>
        /// The HttpMessageHandler used to retrieve metadata.
        /// This cannot be set at the same time as BackchannelCertificateValidator unless the value
        /// is a WebRequestHandler.
        /// </summary>
        public HttpMessageHandler BackchannelHttpHandler { get; set; }

        /// <summary>
        /// Gets or sets the timeout when using the backchannel to make an http call.
        /// </summary>
        public TimeSpan BackchannelTimeout { get; set; } = TimeSpan.FromMinutes(1);

        /// <summary>
        /// Configuration provided directly by the developer. If provided, then MetadataAddress and the Backchannel properties
        /// will not be used. This information should not be updated during request processing.
        /// </summary>
        public OpenIdConnectConfiguration Configuration { get; set; }

        /// <summary>
        /// Responsible for retrieving, caching, and refreshing the configuration from metadata.
        /// If not provided, then one will be created using the MetadataAddress and Backchannel properties.
        /// </summary>
        public IConfigurationManager<OpenIdConnectConfiguration> ConfigurationManager { get; set; }

        /// <summary>
        /// Gets or sets if a metadata refresh should be attempted after a SecurityTokenSignatureKeyNotFoundException. This allows for automatic
        /// recovery in the event of a signature key rollover. This is enabled by default.
        /// </summary>
        public bool RefreshOnIssuerKeyNotFound { get; set; } = true;

        /// <summary>
        /// Gets the ordered list of <see cref="ISecurityTokenValidator"/> used to validate access tokens.
        /// </summary>
        public IList<ISecurityTokenValidator> SecurityTokenValidators { get; } = new List<ISecurityTokenValidator> { new JwtSecurityTokenHandler() };

        /// <summary>
        /// Gets or sets the parameters used to validate identity tokens.
        /// </summary>
        /// <remarks>Contains the types and definitions required for validating a token.</remarks>
        /// <exception cref="ArgumentNullException">if 'value' is null.</exception>
        public TokenValidationParameters TokenValidationParameters { get; set; } = new TokenValidationParameters();

        /// <summary>
        /// Defines whether the bearer token should be stored in the
        /// <see cref="AuthenticationProperties"/> after a successful authorization.
        /// </summary>
        public bool SaveToken { get; set; } = true;

        /// <summary>
        /// Defines whether the token validation errors should be returned to the caller.
        /// Enabled by default, this option can be disabled to prevent the JWT handler
        /// from returning an error and an error_description in the WWW-Authenticate header.
        /// </summary>
        public bool IncludeErrorDetails { get; set; } = true;
    }

这里会对配置做校验。JwtBear默认是没有提供发放Token的方法的，需要我们自己实现，这个后面再说。发放Token可以本地发放，也可以请求远程地址。

很多配置都是使用OpenConnectId协议来实现远程认证需要的，如果是本地发放token则不要配置。

 /// <summary>
/// Invoked to post configure a JwtBearerOptions instance.
/// </summary>
/// <param name="name">The name of the options instance being configured.</param>
/// <param name="options">The options instance to configure.</param>
public void PostConfigure(string name, JwtBearerOptions options)
{
    if (string.IsNullOrEmpty(options.TokenValidationParameters.ValidAudience) && !string.IsNullOrEmpty(options.Audience))
    {
        options.TokenValidationParameters.ValidAudience = options.Audience;
    }

    if (options.ConfigurationManager == null)
    {
        if (options.Configuration != null)
        {
            options.ConfigurationManager = new StaticConfigurationManager<OpenIdConnectConfiguration>(options.Configuration);
        }
        else if (!(string.IsNullOrEmpty(options.MetadataAddress) && string.IsNullOrEmpty(options.Authority)))
        {
            if (string.IsNullOrEmpty(options.MetadataAddress) && !string.IsNullOrEmpty(options.Authority))
            {
                options.MetadataAddress = options.Authority;
                if (!options.MetadataAddress.EndsWith("/", StringComparison.Ordinal))
                {
                    options.MetadataAddress += "/";
                }

                options.MetadataAddress += ".well-known/openid-configuration";
            }

            if (options.RequireHttpsMetadata && !options.MetadataAddress.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
            {
                throw new InvalidOperationException("The MetadataAddress or Authority must use HTTPS unless disabled for development by setting RequireHttpsMetadata=false.");
            }

            var httpClient = new HttpClient(options.BackchannelHttpHandler ?? new HttpClientHandler());
            httpClient.Timeout = options.BackchannelTimeout;
            httpClient.MaxResponseContentBufferSize = 1024 * 1024 * 10; // 10 MB

            options.ConfigurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(options.MetadataAddress, new OpenIdConnectConfigurationRetriever(),
                new HttpDocumentRetriever(httpClient) { RequireHttps = options.RequireHttpsMetadata });
        }
    }
}

发放Token

上面提到了JwtBear项目没有提供发放Token的方法，可以使用微软的扩展库来实现。

SymmetricSecurityKey ：表示使用对称算法生成的所有密钥的抽象基类。

using Microsoft.AspNetCore.Mvc;
using System;
using System.Text;

using IdentityModel;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;

[Route("api/user/login")]
[HttpPost]
public IActionResult Login([FromBody]UserDto dto)
{
    //验证username.password等逻辑..略
    var tokenHandler = new JwtSecurityTokenHandler();
    var key = Encoding.ASCII.GetBytes("this is a SecretKey");
    var authTime = DateTime.UtcNow;
    var expiresAt = authTime.AddDays(7);
    var tokenDescriptor = new SecurityTokenDescriptor
    {
        Subject = new ClaimsIdentity(new Claim[]
        {
            new Claim(JwtClaimTypes.Id, "1"),
            //谁用token
            new Claim(JwtClaimTypes.Audience,"http://localhost:5000"),
            //谁发token
            new Claim(JwtClaimTypes.Issuer,"http://localhost:5000"),
        }),
        Expires = expiresAt,
        SigningCredentials = new SigningCredentials(new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature)
    };
    var token = tokenHandler.CreateToken(tokenDescriptor);
    var tokenString = tokenHandler.WriteToken(token);
    return Ok(tokenString);
}

HS256算法要求key大于128bit即16字节,否则会出错

扩展库源码地址：

https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/issues

上面的代码只实现了很简单的token颁发的功能，刷新token，scope的校验，单点登录等都没有实现，不建议生产环境使用（除非你的需求十分简单已经可以满足）。实现这些十分麻烦，通常需要借助框架比如IdentityServer，这个后面再聊。

Cookie认证与Jwt认证对比

Cookie认证简图

Cookie认证需要通知浏览器操作cookie，以及302跳转，所以前后端同域的web场景比较合适。

sequenceDiagram
client->>server: 校验用户名密码后登录(HttpContext.SignInAsync())
server->>server: Cookie维护登录信息
server->>client: 302跳转RedirectUrl
client->>server: 登出(HttpContext.SignOutAsync())
server->>client: 清除Cookie,302跳转LogoutUrl

Jwt认证简图

可以看到服务端只负责颁发token、校验token，校验失败返回标准401，至于401怎么处理在于客户端，服务端不依赖于浏览器，所以用于非web端、或者前后端分离的场景比较合适

sequenceDiagram
client->>server: 登录(Login)
server->>server: 校验信息
server->>client: 颁发token
client->>server: 访问受保护api
server->>server: 校验token,将jwt中的claims信息写入HttpContext
server->>client: 返回api结果 or 401
client->>client: 处理401,自行跳到登录页或其他操作

JwtBearerHandler源码分析

JwtBearerHandler继承自AuthenticationHandler，比CookieHandler少了SignIn和Signout的实现，它只处理认证（Authenticate）、质询（Chanllenge）和拒绝（Forbid），上面已经说明过原因了。

classDiagram
class AuthenticationHandler{
AuthenticationScheme Scheme
TOptions Options
HttpContext Context
HttpRequest Request
HttpResponse Response
PathString OriginalPath
PathString OriginalPathBase
ILogger Logger
UrlEncoder UrlEncoder
ISystemClock Clock
object Events
string ClaimsIssuer
string CurrentUri
InitializeAsync()
+Task AuthenticateAsync()
+Task ChallengeAsync(AuthenticationProperties properties)
+Task ForbidAsync(AuthenticationProperties properties)
}
class IAuthenticationHandler{
HandleAsync()
}
JwtBearerHandler-->AuthenticationHandler
AuthenticationHandler-->IAuthenticationHandler

Authenticate - 认证

• 触发MessageReceived事件，相当于是个钩子，开发可以直接拦截返回认证结果，或者设置token取代header中的token
• 从header中取token
• 获取配置和校验配置
• 循环Option.SecurityTokenValidators执行每个校验器的校验逻辑(默认校验器逻辑等下说)
• 如果配置 Options.SaveToken=true, 则会将access_token保存在HttpContext.Properties中

protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
{
    string token = null;
    try
    {
        // Give application opportunity to find from a different location, adjust, or reject token
        var messageReceivedContext = new MessageReceivedContext(Context, Scheme, Options);

        // event can set the token
        await Events.MessageReceived(messageReceivedContext);
        if (messageReceivedContext.Result != null)
        {
            return messageReceivedContext.Result;
        }

        // If application retrieved token from somewhere else, use that.
        token = messageReceivedContext.Token;

        if (string.IsNullOrEmpty(token))
        {
            string authorization = Request.Headers[HeaderNames.Authorization];

            // If no authorization header found, nothing to process further
            if (string.IsNullOrEmpty(authorization))
            {
                return AuthenticateResult.NoResult();
            }

            if (authorization.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase))
            {
                token = authorization.Substring("Bearer ".Length).Trim();
            }

            // If no token found, no further work possible
            if (string.IsNullOrEmpty(token))
            {
                return AuthenticateResult.NoResult();
            }
        }

        if (_configuration == null && Options.ConfigurationManager != null)
        {
            _configuration = await Options.ConfigurationManager.GetConfigurationAsync(Context.RequestAborted);
        }

        var validationParameters = Options.TokenValidationParameters.Clone();
        if (_configuration != null)
        {
            var issuers = new[] { _configuration.Issuer };
            validationParameters.ValidIssuers = validationParameters.ValidIssuers?.Concat(issuers) ?? issuers;

            validationParameters.IssuerSigningKeys = validationParameters.IssuerSigningKeys?.Concat(_configuration.SigningKeys)
                ?? _configuration.SigningKeys;
        }

        List<Exception> validationFailures = null;
        SecurityToken validatedToken;
        foreach (var validator in Options.SecurityTokenValidators)
        {
            if (validator.CanReadToken(token))
            {
                ClaimsPrincipal principal;
                try
                {
                    principal = validator.ValidateToken(token, validationParameters, out validatedToken);
                }
                catch (Exception ex)
                {
                    Logger.TokenValidationFailed(ex);

                    // Refresh the configuration for exceptions that may be caused by key rollovers. The user can also request a refresh in the event.
                    if (Options.RefreshOnIssuerKeyNotFound && Options.ConfigurationManager != null
                        && ex is SecurityTokenSignatureKeyNotFoundException)
                    {
                        Options.ConfigurationManager.RequestRefresh();
                    }

                    if (validationFailures == null)
                    {
                        validationFailures = new List<Exception>(1);
                    }
                    validationFailures.Add(ex);
                    continue;
                }

                Logger.TokenValidationSucceeded();

                var tokenValidatedContext = new TokenValidatedContext(Context, Scheme, Options)
                {
                    Principal = principal,
                    SecurityToken = validatedToken
                };

                await Events.TokenValidated(tokenValidatedContext);
                if (tokenValidatedContext.Result != null)
                {
                    return tokenValidatedContext.Result;
                }

                if (Options.SaveToken)
                {
                    tokenValidatedContext.Properties.StoreTokens(new[]
                    {
                        new AuthenticationToken { Name = "access_token", Value = token }
                    });
                }

                tokenValidatedContext.Success();
                return tokenValidatedContext.Result;
            }
        }

        if (validationFailures != null)
        {
            var authenticationFailedContext = new AuthenticationFailedContext(Context, Scheme, Options)
            {
                Exception = (validationFailures.Count == 1) ? validationFailures[0] : new AggregateException(validationFailures)
            };

            await Events.AuthenticationFailed(authenticationFailedContext);
            if (authenticationFailedContext.Result != null)
            {
                return authenticationFailedContext.Result;
            }

            return AuthenticateResult.Fail(authenticationFailedContext.Exception);
        }

        return AuthenticateResult.Fail("No SecurityTokenValidator available for token: " + token ?? "[null]");
    }
    catch (Exception ex)
    {
        Logger.ErrorProcessingMessage(ex);

        var authenticationFailedContext = new AuthenticationFailedContext(Context, Scheme, Options)
        {
            Exception = ex
        };

        await Events.AuthenticationFailed(authenticationFailedContext);
        if (authenticationFailedContext.Result != null)
        {
            return authenticationFailedContext.Result;
        }

        throw;
    }
}

JwtBearOptions配置类的这段代码可以看到, 默认校验类是JwtSecurityTokenHandler，这是上面提到的扩展包里面的类，命名空间是System.IdentityModel.Tokens.Jwt

/// <summary>
/// Gets the ordered list of <see cref="ISecurityTokenValidator"/> used to validate access tokens.
/// </summary>
public IList<ISecurityTokenValidator> SecurityTokenValidators { get; } = new List<ISecurityTokenValidator> { new JwtSecurityTokenHandler() };

看一看代码，代码比较简单，就是解码token，然后将claims信息返回。之前生成jwt也是使用的这个类。

如果需要额外的校验逻辑，可以自己实现ISecurityTokenValidator，用这个类解码token得到claims之后实现自己的业务逻辑。

public override ClaimsPrincipal ValidateToken(string token, TokenValidationParameters validationParameters, out SecurityToken validatedToken)
    {
        if (string.IsNullOrWhiteSpace(token))
            throw LogHelper.LogArgumentNullException(nameof(token));

        if (validationParameters == null)
            throw LogHelper.LogArgumentNullException(nameof(validationParameters));

        if (token.Length > MaximumTokenSizeInBytes)
            throw LogHelper.LogExceptionMessage(new ArgumentException(LogHelper.FormatInvariant(TokenLogMessages.IDX10209, token.Length, MaximumTokenSizeInBytes)));

        var tokenParts = token.Split(new char[] { '.' }, JwtConstants.MaxJwtSegmentCount + 1);
        if (tokenParts.Length != JwtConstants.JwsSegmentCount && tokenParts.Length != JwtConstants.JweSegmentCount)
            throw LogHelper.LogExceptionMessage(new ArgumentException(LogHelper.FormatInvariant(LogMessages.IDX12741, token)));

        if (tokenParts.Length == JwtConstants.JweSegmentCount)
        {
            var jwtToken = ReadJwtToken(token);
            var decryptedJwt = DecryptToken(jwtToken, validationParameters);
            var innerToken = ValidateSignature(decryptedJwt, validationParameters);
            jwtToken.InnerToken = innerToken;
            validatedToken = jwtToken;
            return ValidateTokenPayload(innerToken, validationParameters);
        }
        else
        {
            validatedToken = ValidateSignature(token, validationParameters);
            return ValidateTokenPayload(validatedToken as JwtSecurityToken, validationParameters);
        }
    }

Chanllenge -- 质询

质询逻辑简单说下，执行认证方法，成功则返回结果，失败返回401，生成的报文大致这样

https://tools.ietf.org/html/rfc6750#section-3.1
WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"

protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
{
    var authResult = await HandleAuthenticateOnceSafeAsync();
    var eventContext = new JwtBearerChallengeContext(Context, Scheme, Options, properties)
    {
        AuthenticateFailure = authResult?.Failure
    };

    // Avoid returning error=invalid_token if the error is not caused by an authentication failure (e.g missing token).
    if (Options.IncludeErrorDetails && eventContext.AuthenticateFailure != null)
    {
        eventContext.Error = "invalid_token";
        eventContext.ErrorDescription = CreateErrorDescription(eventContext.AuthenticateFailure);
    }

    await Events.Challenge(eventContext);
    if (eventContext.Handled)
    {
        return;
    }

    Response.StatusCode = 401;

    if (string.IsNullOrEmpty(eventContext.Error) &&
        string.IsNullOrEmpty(eventContext.ErrorDescription) &&
        string.IsNullOrEmpty(eventContext.ErrorUri))
    {
        Response.Headers.Append(HeaderNames.WWWAuthenticate, Options.Challenge);
    }
    else
    {
        // https://tools.ietf.org/html/rfc6750#section-3.1
        // WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"
        var builder = new StringBuilder(Options.Challenge);
        if (Options.Challenge.IndexOf(' ') > 0)
        {
            // Only add a comma after the first param, if any
            builder.Append(',');
        }
        if (!string.IsNullOrEmpty(eventContext.Error))
        {
            builder.Append(" error=\"");
            builder.Append(eventContext.Error);
            builder.Append("\"");
        }
        if (!string.IsNullOrEmpty(eventContext.ErrorDescription))
        {
            if (!string.IsNullOrEmpty(eventContext.Error))
            {
                builder.Append(",");
            }

            builder.Append(" error_description=\"");
            builder.Append(eventContext.ErrorDescription);
            builder.Append('\"');
        }
        if (!string.IsNullOrEmpty(eventContext.ErrorUri))
        {
            if (!string.IsNullOrEmpty(eventContext.Error) ||
                !string.IsNullOrEmpty(eventContext.ErrorDescription))
            {
                builder.Append(",");
            }

            builder.Append(" error_uri=\"");
            builder.Append(eventContext.ErrorUri);
            builder.Append('\"');
        }

        Response.Headers.Append(HeaderNames.WWWAuthenticate, builder.ToString());
    }
}

Forbid - 拒绝

返回403

protected override Task HandleForbiddenAsync(AuthenticationProperties properties)
{
    var forbiddenContext = new ForbiddenContext(Context, Scheme, Options);
    Response.StatusCode = 403;
    return Events.Forbidden(forbiddenContext);
}

参考资料：

Cookie的SameSite属性

http://www.ruanyifeng.com/blog/2019/09/cookie-samesite.html

CORS

https://holdengong.com/aspnetcore3.1_middleware源码解析_1_cors/

ASPNET Core 认证与授权[4]:JwtBearer认证

https://www.cnblogs.com/RainingNight/p/jwtbearer-authentication-in-asp-net-core.html