【Azure Developer】.NET 10搭建登录认证示例(Identity + JWT + Refresh Token)

本文是一个动手示例,跟随一步一步,可以把项目真正跑起来。

从创建项目开始,实现注册、登录、JWT 验证、Refresh Token 轮换、MCP 鉴权,最后补上一个能实际操作的中文页面。

最终效果:一张动态图看完整流程

auth-flow

动态图:未认证首页 → 注册表单 → 注册成功 → 登录成功 → 获取天气 → 退出登录。

本文将要完成的示例,是一条真正闭环的认证链路:

注册账户
   ↓
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

image

这会生成一个随机的 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 的唯一索引有两个用途:

  1. 避免重复记录。
  2. 加快按令牌哈希查找记录的速度。

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; }  // 被谁替换,重放检测用
}

这里有四个关键点:

  1. 配置错误要在启动时暴露。密钥缺失、不是 Base64、长度不足,都直接报出明确错误,而不是等用户登录时才返回 500。
  2. 签发和验证使用同一个服务配置。避免登录签发时使用一个 Issuer,验证时又使用另一个。
  3. 限制签名算法。这里明确只接受:SecurityAlgorithms.HmacSha256
  4. 保留一分钟时钟容差。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>

image

注:服务地址指向 /mcp,认证采用静态请求头。Inspector 会在每次请求中发送 Authorization

 

第二步:连接并确认发现工具

完成配置后点击 Connect。连接成功时,面板显示:Connected · Streamable HTTP · 1 tool

image

注: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 作为演示字符串;

这个工具直接返回演示文本,不会检查真实城市名称,也不会查询真实天气。

image

Inspector 显示工具执行成功。

 

 

 

 

【完】

posted @ 2026-11-20 21:09  编码者卢布  阅读(14)  评论(0)    收藏  举报