Gestire i token Web JSON in fase di sviluppo con dotnet user-jwts

Di Rick Anderson

Lo dotnet user-jwts strumento da riga di comando può creare e gestire token WEB JSON locali specifici dell'app.

Riepilogo

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

Descrizione

Crea e gestisce token Web JSON locali specifici del progetto.

Argomenti

PROJECT | SOLUTION

Progetto MSBuild in cui applicare un comando. Se non si specifica un progetto, MSBuild cerca nella directory di lavoro corrente un file con estensione di file che termina in proj e usa tale file.

Comandi

Comando	Descrizione
clear	Eliminare tutti i token JWT rilasciati per un progetto.
create	Rilasciare un nuovo token Web JSON.
remove	Eliminare un token JWT specificato.
key	Visualizzare o reimpostare la chiave di firma usata per emettere token JWT.
list	Elenca i token JWT rilasciati per il progetto.
print	Visualizzare i dettagli di un token JWT specificato.

Creazione

Sintassi: dotnet user-jwts create [options]

Opzione	Descrizione
-p | --progetto	Percorso del progetto su cui operare. Il valore predefinito è il progetto nella directory corrente.
--schema	Nome dello schema da usare per il token generato. L'impostazione predefinita è 'Bearer'.
-n | --nome	Nome dell'utente per cui creare il token JWT. L'impostazione predefinita è l'utente dell'ambiente corrente.
--pubblico	Destinatari per cui creare il token JWT. Per impostazione predefinita, gli URL configurati nel launchSettings.json del progetto.
--Emittente	Autorità di certificazione del token JWT. Il valore predefinito è "dotnet-user-jwts".
--scope	Attestazione di ambito da aggiungere al token JWT. Specificare una volta per ogni ambito.
--ruolo	Attestazione di ruolo da aggiungere al token JWT. Specificare una volta per ogni ruolo.
--richiesta	Attestazioni da aggiungere al token JWT. Specificare una volta per ogni attestazione nel formato "name=value".
--not-before	La data e l'ora UTC del token JWT non devono essere valide prima nel formato 'aa-MM-gg [[HH:mm[[:ss]]]]'. Il valore predefinito è data e ora di creazione del token JWT.
--expires-on	La data UTC e l'ora in cui il token JWT deve scadere nel formato "aaaa-MM-gg [[[ [HH:mm]]:ss]]". Il valore predefinito è 6 mesi dopo la data --not-before. Non usare questa opzione insieme all'opzione --valid-for.
--valid-for	Il periodo in cui il token JWT deve scadere. Specificare l'uso di un numero seguito da un tipo di durata come 'd' per giorni, 'h' per ore, 'm' per minuti e 's' per secondi, ad esempio 365d'. Non usare questa opzione insieme all'opzione --expires-on.
-o | --prodotto	Formato da usare per la visualizzazione dell'output dal comando . Può essere uno dei valori "default", "token" o "json".
-h | --Guida	Mostra le informazioni della Guida

Esempi

Eseguire i comandi seguenti per creare un progetto Web vuoto e aggiungere il pacchetto NuGet Microsoft.AspNetCore.Authentication.JwtBearer :

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

Sostituire il contenuto di Program.cs con il codice seguente:

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

Nel codice precedente, una richiesta GET per /secret restituire un 401 Unauthorized errore. Un'app di produzione potrebbe ottenere il token JWT da un servizio token di sicurezza (STS), forse in risposta all'accesso tramite un set di credenziali. Ai fini dell'uso dell'API durante lo sviluppo locale, lo dotnet user-jwts strumento da riga di comando può essere usato per creare e gestire JWT locali specifici dell'app.

Lo user-jwts strumento è simile al concetto dello strumento user-secrets , che può essere usato per gestire i valori per l'app che sono validi solo per lo sviluppatore nel computer locale. In effetti, lo strumento user-jwts usa l'infrastruttura user-secrets per gestire la chiave con cui i token JWT sono firmati, assicurandosi che sia archiviato in modo sicuro nel profilo utente.

Lo user-jwts strumento nasconde i dettagli di implementazione, ad esempio dove e come vengono archiviati i valori. Lo strumento può essere usato senza conoscere i dettagli di implementazione. I valori vengono archiviati in un file JSON nella cartella del profilo utente del computer locale:

Windows

Percorso del file system:

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

Linux/macOS

Percorso del file system:

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

Creare un token JWT

Il comando seguente crea un token JWT locale:

dotnet user-jwts create

Il comando precedente crea un token JWT e aggiorna il file del appsettings.Development.json progetto con JSON simile al seguente:

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

Copiare il token JWT e l'oggetto ID creato nel comando precedente. Usare uno strumento come Curl per testare /secret:

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

Dove {token} è il token JWT generato in precedenza.

Visualizzare le informazioni di sicurezza JWT

Il comando seguente visualizza le informazioni di sicurezza JWT, tra cui scadenza, ambiti, ruoli, intestazione del token e payload e il token compatto:

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

Creare un token per un utente e un ambito specifici

Per le opzioni di creazione supportate, vedere Creare in questo argomento.

Il comando seguente crea un token JWT per un utente denominato MyTestUser:

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

L'output del comando precedente è simile al seguente:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Il token precedente può essere usato per testare l'endpoint /secret2 nel codice seguente:

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