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 |
格式为 yyyy-MM-dd [[[ [HH:mm]]:ss]] 的 JWT 过期时的 UTC 日期和时间。 默认为 --not-before 日期后的六个月。 不要将此选项与 --valid-for 选项一起使用。 |
--valid-for |
JWT 保持有效的时间量。 到达该时间后,JWT 将过期。 指定一个数字,后跟持续时间类型(d天、小时、 hm分钟、s秒),例如365d。 不要将此选项与 --expires-on 选项一起使用。 |
-o \| --output |
用于显示命令输出的格式: default、 token或 json。 |
-h \| --help |
显示命令的帮助信息。 |
与基于文件的应用一起使用
dotnet user-jwts通过--file选项与基于文件的应用配合使用。 将 --file 指向应用的 C# 文件(.cs)。
在以下示例中,应用程序是一个名为 app.cs 的文件,没有项目文件,并且该命令从应用程序的根目录在命令 shell 中执行:
dotnet user-jwts create --file app.cs
该--file选项适用于每个user-jwts命令(create、clear、key、list、print和remove),与 --project 选项的作用方式相同。 如果既未指定 --file 也未指定 --project,工具将在当前目录中搜索 MSBuild 项目。
规则:
- 传递给
--file的路径必须是文件扩展名为.cs的 C# 文件。 -
--project和--file选项不能一起使用。
示例
运行以下命令来创建一个空的 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 基础结构来存储位于 Authentication:Schemes:Bearer:SigningKeys 下的对称签名机密(没有公钥)。 在开发环境中,默认主机配置使用户机密可供 AddJwtBearer() 用于签名验证。 此方法可确保密钥安全地存储在用户配置文件中。
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
为特定用户和范围创建令牌
以下命令为名为 的用户创建一个 。 有关支持 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();