# JWT 身份验证设置 ## 概述此技能为 .NET API 实现 JWT（JSON Web Token）身份验证： * **访问令牌** \- 在响应正文中返回短暂的 JWT * **刷新令牌** \- 存储在 HttpOnly cookie 中（安全，无法通过 JavaScript 访问） * **选项模式** \- 可通过 JwtOptions 配置过期时间 * **令牌轮换** \- 每次刷新时发出新的刷新令牌 * **安全审计** \- 全面的事件跟踪以确保合规性 * **令牌生成** \- 创建访问和刷新令牌 * **令牌验证** \- 验证传入的令牌 * **用户上下文** \- 从声明中提取用户信息 ## 快速参考组件|目的|地点 ---|---|--- `IJwtService` |代币生成接口|应用/摘要 `JwtService` |代币生成实施 |基础设施/身份验证 `JwtOptions` |配置（过期、发行者等）|基础设施/身份验证 `JwtBearerOptionsSetup` |配置 JWT 验证 |基础设施/身份验证 `IUserContext` |当前用户信息 |应用/摘要 `用户上下文` |从 HttpContext 中提取 |基础设施/身份验证 `IRefreshTokenRepository` |刷新令牌存储 |域/身份 `Cookie 设置` | Cookie 配置 |基础设施/身份验证 ** ** ## 认证结构 /应用/摘要/ ├── 认证/ │ ├── IJwtService.cs │ ├── IUserContext.cs │ ├── TokenResponse.cs │ └── AuthenticationErrors.cs /基础设施/ ├── 认证/ │ ├── JwtOptions.cs │ ├── JwtService.cs │ ├── JwtBearerOptionsSetup.cs │ ├── UserContext.cs │ ├── CookieSettings.cs │ └── RefreshTokenCookieManager.cs ** ** ## 模板：JWT 配置选项 // src/{name}.infrastruct/Authentication/JwtOptions.cs 命名空间 {name}.infrastruct.authentication; 公共密封类 JwtOptions { 公共常量字符串SectionName =“Jwt”; 公共字符串发行者{获取;初始化； } = 字符串.Empty; 公共字符串受众{获取;初始化； } = 字符串.Empty; 公共字符串 SecretKey { 获取；初始化； } = 字符串.Empty; 公共 int AccessTokenExpirationMinutes { 获取；初始化； } = 60; 公共 int RefreshTokenExpirationDays { 获取；初始化； } = 7; 公共 CookieSettings Cookie { 获取；初始化； } = 新的(); } 公共密封类 CookieSettings { /// <摘要> /// 刷新令牌cookie的名称 /// 公共字符串名称{获取;初始化； } = "X-刷新-令牌"; /// <摘要> /// Cookie 域（当前域留空） /// 公共字符串？域{获取;初始化； } /// <摘要> /// Cookie 路径 /// 公共字符串路径{获取;初始化； } =“/api/v1/auth”; /// <摘要> /// SameSite 策略（严格推荐用于医疗保健） /// 公共 SameSiteMode SameSite { 获取；初始化； } = SameSiteMode.Strict; /// <摘要> /// 需要 HTTPS（在生产中始终如此） /// 公共 bool SecureOnly { 获取；初始化； } = 真； } ### 应用程序设置.json { “Jwt”：{ “发行人”：“您的应用程序名称”， “受众”：“您的应用程序名称”， "SecretKey": "您的秘密密钥至少 32 个字符长，以确保安全", “AccessTokenExpirationMinutes”：60， “RefreshTokenExpirationDays”：7， “饼干”：{ “名称”：“X-刷新令牌”， “域名”：“”， “路径”：“/api/v1/auth”， "SameSite": "严格", “仅安全”：正确 } } } ** ** ## 模板：JWT 服务接口 // src/{name}.application/Abstractions/Authentication/IJwtService.cs 使用 {name}.domain.users；命名空间 {name}.application.abstractions.authentication; 公共接口 IJwtService { /// <摘要> /// 为用户生成访问和刷新令牌 /// TokenGenerationResult 生成令牌（用户用户， IEnumerable 角色， IEnumerable<字符串>?权限=空）； /// <摘要> /// 使用自定义声明生成令牌 /// TokenGenerationResult 生成令牌（引导用户ID，字符串电子邮件， IEnumerable 角色， IDictionary<字符串，字符串>？额外索赔= null); /// <摘要> /// 散列刷新令牌以确保安全数据库存储 /// 字符串HashRefreshToken（字符串refreshToken）； /// <摘要> /// 根据哈希值验证普通刷新令牌 /// bool verifyRefreshToken(字符串 plainToken, 字符串 hashedToken); /// <摘要> /// 获取访问令牌过期时间 /// 日期时间 GetAccessTokenExpiry(); /// <摘要> /// 获取刷新令牌过期时间 /// 日期时间 GetRefreshTokenExpiry(); } ** ** ## 模板：令牌响应 // src/{name}.application/Abstractions/Authentication/TokenResponse.cs 命名空间 {name}.application.abstractions.authentication; /// <摘要> /// 包含访问令牌的响应（刷新令牌通过 HttpOnly cookie 设置） /// 公开密封记录TokenResponse( 字符串 AccessToken, 日期时间 AccessTokenExpiration, 字符串 TokenType = "承载"); /// <摘要> /// 内部响应，包括刷新令牌（用于 cookie 设置） /// 公开密封记录TokenGenerationResult( 字符串 AccessToken, 字符串刷新令牌，日期时间 AccessTokenExpiration, 日期时间刷新令牌过期）； ** ** ## 模板：JWT 服务实现 // src/{name}.infrastruct/Authentication/JwtService.cs 使用 System.IdentityModel.Tokens.Jwt；使用 System.Security.Claims；使用系统.安全.密码学；使用系统文本；使用 Microsoft.Extensions.Options；使用 Microsoft.IdentityModel.Tokens；使用 {name}.application.Abstractions.Authentication；使用 {name}.application.Abstractions.Clock；使用 {name}.domain.identity; 命名空间 {name}.infrastruct.authentication; 内部密封类 JwtService ：IJwtService { 私有只读 JwtOptions _options; 私有只读 IDateTimeProvider _dateTimeProvider；私有只读 SigningCredentials _signingCredentials；私有只读 JwtSecurityTokenHandler _tokenHandler；公共 JwtService( IOptions 选项， IDateTimeProvider 日期时间提供商) { _options = 选项.Value; _dateTimeProvider = 日期时间提供者； var securityKey = new SymmetricSecurityKey( Encoding.UTF8.GetBytes(_options.SecretKey)); _signingCredentials = 新的 SigningCredentials( 安全密钥，安全算法.HmacSha256); _tokenHandler = new JwtSecurityTokenHandler(); } 公共 TokenGenerationResult 生成令牌（用户用户， IEnumerable 角色， IEnumerable<字符串>?权限=空） { var extraClaims = new Dictionary<字符串, 字符串> { ["name"] = $"{user.FirstName} {user.LastName}".Trim() }; 返回生成令牌内部（用户.Id, 用户.电子邮件, 角色，权限，附加索赔）； } 公共 TokenGenerationResult 生成令牌（引导用户ID，字符串电子邮件， IEnumerable 角色， IDictionary<字符串，字符串>？额外索赔 = null) { 返回GenerateTokensInternal（用户ID，电子邮件，角色，空，additionalClaims）； } 私人TokenGenerationResultGenerateTokensInternal（引导用户ID，字符串电子邮件， IEnumerable 角色， IEnumerable<字符串>?权限， IDictionary<字符串，字符串>？附加索赔） { var now = _dateTimeProvider.UtcNow; var accessTokenExpiration = now.AddMinutes(_options.AccessTokenExpirationMinutes); varfreshTokenExpiration = now.AddDays(_options.RefreshTokenExpirationDays); // 生成访问令牌 var accessToken = 生成AccessToken( 用户 ID, 电子邮件，角色，权限，额外索赔，现在，访问令牌过期）； // 生成不透明刷新令牌 var刷新令牌=GenerateRefreshToken(); 返回新的 TokenGenerationResult( 访问令牌，刷新令牌， accessToken过期时间，刷新令牌过期）； } 私有字符串GenerateAccessToken( 引导用户ID，字符串电子邮件， IEnumerable 角色， IEnumerable<字符串>?权限， IDictionary<字符串，字符串>？额外索赔，现在的日期时间，日期时间到期） { var 声明 = 新列表<声明> { 新（JwtRegisteredClaimNames.Sub，userId.ToString（）），新（JwtRegisteredClaimNames.电子邮件，电子邮件），新（JwtRegisteredClaimNames.Jti，Guid.NewGuid（）。ToString（）），新（JwtRegisteredClaimNames.Iat， new DateTimeOffset(now).ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer64) }; // 添加角色 foreach（角色中的 var 角色） { Claims.Add(new Claim(ClaimTypes.Role, 角色)); } // 添加权限 if（权限不为空） { foreach（权限中的var权限） { 声明.添加(新声明(“许可”,许可)); } } // 添加额外的声明 if (additionalClaims 不为空) { foreach（additionalClaims 中的 var（键，值）） { if (!string.IsNullOrEmpty(值)) { 声明.添加（新声明（键，值））； } } } var 令牌 = 新 JwtSecurityToken( 发行人：_options.Issuer，观众：_options.Audience，索赔：索赔，不以前：现在，过期：过期，签名凭证：_signingCredentials); 返回 _tokenHandler.WriteToken(token); } 私有静态字符串GenerateRefreshToken() { var randomBytes = 新字节[64]; 使用 var rng = RandomNumberGenerator.Create(); rng.GetBytes(randomBytes); 返回 Convert.ToBase64String(randomBytes); } public string HashRefreshToken(string refreshToken) { var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(refreshToken)); return Convert.ToHexString(bytes).ToLowerInvariant(); } public bool VerifyRefreshToken(string plainToken, string hashedToken) { var ComputeHash = HashRefreshToken(plainToken); return string.Equals(computedHash, hashedToken, StringComparison.OrdinalIgnoreCase); } 公共 DateTime GetAccessTokenExpiry() { return _dateTimeProvider.UtcNow.AddMinutes(_options.AccessTokenExpirationMinutes); } 公共 DateTime GetRefreshTokenExpiry() { return _dateTimeProvider.UtcNow.AddDays(_options.RefreshTokenExpirationDays); } } ** ** ## 模板：刷新令牌 Cookie 管理器 // src/{name}.infrastruct/Authentication/RefreshTokenCookieManager.cs 使用 Microsoft.AspNetCore.Http；使用 Microsoft.Extensions.Options；命名空间 {name}.infrastruct.authentication; 公共接口 IRefreshTokenCookieManager { void SetRefreshTokenCookie（HttpResponse响应，字符串refreshToken，日期时间到期）；细绳？ GetRefreshTokenFromCookie(HttpRequest 请求); void ClearRefreshTokenCookie(HttpResponse 响应); } 内部密封类 RefreshTokenCookieManager : IRefreshTokenCookieManager { 私有只读 JwtOptions _options; 公共 RefreshTokenCookieManager(IOptions 选项) { _options = 选项.Value; } 公共无效SetRefreshTokenCookie（HttpResponse响应，字符串refreshToken，日期时间到期） { var cookieOptions = 新的 CookieOptions { HttpOnly = true, // 无法通过 JavaScript 访问（XSS 保护） Secure = _options.Cookie.SecureOnly, // 仅 HTTPS SameSite = _options.Cookie.SameSite, // CSRF 保护过期=过期，路径 = _options.Cookie.Path, 域 = string.IsNullOrEmpty(_options.Cookie.Domain) ？空 : _options.Cookie.Domain, IsEssential = true // GDPR 合规性所需 }; response.Cookies.Append(_options.Cookie.Name,refreshToken,cookieOptions); } 公共字符串？ GetRefreshTokenFromCookie(HttpRequest 请求) { 返回 request.Cookies.TryGetValue(_options.Cookie.Name, out var token) ？代币：空； } 公共无效ClearRefreshTokenCookie（HttpResponse响应） { var cookieOptions = 新的 CookieOptions { HttpOnly = true, 安全 = _options.Cookie.SecureOnly, SameSite = _options.Cookie.SameSite, Expires = DateTime.UtcNow.AddDays(-1), // 立即过期路径 = _options.Cookie.Path, 域 = string.IsNullOrEmpty(_options.Cookie.Domain) ？空 : _options.Cookie.Domain }; response.Cookies.Append(_options.Cookie.Name, string.Empty, cookieOptions); } } ** ** ## 模板：刷新令牌实体 // src/{name}.domain/identity/RefreshToken.cs 命名空间 {name}.domain.identity; 公共密封类 RefreshToken { 公共 Guid Id { 获取；私人套装； } 公共 Guid 用户 ID { 获取；私人套装； } 公共字符串TokenHash { 获取;私人套装； } = 字符串.Empty; 公共日期时间创建时间{获取;私人套装； } 公共日期时间过期{获取;私人套装； } 公共日期时间？撤销At { 得到;私人套装； } 公共字符串？ ReplacedByTokenHash { 获取；私人套装； } 公共字符串？设备信息{获取;私人套装； } 公共字符串？ Ip地址{获取;私人套装； } public bool IsExpired => DateTime.UtcNow >= ExpiresAt; 公共 bool IsRevoked => RevokedAt.HasValue; public bool IsActive => !IsRevoked && !IsExpired; 私有 RefreshToken() { } 公共静态刷新令牌创建（引导用户ID，字符串tokenHash，日期时间到期时间，字符串？设备信息 = null, 字符串？ IP 地址 = 空) { 返回新的刷新令牌 { Id = Guid.NewGuid(), 用户ID = 用户ID, 令牌哈希 = 令牌哈希, 创建时间 = DateTime.UtcNow, 过期时间 = 过期时间, 设备信息 = 设备信息, IP 地址 = ip 地址 }; } 公共无效撤销（字符串？replacedByTokenHash = null） { RevokedAt = DateTime.UtcNow; ReplacedByTokenHash = ReplacedByTokenHash; } } ** ** ## 模板：JWT 承载选项设置 // src/{name}.infrastruct/Authentication/JwtBearerOptionsSetup.cs 使用系统文本；使用 Microsoft.AspNetCore.Authentication.JwtBearer；使用 Microsoft.Extensions.Options；使用 Microsoft.IdentityModel.Tokens；命名空间 {name}.infrastruct.authentication; 内部密封类 JwtBearerOptionsSetup : IConfigureNamedOptions { 私有只读 JwtOptions _jwtOptions; 公共 JwtBearerOptionsSetup(IOptions jwtOptions) { _jwtOptions = jwtOptions.Value; } 公共无效配置（JwtBearerOptions选项） { 配置（JwtBearerDefaults.AuthenticationScheme，选项）； } 公共无效配置（字符串？名称，JwtBearerOptions选项） { options.TokenValidationParameters = 新的 TokenValidationParameters { 验证发行者 = true, ValidIssuer = _jwtOptions.Issuer, 验证受众 = true, ValidAudience = _jwtOptions.Audience, ValidateIssuerSigningKey = true, IssuerSigningKey = 新的 SymmetricSecurityKey( Encoding.UTF8.GetBytes(_jwtOptions.SecretKey)), 验证生命周期 = true, ClockSkew = TimeSpan.Zero, // 不容忍过期 // 确保我们从令牌中获取用户 ID NameClaimType = "sub", 角色声明类型=“角色” }; options.Events = 新 JwtBearerEvents { OnAuthenticationFailed = 上下文 => { if (context.Exception 是 SecurityTokenExpiredException) { context.Response.Headers.Append( “令牌已过期”， “真实”）； } 返回任务.CompletedTask; }, OnChallenge = 上下文 => { // 401 的自定义响应返回任务.CompletedTask; }, OnForbidden = 上下文 => { // 403 的自定义响应返回任务.CompletedTask; } }; } } ** ** ## 模板：用户上下文接口 // src/{name}.application/Abstractions/Authentication/IUserContext.cs 命名空间 {name}.application.abstractions.authentication; 公共接口 IUserContext { /// <摘要> /// 当前认证用户的ID /// 引导用户 ID { 获取； } /// <摘要> /// 当前用户的电子邮件 /// 字符串电子邮件{获取; } /// <摘要> /// 当前用户的组织ID /// 指导？组织 ID { 获取； } /// <摘要> /// 当前用户的角色 /// IReadOnlyList 角色 { get; } /// <摘要> /// 检查用户是否通过身份验证 /// 布尔 IsAuthenticated { 获取； } /// <摘要> /// 检查用户是否具有特定角色 /// bool IsInRole(字符串角色); /// <摘要> /// 获取自定义声明值 /// 字符串？ GetClaimValue(字符串声明类型); } ** ** ## 模板：用户上下文实现 // src/{name}.infrastruct/Authentication/UserContext.cs 使用 System.IdentityModel.Tokens.Jwt；使用 System.Security.Claims；使用 Microsoft.AspNetCore.Http；使用 {name}.application.abstractions.authentication；命名空间 {name}.infrastruct.authentication; 内部密封类 UserContext ：IUserContext { 私有只读 IHttpContextAccessor _httpContextAccessor；公共 UserContext(IHttpContextAccessor httpContextAccessor) { _httpContextAccessor = httpContextAccessor; } 私人索赔本金？用户 => _httpContextAccessor.HttpContext?.User; 公共 bool IsAuthenticated => 用户？.身份？.IsAuthenticated ??错误的; 公共Guid用户ID { 得到 { var userIdClaim = User?.FindFirst(JwtRegisteredClaimNames.Sub)?.Value ??用户？.FindFirst(ClaimTypes.NameIdentifier)?.Value; 返回 Guid.TryParse(userIdClaim, out var userId) ？用户ID : throw new InvalidOperationException("在声明中找不到用户 ID"); } } 公共字符串电子邮件 { 得到 { 返回用户？.FindFirst(JwtRegisteredClaimNames.Email)?.Value ??用户?.FindFirst(ClaimTypes.Email)?.Value ??字符串.空; } } 公共指导？组织ID { 得到 { var orgIdClaim = User?.FindFirst("organization_id")?.Value; 返回 Guid.TryParse(orgIdClaim, out var orgId) ？组织ID：空； } } 公共 IReadOnlyList 角色 { 得到 { 返回 User?.FindAll(ClaimTypes.Role) .Select(c => c.Value) .ToList() ??新列表<字符串>(); } } 公共 bool IsInRole（字符串角色） { 返回用户？.IsInRole(角色) ??错误的; } 公共字符串？ GetClaimValue（字符串声明类型） { return User?.FindFirst(claimType)?.Value; } } ** ** ## 模板：认证注册 // src/{name}.infrastruct/Authentication/AuthenticationExtensions.cs 使用 Microsoft.AspNetCore.Authentication.JwtBearer；使用 Microsoft.Extensions.Configuration；使用 Microsoft.Extensions.DependencyInjection；使用 {name}.application.abstractions.authentication；命名空间 {name}.infrastruct.authentication; 公共静态类 AuthenticationExtensions { 公共静态 IServiceCollection AddJwtAuthentication( 这个IServiceCollection服务， IConfiguration配置） { // 绑定 JWT 选项 services.Configure( 配置.GetSection(JwtOptions.SectionName)); // 注册JWT承载认证服务 .AddAuthentication(选项=> { options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme; options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme; options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme; }) .AddJwtBearer(); // 配置 JWT 承载选项 services.ConfigureOptions(); // 注册服务 services.AddHttpContextAccessor(); services.AddScoped(); services.AddScoped(); 退货服务； } } ** ** ## 模板：登录命令处理程序 // src/{name}.application/Users/Login/LoginUserCommandHandler.cs 使用 {name}.application.Abstractions.Authentication；使用 {name}.application.Abstractions.Messaging；使用 {name}.domain.abstractions；使用 {name}.domain.identity; 命名空间 {name}.application.users.login; 公开密封记录LoginUserCommand( 字符串电子邮件，字符串密码，字符串？设备信息 = null, 字符串？ IpAddress = null) : ICommand; 内部密封类LoginUserCommandHandler : ICommandHandler { 私有只读 IUserRepository _userRepository; 私有只读 IPasswordHasher _passwordHasher；私有只读 IJwtService _jwtService；私有只读 IRoleRepository _roleRepository；私有只读 IRefreshTokenRepository _refreshTokenRepository; 私有只读 IUnitOfWork _unitOfWork; 公共登录用户命令处理程序（ IUserRepository 用户存储库， IPasswordHasher 密码Hasher, IJwtService jwtService， IRoleRepository 角色存储库， IRefreshTokenRepository 刷新TokenRepository， IUnitOfWork 工作单元） { _userRepository = userRepository; _passwordHasher = 密码Hasher； _jwtService = jwtService; _roleRepository = 角色存储库； _refreshTokenRepository =刷新TokenRepository; _工作单元 = 工作单元； } 公共异步任务<结果>句柄（登录用户命令请求， CancellationToken（取消令牌） { // 通过邮箱查找用户 var user = wait _userRepository.GetByEmailAsync( 请求.电子邮件, 取消令牌）； if（用户为空） { 返回 Result.Failure(UserErrors.InvalidCredentials); } // 验证密码 if (!_passwordHasher.Verify(request.Password, user.PasswordHash)) { 返回 Result.Failure(UserErrors.InvalidCredentials); } // 检查用户是否活跃 if (!user.IsActive) { 返回 Result.Failure(UserErrors.AccountDeactivated); } // 获取用户角色和权限 var 角色=等待_roleRepository.GetRolesByUserIdAsync(user.Id,cancelToken); var roleNames = Roles.Select(r => r.Name); var 权限 = Roles.SelectMany(r => r.Permissions).Distinct(); // 生成令牌 var tokenResult = _jwtService.GenerateTokens(用户、角色名称、权限); // 将哈希刷新令牌存储在数据库中 var refreshTokenEntity = RefreshToken.Create( 用户Id: 用户.Id, tokenHash: _jwtService.HashRefreshToken(tokenResult.RefreshToken), 过期时间：tokenResult.RefreshTokenExpiration， deviceInfo: 请求.DeviceInfo, ipAddress: 请求.IpAddress); _refreshTokenRepository.Add(refreshTokenEntity); 等待 _unitOfWork.SaveChangesAsync(cancellationToken); // 返回访问令牌（刷新令牌将由控制器设置在 cookie 中）返回新的 TokenResponse( tokenResult.AccessToken, tokenResult.AccessTokenExpiration); } } ** ** ## 模板：刷新令牌命令处理程序 // src/{name}.application/Users/RefreshToken/RefreshTokenCommandHandler.cs 使用 {name}.application.Abstractions.Authentication；使用 {name}.application.Abstractions.Messaging；使用 {name}.domain.abstractions；使用 {name}.domain.identity; 命名空间 {name}.application.users.refreshToken; 公共密封记录 RefreshTokenCommand( 字符串刷新令牌，字符串？设备信息 = null, 字符串？ IpAddress = null) : ICommand; 内部密封类 RefreshTokenCommandHandler : ICommandHandler { 私有只读 IJwtService _jwtService；私有只读 IUserRepository _userRepository; 私有只读 IRoleRepository _roleRepository；私有只读 IRefreshTokenRepository _refreshTokenRepository; 私有只读 IUnitOfWork _unitOfWork; 公共 RefreshTokenCommandHandler( IJwtService jwtService， IUserRepository 用户存储库， IRoleRepository 角色存储库， IRefreshTokenRepository 刷新TokenRepository， IUnitOfWork 工作单元） { _jwtService = jwtService; _userRepository = userRepository; _roleRepository = 角色存储库； _refreshTokenRepository =刷新TokenRepository; _工作单元 = 工作单元； } 公共异步任务<结果>句柄（ RefreshTokenCommand 请求， CancellationToken（取消令牌） { // 对传入的令牌进行哈希处理以在数据库中查找它 var tokenHash = _jwtService.HashRefreshToken(request.RefreshToken); // 查找存储的刷新令牌 varstoredToken =等待_refreshTokenRepository.GetByHashAsync（令牌哈希，取消令牌）； if (storedToken 为 null || !storedToken.IsActive) { 返回 Result.Failure(UserErrors.InvalidRefreshToken); } // 获取用户 var 用户 = 等待 _userRepository.GetByIdAsync( 存储的Token.UserId, 取消令牌）； if (用户为 null || !user.IsActive) { // 如果用户无效，则撤销令牌存储令牌.Revoke(); 等待 _unitOfWork.SaveChangesAsync(cancellationToken); 返回 Result.Failure(UserErrors.InvalidRefreshToken); } // 获取当前角色和权限 var 角色=等待_roleRepository.GetRolesByUserIdAsync(user.Id,cancelToken); var roleNames = Roles.Select(r => r.Name); var 权限 = Roles.SelectMany(r => r.Permissions).Distinct(); // 生成新的代币 var tokenResult = _jwtService.GenerateTokens(用户、角色名称、权限); // 轮换刷新令牌：撤销旧令牌，创建新令牌 var newTokenHash = _jwtService.HashRefreshToken(tokenResult.RefreshToken); storeToken.Revoke(replacedByTokenHash: newTokenHash); var newRefreshToken = Domain.Identity.RefreshToken.Create( 用户Id: 用户.Id, 令牌哈希：新令牌哈希，过期时间：tokenResult.RefreshTokenExpiration， deviceInfo: 请求.DeviceInfo, ipAddress: 请求.IpAddress); _refreshTokenRepository.Add(newRefreshToken); 等待 _unitOfWork.SaveChangesAsync(cancellationToken); 返回token结果； } } ** ** ## 模板：身份验证控制器 // src/{name}.api/Controllers/Auth/AuthController.cs 使用 MediatR；使用 Microsoft.AspNetCore.Authorization；使用 Microsoft.AspNetCore.Mvc；使用 {name}.application.abstractions.authentication；使用 {name}.application.users.login; 使用 {name}.application.users.refreshToken；使用 {name}.infrastruct.authentication；命名空间 {name}.api.Controllers.Auth; [API控制器] [路线（“api/v1/auth”）] 公共类 AuthController ：ControllerBase { 私有只读 ISender _sender；私有只读 IRefreshTokenCookieManager _cookieManager; 公共身份验证控制器（ ISender 发件人， IRefreshTokenCookieManager cookieManager) { _发件人=发件人； _cookieManager = cookieManager; } [HttpPost("登录")] [允许匿名] 公共异步任务 LoginFull( [FromBody] LoginRequest 请求， CancellationToken（取消令牌） { var 命令 = 新的 LoginUserCommand( 请求.电子邮件, 请求.密码, 设备信息：Request.Headers.UserAgent， IpAddress: HttpContext.Connection.RemoteIpAddress?.ToString()); var result = wait _sender.Send(命令,cancelToken); if (结果.IsFailure) { return Unauthorized(new { error = result.Error.Code, message = result.Error.Message }); } // 在 HttpOnly cookie 中设置刷新令牌 _cookieManager.SetRefreshTokenCookie( 回应，结果.Value.RefreshToken, 结果.Value.RefreshTokenExpiration); // 仅返回响应正文中的访问令牌返回确定（新TokenResponse（结果.Value.AccessToken, 结果.Value.AccessTokenExpiration)); } [HttpPost(“刷新”)] [允许匿名] 公共异步任务 RefreshToken(CancellationToken CancellationToken) { // 从 HttpOnly cookie 获取刷新令牌 var refreshToken = _cookieManager.GetRefreshTokenFromCookie(Request); if (string.IsNullOrEmpty(refreshToken)) { return Unauthorized(new { error = "invalid_token", message = "未找到刷新令牌" }); } var 命令 = 新的 RefreshTokenCommand( 刷新令牌，设备信息：Request.Headers.UserAgent， IpAddress: HttpContext.Connection.RemoteIpAddress?.ToString()); var result = wait _sender.Send(命令,cancelToken); if (结果.IsFailure) { // 清除无效的cookie _cookieManager.ClearRefreshTokenCookie(响应); return Unauthorized(new { error = result.Error.Code, message = result.Error.Message }); } // 在 HttpOnly cookie 中设置新的刷新令牌（旋转） _cookieManager.SetRefreshTokenCookie( 回应，结果.Value.RefreshToken, 结果.Value.RefreshTokenExpiration); // 仅返回响应正文中的访问令牌返回确定（新TokenResponse（结果.Value.AccessToken, 结果.Value.AccessTokenExpiration)); } [HttpPost(“注销”)] [授权] 公共异步任务注销（CancellationToken CancellationToken） { // 从cookie中获取刷新令牌并撤销它 var refreshToken = _cookieManager.GetRefreshTokenFromCookie(Request); if (!string.IsNullOrEmpty(refreshToken)) { var 命令 = new RevokeRefreshTokenCommand(refreshToken); 等待_sender.Send（命令，cancelToken）； } // 清除cookie _cookieManager.ClearRefreshTokenCookie(响应); 返回无内容（）； } [HttpGet(“我”)] [授权] 公共 IActionResult GetCurrentUser([FromServices] IUserContext userContext) { 返回确定（新 { 用户Id = userContext.UserId, 电子邮件 = userContext.Email, 名称 = userContext.Name, 患者 ID = userContext.PatientId, 角色= userContext.Roles，权限 = userContext.Permissions }); } } 公开密封记录LoginRequest(string Email, string Password); ** ** ## 模板：依赖注入注册 // src/{name}.infrastructure/DependencyInjection.cs private static void AddAuthentication(IServiceCollection services, IConfiguration configuration) { // Configure JWT options with nested cookie settings services.Configure(configuration.GetSection(JwtOptions.SectionName)); // 注册认证服务 services.AddScoped(); services.AddScoped(); // 为UserContext注册HttpContextAccessor services.AddHttpContextAccessor(); services.AddScoped(); // 配置 JWT 承载身份验证服务 .AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(); services.ConfigureOptions(); // 配置授权 services.AddAuthorization(); } ** ** ## 关键规则 1. **Secret key length** \- At least 32 characters for HMAC-SHA256 2. **Store secrets securely** \- Use Azure Key Vault, AWS Secrets, etc. 3. **Short access tokens** \- 15-60 minutes typical 4. **Longer refresh tokens** \- 7-30 days typical 5. **Validate all claims** \- Issuer, audience, signature, expiration 6. **No clock skew** \- Set `ClockSkew = TimeSpan.Zero` 7. **HTTPS only** \- Never transmit tokens over HTTP 8. **HttpOnly cookies** \- Refresh tokens should never be accessible via JavaScript 9. **Token rotation** \- Issue new refresh token on each use 10. **Revoke on logout** \- Always revoke refresh token on logout 11. **Use IUserContext** \- Don't access HttpContext directly in handlers ** ** ## 要避免的反模式 // ❌ WRONG: Returning refresh token in response body 返回确定（新{accessToken，refreshToken}）； // 暴露于 XSS！ // ✅ CORRECT: Set refresh token in HttpOnly cookie _cookieManager.SetRefreshTokenCookie(Response, refreshToken, expiry); 返回确定（新{accessToken}）； // ❌ 错误：存储普通刷新令牌 await _db.RefreshTokens.AddAsync(new { Token = refreshToken }); // ✅ 正确：存储哈希令牌 await _db.RefreshTokens.AddAsync(new { TokenHash = _jwtService.HashRefreshToken(refreshToken) }); // ❌ 错误：密钥短 "SecretKey": "abc123" // 太短，不安全！ // ✅ 正确：强密钥 "SecretKey": "your-secret-key-at-least-32-characters-long-for-security" // ❌ 错误：在处理程序中访问 HttpContext 公共类处理程序 { 私有只读 IHttpContextAccessor _accessor； var userId = _accessor.HttpContext.User.FindFirst("sub"); // 不！ } // ✅ 正确：使用 IUserContext 抽象公共类处理程序 { 私有只读 IUserContext _userContext； var userId = _userContext.UserId; } // ❌ 错误：刷新令牌永不过期 ExpiresAt = DateTime.MaxValue // 安全风险！ // ✅ 正确：配置的过期时间 ExpiresAt = DateTime.UtcNow.AddDays(_options.RefreshTokenExpirationDays) // ❌ 错误：令牌永不过期 expires: DateTime.MaxValue // 安全风险！ // ✅ 正确：具有刷新功能的短期令牌过期：DateTime.UtcNow.AddMinutes(60) ** ** ## 相关技能 * `permission-authorization` \- Permission-based access control * `api-controller-generator` \- Protected API endpoints * `dotnet-clean-architecture` \- Infrastructure layer setup

Jwt认证

包含技能