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 JWToggetto .
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 JWToggetto .

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 l'oggetto JWT . L'impostazione predefinita è l'utente dell'ambiente corrente.
--audience Destinatari per cui creare l'oggetto JWT . Per impostazione predefinita, usa gli URL configurati nel file launchSettings.json del progetto.
--issuer Autorità emittente dell'oggetto JWT. Di default è dotnet-user-jwts.
--scope Attestazione di ambito da aggiungere all'oggetto JWT. Specificare una sola volta per ogni ambito.
--role Attestazione di ruolo da aggiungere all'oggetto JWT. Specifica una sola volta per ogni ruolo.
--claim Attestazioni da aggiungere all'oggetto 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 Quantità di tempo che rimane JWT valida. Quando viene raggiunto il tempo, l'oggetto 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.

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 da JWT 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.js> in

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

Crea un JWT

Il comando seguente crea un oggetto locale JWT:

dotnet user-jwts create

Il comando precedente crea e JWT 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 e l'oggetto JWTID creato nel comando precedente. Usare uno strumento come Curl per testare l'endpoint /secret , dove {token} è quello generato JWTin 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 oggetto 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

  • Last updated on