Teilen über


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:

Dateisystempfad:

%APPDATA%\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();