使用 dotnet user-jwts 管理開發中的 JSON Web 權杖
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 的簽署金鑰。 |
| 清單 | 列出針對專案發出的 JWT。 |
| 顯示指定 JWT 的詳細資料。 |
建立
使用方式：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 | UTC 日期和時間 JWT 在格式 'yyyy-MM-dd [[HH:mm[[:ss]]]]' 之前無效。 預設為建立 JWT 的日期和時間。 |
| --expires-on | UTC 日期和時間 JWT 的格式應以 'yyyy-MM-dd [[[ [HH:mm]]:ss]]' 格式過期。 預設為 --not-before 日期之後 6 個月。 請勿將此選項與 --valid-for 選項搭配使用。 |
| --valid-for | JWT 應該在之後到期的期間。 使用數字後面跟著持續時間類型來指定，例如「d」表示天、「h」表示小時、「m」表示分鐘及「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 錯誤。 生產應用程式可能會從安全性權杖服務 (STS) 取得 JWT，以回應透過一組認證登入。 為了在本機開發期間使用 API，dotnet user-jwts 命令列工具可用來建立和管理應用程式特定的本機 JWT。
user-jwts 工具與使用者密碼工具的概念類似，它可用來管理只對本機電腦上開發人員有效的應用程式值。 事實上，user-jwts 工具會利用 user-secrets 基礎結構來管理 JWT 所簽署的金鑰，確保其安全地儲存在使用者設定檔中。
user-jwts 工具會隱藏實作詳細資料，例如儲存值的位置和方式。 不需要知道實作詳細資料，就可以使用此工具。 這些值會儲存在本機電腦使用者設定檔資料夾中的 JSON 檔案中：
檔案系統路徑：
%APPDATA%\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：
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/secret
其中 {token} 是先前產生的 JWT。
顯示 JWT 安全性資訊
下列命令會顯示 JWT 安全性資訊，包括到期日、範圍、角色、權杖標頭和承載，以及精簡權杖：
dotnet user-jwts print {ID} --show-all
建立特定使用者和範圍的權杖
如需支援的建立選項，請參閱本主題中的建立。
下列命令會為名為 MyTestUser 的使用者建立 JWT：
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();
