Zarządzać tokenami JWT w środowisku deweloperskim za pomocą narzędzia 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.

Ten artykuł zawiera szczegółowe informacje o składni polecenia i przykłady.

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, do którego ma zostać zastosowane 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ę na pliku proj. Następnie używa tego pliku, aby uzyskać informacje o projekcie dla tego polecenia.

Polecenia

Polecenie opis
clear Usuń wszystkie wystawione JWTs dla projektu.
create Wydaj nowy token internetowy JSON.
remove Usuń dane JWT.
key Wyświetl lub zresetuj klucz podpisywania używany do wystawiania JWTs.
list Wyświetl listę tokenów JWT wydanych dla projektu.
print Wyświetl szczegóły danego JWTobiektu .

Opcje polecenia create

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

Opcja opis
-p \| --project Ścieżka projektu, na którym ma zostać wykonana operacja. Domyślnie projekt jest w bieżącym katalogu.
--scheme Nazwa schematu do użycia dla wygenerowanego tokenu. Wartość domyślna to Bearer.
-n \| --name Nazwa użytkownika, dla którego ma zostać utworzony element JWT. Wartością domyślną jest aktualny użytkownik środowiska.
--audience Odbiorcy, dla których należy utworzyć JWT. Domyślnie używa adresów URL skonfigurowanych w pliku launchSettings.json projektu.
--issuer Wystawca JWT. Wartość domyślna to dotnet-user-jwts.
--scope Roszczenie zakresu do dodania do elementu JWT. Określ to raz dla każdego zakresu.
--role Claim roli, który ma zostać dodany do JWT. Określ raz dla każdej roli.
--claim Roszczenia do dodania do elementu JWT. Określ jeden raz dla każdego roszczenia w formacie name=value.
--not-before Data i godzina UTC, o której wartość JWT staje się prawidłowa, w formacie yyyy-MM-dd [[HH:mm[[:ss]]]]. Domyślnie ustawiana jest data i godzina utworzenia JWT.
--expires-on Data i godzina UTC, o której JWT wygasa, w formacie yyyy-MM-dd [[[ [HH:mm]]:ss]]. Domyślnie jest ustawiona na sześć miesięcy po dacie --not-before. Nie używaj tej opcji z opcją --valid-for .
--valid-for Czas, przez jaki JWT pozostaje ważny. Po osiągnięciu tego czasu JWT wygasa. Określ liczbę, po której następuje typ czasu trwania (d dni, h godziny, m minuty, s sekundy), na przykład 365d. Nie używaj tej opcji z opcją --expires-on .
-o \| --output Format używany do wyświetlania danych wyjściowych z polecenia : default, tokenlub json.
-h \| --help Wyświetla informacje pomocy dla polecenia.

Do użycia z aplikacjami opartymi na plikach

Program dotnet user-jwts współpracuje z aplikacjami opartymi na plikach za pośrednictwem opcji --file. Wskaż --file plik C# aplikacji (.cs).

W poniższym przykładzie aplikacja jest plikiem o nazwie app.cs bez pliku projektu, a polecenie jest wykonywane w powłoce poleceń z katalogu głównego aplikacji:

dotnet user-jwts create --file app.cs

Opcja --file ma zastosowanie do każdego polecenia user-jwts (create, clear, list, key, print, i remove), tak samo jak opcja --project. Jeśli ani --file, ani --project nie zostaną określone, narzędzie przeszukuje bieżący katalog w poszukiwaniu projektu MSBuild.

Zasady:

  • Ścieżka przekazana do --file musi być plikiem C# z .cs rozszerzeniem pliku.
  • Opcje --file i --project nie mogą być używane razem.

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ść pliku 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 przykładzie kodu żądanie GET do punktu końcowego /secret zwraca błąd 401 Unauthorized. Aplikacja produkcyjna może pobrać JWT z usługi tokenów zabezpieczeń, być może w odpowiedzi na zalogowanie się przy użyciu poświadczeń. Gdy używasz interfejsu API podczas lokalnego programowania, narzędzie wiersza poleceń dotnet user-jwts może służyć do tworzenia lokalnych tokenów JWT przeznaczonych dla danej aplikacji i zarządzania nimi.

Narzędzie user-jwts jest podobne do narzędzia user-secrets . Może służyć do zarządzania wartościami aplikacji, które są prawidłowe tylko dla dewelopera na komputerze lokalnym. W istocie narzędzie user-jwts wykorzystuje infrastrukturę user-secrets do zarządzania kluczem używanym do podpisywania tokenów JWT. Takie podejście zapewnia bezpieczne przechowywanie klucza 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: %APPDATA%\Microsoft\UserSecrets<secrets_GUID>\user-jwts.json

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

Utwórz JWT

Następujące polecenie tworzy lokalny JWT:

dotnet user-jwts create

Poprzednie polecenie tworzy element JWT i aktualizuje plik projektu appsettings.Development.json przy użyciu kodu JSON podobnego do przedstawionego w poniższym przykładzie:

{
  "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 element JWT i ID utworzone w poprzednim poleceniu. Użyj narzędzia, takiego jak Curl, aby przetestować /secret punkt końcowy, gdzie {token} jest wcześniej wygenerowany JWT:

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

Wyświetl JWT informacje o zabezpieczeniach

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

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

Tworzenie tokenu dla określonego użytkownika i zakresu

Następujące polecenie tworzy JWT dla użytkownika o nazwie MyTestUser. Aby zapoznać się z obsługiwanymi create opcjami, zobacz sekcję Opcje dla polecenia create .

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

Powyższe polecenie zawiera dane wyjściowe podobne do następującego przykładu:

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

Treści powiązane

  • Ostatnia aktualizacja o