Verwalten von JSON-Webtoken in der Entwicklung mit dotnet-user-jwts

Von Rick Anderson

Das dotnet user-jwts Befehlszeilentool kann App-spezifische lokale JSON-Webtoken (JWTs) erstellen und verwalten.

Übersicht

dotnet user-jwts [<PROJECT>] [command]
dotnet user-jwts [command] -h|--help

Beschreibung

Erstellt und verwaltet projektspezifische lokale JSON-Webtoken.

Argumente

PROJECT | SOLUTION

Das MSBuild-Projekt, auf das ein Befehl angewendet werden soll. Wenn Sie kein Projekt angeben, durchsucht MSBuild das aktuelle Arbeitsverzeichnis nach einer Dateierweiterung, die mit proj endet, und verwendet diese Datei.

Befehle

Command	Beschreibung
clear	Löscht alle ausgestellten JWTs für ein Projekt.
create	Stellt ein neues JSON-Webtoken aus.
remove	Löscht ein angegebenes JWT.
Schlüssel	Zeigt den zum Ausstellen von JWTs verwendeten Signaturschlüssels an oder setzt ihn zurück.
list	Listet die für das Projekt ausgestellten JWTs auf.
print	Zeigt die Details eines angegebenen JWT an.

Erstellen

Syntax: dotnet user-jwts create [options]

Option	Beschreibung
-p | --project	Der Pfad des Projekts, das bearbeitet werden soll. Ist standardmäßig auf das Projekt im aktuellen Verzeichnis festgelegt.
--scheme	Der Schemaname, der für das generierte Token verwendet werden soll. Der Standardwert ist „Bearer“.
-n | --name	Der Name des Benutzers, für den das JWT erstellt werden soll. Standardmäßig wird der aktuelle Umgebungsbenutzer verwendet.
--audience	Die Zielgruppen, für die das JWT erstellt werden soll. Standardmäßig werden die URLs verwendet, die in launchSettings.json des Projekts konfiguriert sind.
--issuer	Der Aussteller des JWT. Der Standardwert ist „dotnet-user-jwts“.
--scope	Ein Bereichsanspruch, der dem JWT hinzugefügt werden soll. Ist einmal für jeden Bereich anzugeben.
--role	Ein Rollenanspruch, der dem JWT hinzugefügt werden soll. Ist einmal für jede Rolle anzugeben.
--claim	Ansprüche, die dem JWT hinzugefügt werden sollen. Ist einmal für jeden Anspruch im Format „name=value“ anzugeben.
--not-before	Das UTC-Datum und die UTC-Uhrzeit, vor dem bzw. der das JWT nicht gültig sein soll, im Format „yyyy-MM-dd [[HH:mm[[:ss]]]]“. Standardmäßig werden das Datum und die Uhrzeit verwendet, zu dem das JWT erstellt wird.
--expires-on	Das UTC-Datum und die UTC-Uhrzeit, an dem bzw. der das JWT ablaufen soll, im Format „yyyy-MM-dd [[[ [HH:mm]]:ss]]“. Der Standardwert ist 6 Monate nach dem „--not-before“-Datum. Verwenden Sie diese Option nicht in Verbindung mit der Option „--valid-for“.
--valid-for	Der Zeitraum, nach dem das JWT abläuft. Geben Sie eine Zahl gefolgt vom Typ der Dauer („d“ für Tage, „h“ für Stunden, „m“ für Minuten und „s“ für Sekunden) an, z. B. 365d. Verwenden Sie diese Option nicht in Verbindung mit der Option „--expires-on“.
-o | --output	Das Format, das zum Anzeigen der Ausgabe des Befehls verwendet werden soll. Dies kann „default“, „token“ oder „json“ sein.
-h | --help	Anzeigen von Hilfeinformationen

Beispiele

Führen Sie die folgenden Befehle aus, um ein leeres Webprojekt zu erstellen und das NuGet-Paket Microsoft.AspNetCore.Authentication.JwtBearer hinzuzufügen:

dotnet new web -o MyJWT
cd MyJWT
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Ersetzen Sie den Inhalt von Program.cs durch den folgenden Code.

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();

Im vorherigen Code gibt eine GET-Anforderung an /secret einen 401 Unauthorized-Fehler zurück. Eine Produktions-App kann das JWT von einem Sicherheitstokendienst (STS) abrufen, z. B. als Reaktion auf die Anmeldung über einen Satz von Anmeldeinformationen. Zum Arbeiten mit der API während der lokalen Entwicklung kann das Befehlszeilentool dotnet user-jwts verwendet werden, um appspezifische lokale JWTs zu erstellen und zu verwalten.

Das Tool user-jwts ähnelt dem Tool user-secrets. Es kann verwendet werden, um Werte für die App zu verwalten, die nur für den Entwickler auf dem lokalen Computer gültig sind. Tatsächlich verwendet das Tool „user-jwts“ die Infrastruktur von user-secrets, um den Schlüssel zu verwalten, mit dem die JWTs signiert sind, und stellt sicher, dass er sicher im Benutzerprofil gespeichert wird.

Das user-jwts Tool blendet Implementierungsdetails aus, z. B. wo und wie die Werte gespeichert werden. Das Tool kann verwendet werden, ohne die Implementierungsdetails zu kennen. Die Werte werden in einer JSON-Datei im Benutzerprofilordner des lokalen Computers gespeichert:

Windows

Dateisystempfad:

%APPDATA%\Microsoft\UserSecrets\<secrets_GUID>\user-jwts.json

Linux/macOS

Dateisystempfad:

~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json

Erstellen eines JWT

Der folgende Befehl erstellt ein lokales JWT:

dotnet user-jwts create

Der vorherige Befehl erstellt ein JWT und aktualisiert die appsettings.Development.json-Datei des Projekts mit JSON, ähnlich wie im Folgenden:

{
  "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"
      }
    }
  }
}

Kopieren Sie das JWT und die im vorherigen Befehl erstellte ID. Verwenden Sie ein Tool wie Curl, um /secret zu testen:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/secret

Wobei {token} das zuvor generierte JWT ist.

Anzeigen von JWT-Sicherheitsinformationen

Mit dem folgenden Befehl werden die JWT-Sicherheitsinformationen angezeigt, einschließlich Ablauf, Bereiche, Rollen, Tokenheader und Nutzdaten sowie das Kompakttoken:

dotnet user-jwts print {ID} --show-all

Erstellen eines Tokens für einen bestimmten Benutzer und Bereich

Unterstützte Erstellungsoptionen finden Sie unter Create in diesem Thema.

Der folgende Befehl erstellt ein JWT für einen Benutzer namens MyTestUser:

dotnet user-jwts create --name MyTestUser --scope "myapi:secrets"

Mit dem obigen Befehl wird eine ähnliche Ausgabe wie die folgende angezeigt:

New JWT saved with ID '43e0b748'.
Name: MyTestUser
Scopes: myapi:secrets

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Das vorangehende Token kann verwendet werden, um den /secret2-Endpunkt im folgenden Code zu testen:

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();