Zarządzanie tokenami internetowymi JSON podczas programowania przy użyciu interfejsu dotnet user-jwts

Autor: Rick Anderson

dotnet user-jwts Narzędzie wiersza polecenia może tworzyć lokalne tokeny internetowe JSON (JWTs) specyficzne dla aplikacji i zarządzać nimi.

Streszczenie

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

opis

Tworzy lokalne tokeny internetowe JSON specyficzne dla projektu i zarządza nimi.

Argumenty

PROJECT | SOLUTION

Projekt MSBuild, aby zastosować polecenie. Jeśli projekt nie zostanie określony, program MSBuild przeszukuje bieżący katalog roboczy dla pliku, który ma rozszerzenie pliku, które kończy się w pliku proj i używa tego pliku.

Polecenia

Polecenie	opis
czyścić	Usuń wszystkie wystawione JWTs dla projektu.
utworzyć	Wydaj nowy token internetowy JSON.
usuń	Usuń daną JWT.
klucz	Wyświetl lub zresetuj klucz podpisywania używany do wystawiania JWTs.
lista	Wyświetla listę zestawów JWTs wystawionych dla projektu.
drukować	Wyświetl szczegóły danego zestawu JWT.

Utworzenie

Użycie: dotnet user-jwts create [options]

Opcja	opis
-p | --projekt	Ścieżka projektu do działania. Domyślnie projekt jest w bieżącym katalogu.
--plan	Nazwa schematu do użycia dla wygenerowanego tokenu. Wartość domyślna to "Bearer".
-n | --nazwa	Nazwa użytkownika do utworzenia zestawu JWT. Domyślnie jest to bieżący użytkownik środowiska.
--audiencja	Odbiorcy, dla których chcesz utworzyć zestaw JWT. Domyślnie adresy URL skonfigurowane w launchSettings.json projektu.
--Emitenta	Wystawca JWT. Wartość domyślna to "dotnet-user-jwts".
--zakres	Oświadczenie zakresu do dodania do zestawu JWT. Określ raz dla każdego zakresu.
--rola	Oświadczenie roli, które ma zostać dodane do zestawu JWT. Określ raz dla każdej roli.
--roszczenie	Oświadczenia do dodania do zestawu JWT. Określ raz dla każdego oświadczenia w formacie "name=value".
--not-before	Data i godzina UTC, przed jaką JWT nie powinny być prawidłowe w formacie "rrrr-MM-dd [[HH:mm[[:ss]]]]". Domyślnie jest tworzona data i godzina utworzenia JWT.
--expires-on	Data i godzina UTC, o których JWT powinny wygasnąć w formacie "rrrr-MM-dd [[[ [HH:mm]]:ss]]". Wartość domyślna to 6 miesięcy po dacie --not-before. Nie używaj tej opcji w połączeniu z opcją --valid-for.
--valid-for	Okres, po upływie których JWT powinien wygasnąć. Określ użycie liczby, po której następuje typ czasu trwania, taki jak "d" dla dni, "h" dla godzin, "m" przez minuty i "s" w sekundach, na przykład 365d. Nie używaj tej opcji w połączeniu z opcją --expires-on.
-o | --wyjście	Format używany do wyświetlania danych wyjściowych z polecenia . Może być jednym z wartości "default", "token" lub "json".
-h | --Pomoc	Pokaż informacje pomocy

Przykłady

Uruchom następujące polecenia, aby utworzyć pusty projekt internetowy i dodać pakiet NuGet Microsoft.AspNetCore.Authentication.JwtBearer :

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

Zastąp zawartość Program.cs następującym kodem:

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

W poprzednim kodzie żądanie /secret GET zwraca 401 Unauthorized błąd. Aplikacja produkcyjna może pobrać JWT z usługi tokenu zabezpieczającego (STS), być może w odpowiedzi na zalogowanie się za pośrednictwem zestawu poświadczeń. Na potrzeby pracy z interfejsem API podczas programowania dotnet user-jwts lokalnego narzędzie wiersza polecenia może służyć do tworzenia lokalnych zestawów JWTs specyficznych dla aplikacji i zarządzania nimi.

Narzędzie jest podobne do user-jwts. Można go użyć do zarządzania wartościami aplikacji, które są prawidłowe tylko dla dewelopera na komputerze lokalnym. W rzeczywistości narzędzie user-jwts korzysta z user-secrets infrastruktury do zarządzania kluczem podpisanym przez JWTs, upewniając się, że jest on bezpiecznie przechowywany w profilu użytkownika.

Narzędzie user-jwts ukrywa szczegóły implementacji, takie jak miejsce i sposób przechowywania wartości. Narzędzie może być używane bez znajomości szczegółów implementacji. Wartości są przechowywane w pliku JSON w folderze profilu użytkownika komputera lokalnego:

Windows

Ścieżka systemu plików:

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

Linux/macOS

Ścieżka systemu plików:

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

Tworzenie zestawu JWT

Następujące polecenie tworzy lokalny zestaw JWT:

dotnet user-jwts create

Poprzednie polecenie tworzy plik JWT i aktualizuje plik projektu appsettings.Development.json przy użyciu formatu JSON podobny do następującego:

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

Skopiuj JWT i ID utworzony w poprzednim poleceniu. Użyj narzędzia, takiego jak Curl, aby przetestować /secretprogram :

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

Gdzie {token} jest wcześniej wygenerowany zestaw JWT.

Wyświetlanie informacji o zabezpieczeniach JWT

Następujące polecenie wyświetla informacje o zabezpieczeniach JWT, w tym wygasanie, zakresy, role, nagłówek tokenu i ładunek oraz kompaktowy token:

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

Tworzenie tokenu dla określonego użytkownika i zakresu

Aby uzyskać informacje o obsługiwanych opcjach tworzenia, zobacz Tworzenie w tym temacie.

Następujące polecenie tworzy JWT dla użytkownika o nazwie MyTestUser:

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

Powyższe polecenie zawiera dane wyjściowe podobne do następujących:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Powyższy token może służyć do testowania punktu końcowego /secret2 w następującym kodzie:

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