本文是一个动手示例,跟随一步一步,可以把项目真正跑起来。
从创建项目开始,实现注册、登录、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. 配置文件不要保存签名密钥
替换 appsettings.json文件
{
"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 映射
csharpoptions.MapInboundClaims = false;
关闭映射后,JWT 中的 sub、email 等名称保持原样。读取时可以直接使用:user.FindFirst(JwtRegisteredClaimNames.Sub)
另外,通过:NameClaimType = JwtRegisteredClaimNames.UniqueName
让:user.Identity?.Name对应 JWT 中的用户名。
为什么首页允许匿名
登录页面必须能够在未认证时打开。
因此:
csharpapp.UseDefaultFiles(); app.UseStaticFiles();
公开的是页面和静态资源。
真正敏感的天气数据和 MCP 工具,仍由服务端授权保护。
九:补上一个能实际操作的页面
先创建静态资源目录:
powershellNew-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"
}
}
}
}
构建:
powershelldotnet build
启动:
powershelldotnet run --launch-profile http
打开:
texthttp://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 显示工具执行成功。
【完】
text