【Azure Developer】.NET 10搭建登录认证示例(Identity + JWT + Refresh Token)
本文是一个动手示例,跟随一步一步,可以把项目真正跑起来。
从创建项目开始,实现注册、登录、JWT 验证、Refresh Token 轮换、MCP 鉴权,最后补上一个能实际操作的中文页面。
最终效果:一张动态图看完整流程

动态图:未认证首页 → 注册表单 → 注册成功 → 登录成功 → 获取天气 → 退出登录。
本文将要完成的示例,是一条真正闭环的认证链路:
注册账户 ↓ Identity 验证用户名和密码 ↓ 签发 Access Token + Refresh Token ↓ 客户端携带 Bearer Token ↓ 访问天气 API 或 MCP 工具 ↓ Access Token 到期后使用 Refresh Token 换新
如果没有完成认证,会直接跳转到一个自定义页面,并提示:“当前尚未认证,请先注册或登录。”
一:创建项目并安装依赖
1. 准备环境
本文使用:
- .NET 10 SDK。
- PowerShell 7。
- VS Code 或 Visual Studio。
- SQLite。
- 原生 HTML、CSS、JavaScript。
不需要额外安装数据库服务,也不需要 Node.js 前端构建工具。
检查 SDK:
dotnet --version
应当能够使用 .NET 10 SDK, 本项目验证时使用 SDK 10.0.404。
2. 创建 Web API
在准备放置项目的目录执行:
dotnet new webapi -n lbMcpJwtDemo -f net10.0 cd .\lbMcpJwtDemo
3. 安装包
为避免不同时间安装到不同主版本,本文固定使用当前项目验证过的版本:
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore --version 10.0.15 --no-restore dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 10.0.15 --no-restore dotnet add package Microsoft.IdentityModel.JsonWebTokens --version 8.23.0 --no-restore dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 10.0.15 --no-restore dotnet add package ModelContextProtocol.AspNetCore --version 2.4.0 --no-restore dotnet add package Microsoft.AspNetCore.OpenApi --version 10.0.15 --no-restore dotnet restore //--no-restore 只是先添加引用,最后统一还原。兼容性仍需通过还原和构建验证。
几个包的职责:
| 包 | 用途 |
|---|---|
| Identity.EntityFrameworkCore | 使用 EF Core 保存 Identity 用户 |
| Authentication.JwtBearer | 验证请求中的 JWT |
| IdentityModel.JsonWebTokens | 签发 JWT |
| EntityFrameworkCore.Sqlite | SQLite 数据库访问 |
| ModelContextProtocol.AspNetCore | 注册 MCP 服务和 HTTP 端点 |
| AspNetCore.OpenApi | 保留开发环境 OpenAPI 文档 |
4. 最终文件目录结构(供参考)
lbMcpJwtDemo
├── AppDbContext.cs
├── AuthController.cs
├── JwtTokenService.cs
├── TokenHasher.cs
├── WeatherTool.cs
├── Program.cs
├── appsettings.json
├── Properties
│ └── launchSettings.json
├── wwwroot
│ ├── index.html
│ ├── styles.css
│ └── app.js
下面按顺序创建或替换文件。
二:先配置数据库和 JWT 参数
1. 配置文件不要保存签名密钥
{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*", "Jwt": { "Issuer": "https://localhost:5041", "Audience": "mcp-jwt-demo" }, "ConnectionStrings": { "Default": "Data Source=app.db" } }
几个配置的含义:
Issuer:令牌签发者标识。Audience:令牌预期使用方。Default:SQLite 连接字符串。
这里的 Issuer 是签发和验证双方约定的标识,不是服务监听地址,也不会自动开启 HTTPS。
2. 使用 User Secrets 保存密钥
在项目目录下执行:
dotnet user-secrets init
$secret =openssl rand -base64 32
dotnet user-secrets set "Jwt:Secret" $secret

这会生成一个随机的 32 字节密钥,并使用 Base64 保存。注:使用openssl工具生成一个32位字节密钥后用Base64编码,如果没有这个工具也可以使用其它方式实现。
三:接入 Identity 和 SQLite
Identity 已经提供了用户管理、密码哈希和锁定机制,不需要自己再建一套密码验证逻辑。我们只需要接入数据库存储。
创建 AppDbContext.cs:
using Microsoft.AspNetCore.Identity.EntityFrameworkCore; using Microsoft.EntityFrameworkCore; using Microsoft.AspNetCore.Identity; namespace lbMcpJwtDemo; public class AppDbContext : IdentityDbContext<IdentityUser> { public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { } public DbSet<RefreshToken> RefreshTokens => Set<RefreshToken>(); protected override void OnModelCreating(ModelBuilder builder) { base.OnModelCreating(builder); builder.Entity<RefreshToken>(entity => { entity.HasIndex(token => token.TokenHash).IsUnique(); entity.Property(token => token.TokenHash).HasMaxLength(44).IsRequired(); entity.HasOne<IdentityUser>().WithMany() .HasForeignKey(token => token.UserId).OnDelete(DeleteBehavior.Cascade); }); } }
这里额外定义了一张 Refresh Token 表。
TokenHash 的唯一索引有两个用途:
- 避免重复记录。
- 加快按令牌哈希查找记录的速度。
SHA-256 结果是 32 字节,转成 Base64 后长度为 44 个字符。
注意:Refresh Token 的 SHA-256 哈希,与 Identity 的密码哈希不是同一种用途。
密码必须交给 Identity 管理,不要照着 Refresh Token 的方式自行处理用户密码。
四:签发和验证 Access Token
创建 JwtTokenService.cs:
using Microsoft.IdentityModel.JsonWebTokens; using Microsoft.IdentityModel.Tokens; using Microsoft.AspNetCore.Identity; namespace lbMcpJwtDemo; public class JwtTokenService { public const int AccessTokenLifetimeSeconds = 900; private readonly string _issuer; private readonly string _audience; private readonly SymmetricSecurityKey _key; public JwtTokenService(IConfiguration config) { _issuer = config["Jwt:Issuer"] ?? throw new InvalidOperationException("Jwt:Issuer is required."); _audience = config["Jwt:Audience"] ?? throw new InvalidOperationException("Jwt:Audience is required."); if (string.IsNullOrWhiteSpace(_issuer) || string.IsNullOrWhiteSpace(_audience)) throw new InvalidOperationException("Jwt:Issuer and Jwt:Audience must not be empty."); var secret = config["Jwt:Secret"] ?? throw new InvalidOperationException("Configure Jwt:Secret with dotnet user-secrets or the Jwt__Secret environment variable."); var bytes = new byte[secret.Length]; if (!Convert.TryFromBase64String(secret, bytes, out var length) || length < 32) throw new InvalidOperationException("Jwt:Secret must be Base64 encoded and contain at least 32 random bytes."); _key = new SymmetricSecurityKey(bytes[..length]); } public string CreateAccessToken(IdentityUser user) { // 用字典传 Claims,JsonWebTokenHandler 会原样写进 token var claims = new Dictionary<string, object> { [JwtRegisteredClaimNames.Sub] = user.Id, [JwtRegisteredClaimNames.UniqueName] = user.UserName ?? user.Id, [JwtRegisteredClaimNames.Jti] = Guid.NewGuid().ToString(), [JwtRegisteredClaimNames.Email] = user.Email ?? "", ["scope"] = "mcp:invoke" }; var descriptor = new SecurityTokenDescriptor { Issuer = _issuer, Audience = _audience, Claims = claims, Expires = DateTime.UtcNow.AddSeconds(AccessTokenLifetimeSeconds), SigningCredentials = new SigningCredentials(_key, SecurityAlgorithms.HmacSha256) }; var handler = new JsonWebTokenHandler(); return handler.CreateToken(descriptor); } public TokenValidationParameters CreateValidationParameters() => new() { ValidateIssuer = true, ValidateAudience = true, ValidateLifetime = true, ValidateIssuerSigningKey = true, ValidIssuer = _issuer, ValidAudience = _audience, IssuerSigningKey = _key, ValidAlgorithms = [SecurityAlgorithms.HmacSha256], NameClaimType = JwtRegisteredClaimNames.UniqueName, ClockSkew = TimeSpan.FromMinutes(1) }; } public class RefreshToken { public Guid Id { get; set; } public string UserId { get; set; } = ""; public string TokenHash { get; set; } = ""; // 只存 SHA-256 哈希 public DateTime ExpiresAtUtc { get; set; } public bool IsRevoked { get; set; } // 是否已吊销/已轮换 public string? ReplacedByTokenHash { get; set; } // 被谁替换,重放检测用 }
这里有四个关键点:
- 配置错误要在启动时暴露。密钥缺失、不是 Base64、长度不足,都直接报出明确错误,而不是等用户登录时才返回 500。
- 签发和验证使用同一个服务配置。避免登录签发时使用一个 Issuer,验证时又使用另一个。
- 限制签名算法。这里明确只接受:SecurityAlgorithms.HmacSha256
- 保留一分钟时钟容差。Access Token 的 exp 设置为 15 分钟之后,但验证允许一分钟时钟偏差。因此,不要把它描述成“恰好第 900 秒后一定失效”。
JWT 的 Payload 通常可以被解码读取。不要把密码、密钥等内容放进 Claims。
(签名保护的是内容完整性,不能用来隐藏敏感信息)
五:Refresh Token 只保存哈希
创建 TokenHasher.cs:
using System.Security.Cryptography; using System.Text; namespace lbMcpJwtDemo; public static class TokenHasher { public static string Hash(string token) { // 数据库泄露时,原始 token 不会暴露 var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(token)); return Convert.ToBase64String(bytes); } }
Refresh Token 本身由密码随机数生成器创建,原始值只返回给客户端,数据库保存它的哈希。这样,即使数据库记录泄露,攻击者也不能直接拿数据库里的 TokenHash 去调用刷新接口。
六:实现注册、登录、刷新和退出
创建 AuthController.cs:
using System.ComponentModel.DataAnnotations; using System.Security.Cryptography; using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Identity; using Microsoft.AspNetCore.Mvc; using Microsoft.EntityFrameworkCore; namespace lbMcpJwtDemo; [ApiController] [AllowAnonymous] [Route("api/auth")] public class AuthController( AppDbContext db, UserManager<IdentityUser> userManager, SignInManager<IdentityUser> signInManager, JwtTokenService jwtTokenService, ILogger<AuthController> logger) : ControllerBase { [HttpPost("register")] public async Task<IActionResult> Register(RegisterRequest request) { var user = new IdentityUser { UserName = request.UserName, Email = request.Email }; var result = await userManager.CreateAsync(user, request.Password); if (!result.Succeeded) return BadRequest(new { errors = result.Errors.Select(error => new { error.Code, error.Description }) }); return StatusCode(StatusCodes.Status201Created, new { userId = user.Id, userName = user.UserName }); } [HttpPost("login")] public async Task<IActionResult> Login(LoginRequest request, CancellationToken cancellationToken) { var user = await userManager.FindByNameAsync(request.UserName); if (user is null) return Unauthorized(new { error = "用户名或密码不正确" }); var result = await signInManager.CheckPasswordSignInAsync(user, request.Password, lockoutOnFailure: true); if (!result.Succeeded) { logger.LogWarning("Login rejected. Locked out: {LockedOut}", result.IsLockedOut); return Unauthorized(new { error = "用户名或密码不正确,或账户已被锁定" }); } var refreshToken = AddRefreshToken(user.Id); await db.SaveChangesAsync(cancellationToken); return Ok(CreateTokenResponse(user, refreshToken)); } [HttpPost("refresh")] public async Task<IActionResult> Refresh(RefreshRequest request, CancellationToken cancellationToken) { // SQLite's immediate transaction serializes rotation and replay handling. await using var transaction = await db.Database.BeginTransactionAsync(cancellationToken); var hash = TokenHasher.Hash(request.RefreshToken); var stored = await db.RefreshTokens.SingleOrDefaultAsync(token => token.TokenHash == hash, cancellationToken); if (stored is null) return Unauthorized(new { error = "无效的 refresh token" }); if (stored.IsRevoked) { await db.RefreshTokens.Where(token => token.UserId == stored.UserId && !token.IsRevoked) .ExecuteUpdateAsync(setters => setters.SetProperty(token => token.IsRevoked, true), cancellationToken); await transaction.CommitAsync(cancellationToken); logger.LogWarning("Refresh token replay detected; active refresh tokens revoked"); return Unauthorized(new { error = "检测到重放,已吊销该用户所有 refresh token" }); } var user = await userManager.FindByIdAsync(stored.UserId); if (stored.ExpiresAtUtc <= DateTime.UtcNow || user is null || await userManager.IsLockedOutAsync(user)) { stored.IsRevoked = true; await db.SaveChangesAsync(cancellationToken); await transaction.CommitAsync(cancellationToken); return Unauthorized(new { error = "refresh token 已过期或账户不可用" }); } var refreshToken = AddRefreshToken(user.Id); stored.IsRevoked = true; stored.ReplacedByTokenHash = TokenHasher.Hash(refreshToken); await db.SaveChangesAsync(cancellationToken); await transaction.CommitAsync(cancellationToken); return Ok(CreateTokenResponse(user, refreshToken)); } [HttpPost("logout")] public async Task<IActionResult> Logout(RefreshRequest request, CancellationToken cancellationToken) { var hash = TokenHasher.Hash(request.RefreshToken); await db.RefreshTokens.Where(token => token.TokenHash == hash && !token.IsRevoked) .ExecuteUpdateAsync(setters => setters.SetProperty(token => token.IsRevoked, true), cancellationToken); return NoContent(); } private string AddRefreshToken(string userId) { var token = Convert.ToBase64String(RandomNumberGenerator.GetBytes(64)); db.RefreshTokens.Add(new RefreshToken { Id = Guid.NewGuid(), UserId = userId, TokenHash = TokenHasher.Hash(token), ExpiresAtUtc = DateTime.UtcNow.AddDays(7) }); return token; } private object CreateTokenResponse(IdentityUser user, string refreshToken) => new { accessToken = jwtTokenService.CreateAccessToken(user), refreshToken, tokenType = "Bearer", expiresIn = JwtTokenService.AccessTokenLifetimeSeconds }; } public record LoginRequest( [Required, StringLength(256)] string UserName, [Required, StringLength(128)] string Password); public record RegisterRequest( [Required, StringLength(256)] string UserName, [Required, StringLength(128, MinimumLength = 6)] string Password, [EmailAddress, StringLength(256)] string? Email); public record RefreshRequest([Required, StringLength(128)] string RefreshToken);
Refresh Token 是怎样轮换的
假设登录后拿到了 R1:
登录
└── 返回 R1,数据库保存 Hash(R1)
使用 R1 刷新
├── R1 标记为已撤销
├── 创建 R2
└── 返回新的 Access Token 和 R2
再次使用 R1
├── 检测到已撤销令牌被使用
└── 撤销这个用户当前所有有效 Refresh Token
客户端每次刷新后,必须替换手里的 Refresh Token。
七:注册一个 MCP 天气工具
创建 WeatherTool.cs:
using ModelContextProtocol.Server; using System.ComponentModel; namespace lbMcpJwtDemo; [McpServerToolType] public class WeatherTool { [McpServerTool(Name = "get_weather")] [Description("获取指定城市的天气")] public static string GetWeather(string city) { // 演示用,实际换成你自己的业务逻辑 return $"{city}:多云,26℃"; } }
这里返回的是演示数据,不是真实天气服务。
特别注意当前 MCP 包的写法:
[McpServerTool(Name = "get_weather")]
[Description("获取指定城市的天气")]
不要把 Description 当成当前版本 McpServerTool 属性的命名参数。工具定义完成后,还需要注册 HTTP transport,并给端点加授权策略。
八:把所有组件接起来
替换 Program.cs:
using lbMcpJwtDemo; using Microsoft.AspNetCore.Identity; using Microsoft.EntityFrameworkCore; using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.IdentityModel.JsonWebTokens; var builder = WebApplication.CreateBuilder(args); // Add services to the container. // Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi builder.Services.AddOpenApi(); builder.Services.AddControllers(); builder.Services.AddProblemDetails(); var tokenService = new JwtTokenService(builder.Configuration); builder.Services.AddSingleton(tokenService); builder.Services.AddDbContext<AppDbContext>(options => options.UseSqlite(builder.Configuration.GetConnectionString("Default"))); builder.Services.AddIdentityCore<IdentityUser>(options => { options.Lockout.MaxFailedAccessAttempts = 5; options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(5); }) .AddRoles<IdentityRole>() .AddEntityFrameworkStores<AppDbContext>() .AddSignInManager() .AddDefaultTokenProviders(); builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.MapInboundClaims = false; options.TokenValidationParameters = tokenService.CreateValidationParameters(); }); builder.Services.AddMcpServer() .WithHttpTransport() .WithTools<WeatherTool>(); builder.Services.AddAuthorization(options => { options.AddPolicy("mcp", policy => { policy.AddAuthenticationSchemes(JwtBearerDefaults.AuthenticationScheme); policy.RequireAuthenticatedUser(); policy.RequireClaim("scope", "mcp:invoke"); }); }); var app = builder.Build(); using (var scope = app.Services.CreateScope()) { var db = scope.ServiceProvider.GetRequiredService<AppDbContext>(); await db.Database.EnsureCreatedAsync(); } app.UseExceptionHandler(); // Configure the HTTP request pipeline. if (app.Environment.IsDevelopment()) { app.MapOpenApi(); } if (!app.Environment.IsDevelopment()) { app.UseHsts(); app.UseHttpsRedirection(); } app.UseDefaultFiles(); app.UseStaticFiles(); app.UseAuthentication(); app.UseAuthorization(); app.MapMcp("/mcp").RequireAuthorization("mcp"); app.MapControllers(); app.MapGet("/api/auth/me", (System.Security.Claims.ClaimsPrincipal user) => Results.Ok(new { userId = user.FindFirst(JwtRegisteredClaimNames.Sub)?.Value, userName = user.Identity?.Name, email = user.FindFirst(JwtRegisteredClaimNames.Email)?.Value })).RequireAuthorization(); var summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; app.MapGet("/weatherforecast", () => { var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast ( DateOnly.FromDateTime(DateTime.Now.AddDays(index)), Random.Shared.Next(-20, 55), summaries[Random.Shared.Next(summaries.Length)] )) .ToArray(); return forecast; }) .WithName("GetWeatherForecast") .RequireAuthorization(); app.Run(); record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) { public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); }
为什么使用 AddIdentityCore
这个项目采用 JWT,而不是 Identity Cookie 登录。因此使用:AddIdentityCore<IdentityUser>() 再按需添加 Roles、EF Store、SignInManager。这样职责更清晰,也避免无意中混入 Cookie 默认认证方案。
为什么关闭 Claims 映射
options.MapInboundClaims = false;
关闭映射后,JWT 中的 sub、email 等名称保持原样。读取时可以直接使用:user.FindFirst(JwtRegisteredClaimNames.Sub)
另外,通过:NameClaimType = JwtRegisteredClaimNames.UniqueName
让:user.Identity?.Name对应 JWT 中的用户名。
为什么首页允许匿名
登录页面必须能够在未认证时打开。
因此:
app.UseDefaultFiles();
app.UseStaticFiles();
公开的是页面和静态资源。
真正敏感的天气数据和 MCP 工具,仍由服务端授权保护。
九:补上一个能实际操作的页面
先创建静态资源目录:
New-Item -ItemType Directory -Path .\wwwroot -Force
1. 页面结构
创建 wwwroot/index.html:
<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>登录验证 · MCP JWT Demo</title> <link rel="stylesheet" href="/styles.css"> <script src="/app.js" defer></script> </head> <body> <main> <header> <span class="badge">MCP · JWT · Identity</span> <h1>登录验证</h1> <p>登录后访问受保护的天气接口与 MCP 服务。</p> </header> <p id="message" role="status" aria-live="polite">当前尚未认证,请先注册或登录。</p> <section id="auth-panel" aria-label="注册或登录"> <div class="switch"> <button id="login-tab" type="button" aria-pressed="true">登录</button> <button id="register-tab" type="button" aria-pressed="false">注册</button> </div> <form id="auth-form"> <label for="username">用户名</label> <input id="username" name="userName" autocomplete="username" maxlength="256" required> <div id="email-field" hidden> <label for="email">邮箱(可选)</label> <input id="email" name="email" type="email" autocomplete="email" maxlength="256"> </div> <label for="password">密码</label> <input id="password" name="password" type="password" autocomplete="current-password" maxlength="128" required> <p id="password-hint" class="hint" hidden>至少 6 位,包含大写字母、小写字母、数字和符号。</p> <button id="submit-button" class="primary" type="submit">登录</button> </form> </section> <section id="account-panel" aria-label="已登录账户" hidden> <h2>你好,<span id="account-name"></span></h2> <p class="hint">已通过 JWT 验证。访问令牌有效期为 15 分钟。</p> <div class="actions"> <button id="weather-button" class="primary" type="button">获取天气</button> <button id="logout-button" type="button">退出登录</button> </div> <div id="weather-results" hidden> <h3>未来五天天气</h3> <div class="table-wrapper"> <table> <thead><tr><th scope="col">日期</th><th scope="col">温度(℃)</th><th scope="col">描述</th></tr></thead> <tbody id="weather-body"></tbody> </table> </div> </div> </section> <footer>令牌仅保存在当前页面内存中,刷新页面后需重新登录。直接在地址栏打开受保护 API 不会携带 JWT。</footer> </main> </body> </html>
2. 简单样式
创建 wwwroot/styles.css:
:root { color-scheme: light; font-family: system-ui, sans-serif; color: #17243b; background: #f1f5fb; } * { box-sizing: border-box; } body { margin: 0; padding: 48px 20px; } main { max-width: 620px; margin: auto; padding: 36px; background: white; border: 1px solid #dce4f0; border-radius: 20px; box-shadow: 0 12px 40px #1734600d; } h1 { margin: 16px 0 8px; font-size: 32px; } h2 { font-size: 22px; } header p, .hint, footer { color: #5b6b82; line-height: 1.7; } .badge { display: inline-block; padding: 6px 12px; background: #e9f0ff; color: #285fc4; border-radius: 20px; font-size: 12px; font-weight: 600; } #message { padding: 14px 16px; background: #edf4ff; border-radius: 10px; line-height: 1.6; } #message.error { color: #922a29; background: #fff0ef; } .switch, .actions { display: flex; gap: 12px; margin: 24px 0 16px; } .switch button { flex: 1; } button { padding: 12px 18px; border: 1px solid #ccd8e8; border-radius: 9px; background: white; color: inherit; font: inherit; cursor: pointer; } button.primary, .switch button[aria-pressed="true"] { color: white; background: #285fc4; border-color: #285fc4; } button:hover { filter: brightness(.95); } button:disabled { opacity: .6; cursor: wait; } label { display: block; margin: 16px 0 8px; font-weight: 600; } input { width: 100%; padding: 12px; border: 1px solid #ccd8e8; border-radius: 9px; font: inherit; } :focus-visible { outline: 3px solid #87b6ff; outline-offset: 3px; } #submit-button { width: 100%; margin-top: 24px; } .hint { font-size: 13px; } .table-wrapper { overflow-x: auto; } table { width: 100%; border-collapse: collapse; text-align: left; font-size: 14px; } th, td { padding: 12px 8px; border-bottom: 1px solid #e8edf4; white-space: nowrap; } footer { margin-top: 32px; padding-top: 20px; border-top: 1px solid #e8edf4; font-size: 12px; } [hidden] { display: none !important; } @media (max-width: 480px) { body { padding: 20px 12px; } main { padding: 24px 20px; } }
3. 页面交互
创建 wwwroot/app.js:
"use strict"; const element = (id) => document.getElementById(id); let mode = "login"; let tokens = null; class ApiError extends Error { constructor(message, status) { super(message); this.status = status; } } function showMessage(text, isError = false) { element("message").textContent = text; element("message").classList.toggle("error", isError); } function setMode(nextMode) { mode = nextMode; const registering = mode === "register"; element("email-field").hidden = !registering; element("email").disabled = !registering; element("password-hint").hidden = !registering; element("password").autocomplete = registering ? "new-password" : "current-password"; element("password").minLength = registering ? 6 : 1; element("login-tab").setAttribute("aria-pressed", String(!registering)); element("register-tab").setAttribute("aria-pressed", String(registering)); element("submit-button").textContent = registering ? "注册账户" : "登录"; } function clearSession() { tokens = null; element("auth-panel").hidden = false; element("account-panel").hidden = true; element("account-name").textContent = ""; element("weather-body").replaceChildren(); element("weather-results").hidden = true; element("password").value = ""; setMode("login"); } async function api(path, { body, authenticated = false } = {}) { const headers = { Accept: "application/json" }; if (body) headers["Content-Type"] = "application/json"; if (authenticated) { if (!tokens) throw new ApiError("当前尚未认证,请先注册或登录。", 401); headers.Authorization = `Bearer ${tokens.accessToken}`; } let response; try { response = await fetch(path, { method: body ? "POST" : "GET", headers, body: body ? JSON.stringify(body) : undefined, cache: "no-store" }); } catch (error) { throw new Error("无法连接服务,请检查网络或确认服务已启动。", { cause: error }); } const contentType = response.headers.get("Content-Type") ?? ""; const data = response.status !== 204 && (contentType.includes("/json") || contentType.includes("+json")) ? await response.json() : null; if (!response.ok) { const details = Array.isArray(data?.errors) ? data.errors.map((item) => item.description) : Object.values(data?.errors ?? {}).flat(); throw new ApiError( data?.error || details.join(";") || data?.detail || data?.title || `请求失败(HTTP ${response.status})`, response.status ); } return data; } async function perform(action) { const buttons = [...document.querySelectorAll("button")]; buttons.forEach((button) => { button.disabled = true; }); try { await action(); } catch (error) { if (error instanceof ApiError && error.status === 401 && tokens) { clearSession(); showMessage("认证已失效,请重新登录;没有账户可先注册。", true); } else { showMessage(error.message, true); } } finally { buttons.forEach((button) => { button.disabled = false; }); } } element("login-tab").addEventListener("click", () => setMode("login")); element("register-tab").addEventListener("click", () => setMode("register")); element("auth-form").addEventListener("submit", (event) => { event.preventDefault(); const body = { userName: element("username").value.trim(), password: element("password").value }; if (mode === "register") body.email = element("email").value.trim() || null; void perform(async () => { if (mode === "register") { await api("/api/auth/register", { body }); element("password").value = ""; setMode("login"); showMessage("注册成功,请使用刚才的用户名和密码登录。"); element("password").focus(); return; } tokens = await api("/api/auth/login", { body }); const user = await api("/api/auth/me", { authenticated: true }); element("password").value = ""; element("account-name").textContent = user.userName; element("auth-panel").hidden = true; element("account-panel").hidden = false; showMessage("登录成功,已通过身份验证。"); element("weather-button").focus(); }); }); element("weather-button").addEventListener("click", () => { void perform(async () => { const forecast = await api("/weatherforecast", { authenticated: true }); const rows = forecast.map((day) => { const row = document.createElement("tr"); for (const value of [day.date, day.temperatureC, day.summary]) { const cell = document.createElement("td"); cell.textContent = value; row.append(cell); } return row; }); element("weather-body").replaceChildren(...rows); element("weather-results").hidden = false; showMessage("天气数据获取成功,该请求已携带 JWT。"); }); }); element("logout-button").addEventListener("click", () => { void perform(async () => { await api("/api/auth/logout", { body: { refreshToken: tokens.refreshToken } }); clearSession(); showMessage("已退出登录,请先注册或登录后再访问受保护功能。"); element("username").focus(); }); }); setMode("login");
页面为什么不把 Token 放进 localStorage
为了让演示保持简单,令牌只保存在当前页面内存里。
因此:
- 登录成功后,当前页面可以调用 API。
- 刷新页面后,变量被清空,需要重新登录。
- 关闭页面后,不留下持久化令牌。
这并不表示内存存储可以消除 XSS 风险;它只是避免在本示例中引入长期浏览器存储。
页面使用 textContent 输出用户名和天气内容,不把接口返回值拼成 HTML。
为什么处理响应时要判断 Content-Type
JWT 验证失败时,服务端可能只返回一个空的 401,没有 JSON 正文。
如果直接写:await response.json();
页面可能先出现 JSON 解析错误,反而没有显示真正的认证提醒。
这里先判断状态和 Content-Type,再处理错误。
页面没有自动刷新令牌
这是当前项目的明确行为:
- Refresh API 已实现。
- 页面暂不自动调用 Refresh API。
- 页面请求收到
401后,清除当前认证状态并提示重新登录。
如果以后加入自动刷新,需要保证多个请求共享一次刷新操作,否则旧 Refresh Token 的并发使用可能触发重放处理。
十:启动项目,看看实际页面
替换 Properties/launchSettings.json:
{
"$schema": "https://json.schemastore.org/launchsettings.json",
"profiles": {
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": false,
"applicationUrl": "http://localhost:5041",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"https": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": false,
"applicationUrl": "https://localhost:7046;http://localhost:5041",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
构建:dotnet build
启动:dotnet run --launch-profile http
打开:http://localhost:5041/
第一次启动时会自动初始化 SQLite 数据库。
十一: 使用 VS Code MCP Inspector 验证MCP调用
在 VS Code 中使用 MCP Inspector 扩展面板完成配置、连接和工具调用。以下步骤对应本项目实际测试截图。
第一步:配置服务地址与认证头
在 MCP Inspector 中设置:
| 配置项 | 填写内容 |
|---|---|
| Server type | Remote (URL) |
| Server URL | http://localhost:5041/mcp |
| Authentication | Static header / token |
| Headers:名称 | Authorization |
| Headers:值 | Bearer <登录返回的 accessToken> |

注:服务地址指向 /mcp,认证采用静态请求头。Inspector 会在每次请求中发送 Authorization
第二步:连接并确认发现工具
完成配置后点击 Connect。连接成功时,面板显示:Connected · Streamable HTTP · 1 tool

注:Inspector 已连接并发现一个工具。终端同时显示 initialize 和 tools/list 请求处理记录,说明初始化与工具发现已完成。
如果连接失败,可以按状态码定位:
- 401:检查是否填写了 Bearer 前缀、是否误用了 Refresh Token,以及 Access Token 是否过期。重新登录取得新令牌后更新认证头并重连。
- 403:检查当前令牌是否具有 mcp:invoke scope。签名有效不代表拥有工具调用权限。
- 连接被拒绝:检查服务是否启动、端口是否为 5041,以及地址是否包含 /mcp。
第三步:调用 get_weather 并核对结果
在 Available tools 中找到 get_weather,点击旁边的 Run。
在参数窗口中填写 city。本次截图使用 China 作为演示字符串;
这个工具直接返回演示文本,不会检查真实城市名称,也不会查询真实天气。

Inspector 显示工具执行成功。
【完】
当在复杂的环境中面临问题,格物之道需:浊而静之徐清,安以动之徐生。 云中,恰是如此!

浙公网安备 33010602011771号