JSON Web Tokens beheren tijdens de ontwikkeling met dotnet user-jwts

Door Rick Anderson

Het dotnet user-jwts opdrachtregelprogramma kan app-specifieke lokale JSON-webtokens (JWT's) maken en beheren.

Samenvatting

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

Description

Hiermee maakt en beheert u projectspecifieke lokale JSON-webtokens.

Arguments

PROJECT | SOLUTION

Het MSBuild-project waarop een opdracht moet worden toegepast. Als een project niet is opgegeven, zoekt MSBuild in de huidige werkmap naar een bestand met een bestandsextensie die eindigt op proj en dat bestand gebruikt.

Commands

Command	Description
duidelijk	Verwijder alle uitgegeven JWT's voor een project.
create	Geef een nieuw JSON-webtoken op.
remove	Een bepaalde JWT verwijderen.
key	De ondertekeningssleutel weergeven of opnieuw instellen die wordt gebruikt om JWT's uit te geven.
list	Geeft een lijst weer van de JWT's die zijn uitgegeven voor het project.
print	De details van een bepaalde JWT weergeven.

Create

Gebruik: dotnet user-jwts create [options]

Optie	Description
-p | --project	Het pad van het project waarop gewerkt moet worden. Wordt standaard ingesteld op het project in de huidige map.
--schema	De schemanaam die moet worden gebruikt voor het gegenereerde token. Standaard ingesteld op Bearer.
-n | --naam	De naam van de gebruiker waarvoor de JWT moet worden gemaakt. Standaard ingesteld op de huidige omgevingsgebruiker.
--doelgroep	De doelgroepen waarvoor de JWT moet worden gemaakt. Standaard ingesteld op de URL's die zijn geconfigureerd in de launchSettings.jsonvan het project.
--Uitgevende instelling	De uitgever van de JWT. De standaardwaarde is 'dotnet-user-jwts'.
--draagwijdte	Een bereikclaim die moet worden toegevoegd aan de JWT. Specificeer eenmalig voor elke scope.
--rol	Een rolclaim die moet worden toegevoegd aan de JWT. Geef één keer op voor elke rol.
--aanspraak maken op	Claims die moeten worden toegevoegd aan de JWT. Geef voor elke claim één keer aan met de notatie "name=value".
--niet-voor	De UTC-datum en -tijd mag de JWT niet geldig zijn voordat de notatie jjjj-MM-dd [[UU:mm[[:ss]]]] heeft. Standaard ingesteld op de datum en tijd waarop de JWT wordt gemaakt.
--verloopt-op	De UTC-datum en -tijd waarop de JWT zou moeten verlopen in het formaat 'jjjj-MM-dd [[[ [HH:mm]]:ss]]'. De standaardwaarde is 6 maanden na de datum --not-before. Gebruik deze optie niet in combinatie met de optie --valid-for.
--geldig voor	De periode waarna de JWT zal verlopen. Geef een getal op gevolgd door het duurtype 'd' voor dagen, 'h' voor uren, 'm' voor minuten en 's' voor seconden, bijvoorbeeld 365d. Gebruik deze optie niet in combinatie met de optie --expires-on.
-o | --uitvoer	De indeling die moet worden gebruikt voor het weergeven van uitvoer van de opdracht. Dit kan een van de 'standaard', 'token' of 'json' zijn.
-h | --Help	Help-informatie weergeven

Voorbeelden

Voer de volgende opdrachten uit om een leeg webproject te maken en voeg het NuGet-pakket Microsoft.AspNetCore.Authentication.JwtBearer toe:

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

Vervang de inhoud van Program.cs met de volgende 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();

In de voorgaande code resulteert een GET-aanvraag naar /secret in een 401 Unauthorized fout. Een productie-app kan de JWT ophalen van een beveiligingstokenservice (STS), mogelijk als reactie op aanmelden via een set referenties. Voor het werken met de API tijdens lokale ontwikkeling kan het dotnet user-jwts opdrachtregelprogramma worden gebruikt om app-specifieke lokale JWT's te maken en te beheren.

Het hulpprogramma is vergelijkbaar met het hulpprogramma user-jwts. Het kan worden gebruikt om waarden te beheren voor de app die alleen geldig zijn voor de ontwikkelaar op de lokale computer. In feite maakt het hulpprogramma user-jwts gebruik van de infrastructuur voor het user-secrets beheren van de sleutel waarmee de JWT's zijn ondertekend, zodat deze veilig wordt opgeslagen in het gebruikersprofiel.

Het user-jwts hulpprogramma verbergt implementatiedetails, zoals waar en hoe de waarden worden opgeslagen. Het hulpprogramma kan worden gebruikt zonder de implementatiedetails te kennen. De waarden worden opgeslagen in een JSON-bestand in de gebruikersprofielmap van de lokale computer:

Windows

Bestandssysteempad:

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

Linux/macOS

Bestandssysteempad:

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

Een JWT maken

Met de volgende opdracht maakt u een lokale JWT:

dotnet user-jwts create

Met de voorgaande opdracht maakt u een JWT en werkt u het bestand van appsettings.Development.json het project bij met JSON, vergelijkbaar met het volgende:

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

Kopieer de JWT en de ID die in de voorgaande opdracht is gemaakt. Gebruik een hulpprogramma zoals Curl om het volgende te testen /secret:

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

Waar {token} is de eerder gegenereerde JWT.

JWT-beveiligingsgegevens weergeven

Met de volgende opdracht worden de JWT-beveiligingsgegevens weergegeven, waaronder de vervaldatum, scopes, rollen, tokenheader en payload, en het compacte token.

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

Een token maken voor een specifieke gebruiker en een specifiek bereik

Zie Maken in dit onderwerp voor ondersteunde opties voor maken.

Met de volgende opdracht maakt u een JWT voor een gebruiker met de naam MyTestUser:

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

De voorgaande opdracht heeft uitvoer die vergelijkbaar is met de volgende:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Het voorgaande token kan worden gebruikt om het /secret2 eindpunt in de volgende code te 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();