dotnet user-jwts 命令行工具可以创建和管理特定于应用的本地 JSON Web 令牌 (JWT)。
本文提供命令和示例的语法详细信息。
摘要
dotnet user-jwts [<PROJECT>] [command]
dotnet user-jwts [command] -h|--help
说明
创建和管理特定于项目的本地 JSON Web 令牌。
参数
PROJECT | SOLUTION
要对其应用命令的 MSBuild 项目。 如果未指定项目，MSBuild 将在当前工作目录中搜索具有 以 proj 结尾的文件扩展名的文件。 然后，它使用该文件获取命令的项目信息。
命令
| 命令 | 说明 |
|---|---|
clear |
删除为项目颁发的所有 JWT。 |
create |
颁发新的 JSON Web 令牌。 |
remove |
删除给定的 JWT。 |
key |
显示或重置用于颁发 JWT 的签名密钥。 |
list |
列出为项目颁发的 JWT。 |
print |
显示给定 JWT 的详细信息。 |
create 命令的选项
用法：dotnet user-jwts create [options]
| 选项 | 说明 |
|---|---|
-p \| --project |
要操作的项目路径。 默认为当前目录中的项目。 |
--scheme |
用于生成令牌的方案名称。 默认值为 Bearer. |
-n \| --name |
要为其创建 JWT 的用户的名称。 默认为当前环境用户。 |
--audience |
用于创建 JWT 的受众。 默认为项目 launchSettings.json 文件中配置的 URL。 |
--issuer |
JWT 的颁发者。 默认值为 dotnet-user-jwts. |
--scope |
要添加到 JWT 的范围声明。 为每个范围指定一次。 |
--role |
要添加到 JWT 中的角色声明。 为每个角色指定一次。 |
--claim |
添加到 JWT 中的声明。 请为每项声明各指定一次，并采用 name=value 格式。 |
--not-before |
JWT 生效的 UTC 日期和时间，格式 yyyy-MM-dd [[HH:mm[[:ss]]]]为 。 默认为创建 JWT 的日期和时间。 |
--expires-on |
JWT 到期时的 UTC 日期和时间，格式为 yyyy-MM-dd [[[ [HH:mm]]:ss]]。 默认为 --not-before 日期后的六个月。 不要将此选项与 --valid-for 选项一起使用。 |
--valid-for |
JWT 的有效时长。 到达该时间点时，JWT 将过期。 指定一个数字，后跟持续时间类型（d天、小时、 hm分钟、s秒），例如365d。 不要将此选项与 --expires-on 选项一起使用。 |
-o \| --output |
用于显示命令输出的格式： default、 token或 json。 |
-h \| --help |
显示命令的帮助信息。 |
示例
运行以下命令来创建一个空的 Web 项目，并添加 Microsoft.AspNetCore.Authentication.JwtBearer NuGet 包：
dotnet new web -o MyJWT
cd MyJWT
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
将 Program.cs 文件的内容替换为以下代码：
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
app.UseAuthorization();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.Run();
在前面的代码中，对 /secret 终结点的 GET 请求将返回错误 401 Unauthorized 。 生产应用可能会从 安全令牌服务获取 JWT，以响应使用凭据登录。 在本地开发期间使用 API 时， dotnet user-jwts 命令行工具可用于创建和管理特定于应用的本地 JWT。
该工具 user-jwts 的概念类似于 用户机密 工具。 它可用于管理仅对本地计算机上的开发人员有效的应用的值。 事实上，该工具 user-jwts 利用 user-secrets 基础结构来管理 JWT 签名的密钥。 此方法可确保密钥安全地存储在用户配置文件中。
user-jwts 工具会隐藏实现详细信息，例如值的存储位置和存储方法。 可在不知道实现详细信息的情况下使用该工具。
这些值存储在本地计算机的用户配置文件文件夹中的 JSON 文件中：
Windows：%APPDATA%\Microsoft\UserSecrets<secrets_GUID>\user-jwts.json
Linux/macOS： ~/.microsoft/usersecrets/<secrets_GUID/user-jwts.json>
创建 JWT
以下命令会创建一个本地 JWT：
dotnet user-jwts create
上述命令创建 JWT，并使用类似于以下示例的 JSON 更新项目 appsettings.Development.json 文件：
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"Authentication": {
"Schemes": {
"Bearer": {
"ValidAudiences": [
"http://localhost:8401",
"https://localhost:44308",
"http://localhost:5182",
"https://localhost:7076"
],
"ValidIssuer": "dotnet-user-jwts"
}
}
}
}
复制 JWT 和在前一个命令中创建的 ID。 使用 Curl 等工具测试 /secret 端点，其中 {token} 是之前生成的 JWT：
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/secret
显示 JWT 安全信息
以下命令会显示 JWT 安全信息，包括过期时间、作用域、角色、令牌头部和载荷，以及紧凑令牌：
dotnet user-jwts print {ID} --show-all
为特定用户和范围创建令牌
以下命令为名为 MyTestUser 的用户创建 JWT。 有关支持 create 的选项，请参阅 “创建命令”部分的选项 。
dotnet user-jwts create --name MyTestUser --scope "myapi:secrets"
上述命令的输出类似于以下示例：
New JWT saved with ID '43e0b748'.
Name: MyTestUser
Scopes: myapi:secrets
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}
上述令牌可用于在以下代码中测试 /secret2 终结点：
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.MapGet("/secret2", () => "This is a different secret!")
.RequireAuthorization(p => p.RequireClaim("scope", "myapi:secrets"));
app.Run();
