使用 dotnet user-jwts 管理開發中的 JSON Web 權杖

  • 發行項

作者：Rick Anderson

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。
print 顯示指定 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 JWT 在格式 'yyyy-MM-dd [[HH：mm[[：ss]]]]' 之前，JWT 的 UTC 日期和時間不應該有效。 預設為建立 JWT 的日期和時間。
--expires-on JWT 應該以 'yyyy-MM-dd [[[ [HH：mm]]：ss]]] 格式到期的 UTC 日期和時間。 預設為 --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();