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 JSON Web Token (JWT) locali specifici dell'applicazione.

Questo articolo fornisce informazioni dettagliate sulla sintassi per il comando e gli esempi.

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 viene specificato un progetto, MSBuild cerca nella directory di lavoro corrente un file con estensione di file che termina in proj. Usa quindi il file per ottenere le informazioni sul progetto per il comando .

Comandi

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

Opzioni per il comando create

Utilizzo: dotnet user-jwts create [options]

Opzione Descrizione
-p \| --project Il percorso del progetto su cui operare. Usa come valore predefinito il progetto nella cartella corrente.
--scheme Nome dello schema da usare per il token generato. Di default è Bearer.
-n \| --name Nome dell'utente per cui creare il JWT. L'impostazione predefinita è l'utente dell'ambiente corrente.
--audience Destinatari per cui creare il JWT. Per impostazione predefinita, usa gli URL configurati nel file launchSettings.json del progetto.
--issuer L'emittente del JWT. Di default è dotnet-user-jwts.
--scope Un claim di ambito da aggiungere a JWT. Specificare una sola volta per ogni ambito.
--role Attestazione di ruolo da aggiungere a JWT. Specifica una sola volta per ogni ruolo.
--claim Richieste di rimborso da aggiungere a JWT. Specificarlo una volta per ciascuna affermazione nel formato name=value.
--not-before Data e ora UTC in cui l'oggetto JWT diventa valido, nel formato yyyy-MM-dd [[HH:mm[[:ss]]]]. Il valore predefinito è la data e l'ora di creazione dell'oggetto JWT .
--expires-on Data e ora UTC in cui JWT scade, nel formato yyyy-MM-dd [[[ [HH:mm]]:ss]]. Il valore predefinito è impostato a sei mesi dopo la data --not-before. Non usare questa opzione con l'opzione --valid-for.
--valid-for Periodo di tempo durante il quale JWT rimane valido. Allo scadere del tempo, JWT scade. Specificare un numero seguito dal tipo di durata (d giorni, h ore, m minuti, s secondi), ad esempio 365d. Non usare questa opzione con l'opzione --expires-on.
-o \| --output Formato da usare per la visualizzazione dell'output dal comando : default, tokeno json.
-h \| --help Mostra le informazioni di aiuto per il comando.

Usare con app basate su file

dotnet user-jwts funziona con le app basate su file tramite l'opzione --file . Puntare --file al file C# dell'app (.cs).

Nell'esempio seguente l'app è un file denominato app.cs senza un file di progetto e il comando viene eseguito in una shell dei comandi dalla directory radice dell'app:

dotnet user-jwts create --file app.cs

L'opzione --file si applica a ogni comando user-jwts (create, clear, listkey, print, e remove), allo stesso modo dell'opzione --project. Quando non viene specificato né --file né --project, lo strumento cerca nella directory corrente un progetto MSBuild.

Norme:

  • Il percorso passato a --file deve essere un file C# con l'estensione .cs.
  • Le opzioni --file e --project non possono essere usate insieme.

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 del file 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 all'endpoint /secret restituisce un 401 Unauthorized errore. Un'app di produzione potrebbe ottenere il JWT da un servizio token di sicurezza, ad esempio in risposta all'accesso con le credenziali. Quando si usa l'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 è concettualmente simile allo strumento user-secrets. 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 utilizza l'infrastruttura user-secrets per gestire la chiave con la quale vengono firmati i JWT. Questo approccio garantisce che la chiave venga archiviata 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: %APPDATA%\Microsoft\UserSecrets<secrets_GUID>\user-jwts.json

  • Linux/macOS: ~/.microsoft/usersecrets/<secrets_GUID>/user-jwts.json

Crea un JWT

Il comando seguente crea un locale JWT:

dotnet user-jwts create

Il comando precedente crea una JWT e aggiorna il file di progetto appsettings.Development.json con JSON simile all'esempio 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 JWT e il ID creati nel comando precedente. Usare uno strumento come Curl per testare l'endpoint /secret, dove {token} è il JWT generato in precedenza:

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

Visualizzare JWT le informazioni di sicurezza

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

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

Creare un token per un utente e un ambito specifici

Il comando seguente crea un JWT per un utente denominato MyTestUser. Per le opzioni supportate create , vedere la sezione Opzioni per la creazione del comando .

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

L'output del comando precedente è simile all'esempio 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();

Contenuti correlati

  • Ultimo aggiornamento: