dotnet user-jwts ile geliştirme aşamasında JSON Web Belirteçlerini yönetme

Yazan Rick Anderson

Komut dotnet user-jwts satırı aracı, uygulamaya özgü yerel JSON Web Belirteçleri (JWT) oluşturabilir ve yönetebilir.

Bu makalede, komut ve örnekler için söz dizimi ayrıntıları sağlanır.

Özet

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

Açıklama

Projeye özgü yerel JSON Web Belirteçleri oluşturur ve yönetir.

Argümanlar

PROJECT | SOLUTION

Komutun uygulanacağı MSBuild projesi. Bir proje belirtilmezse, MSBuild geçerli çalışma dizininde proj ile biten dosya uzantısına sahip bir dosya arar. Ardından bu dosyayı kullanarak komutun proje bilgilerini alır.

Komutlar

Komut Açıklama
clear Bir proje için verilen tüm JWT'leri silin.
create Yeni bir JSON Web Belirteci gönderin.
remove Belirli JWTbir öğesini silin.
key JWT'leri vermek için kullanılan imzalama anahtarını görüntüleyin veya sıfırlayın.
list Proje için verilen JWT'leri listeleyin.
print Belirli JWTbir öğesinin ayrıntılarını görüntüleyin.

Create komutu için seçenekler

Kullanım: dotnet user-jwts create [options]

Seçenek Açıklama
-p \| --project Üzerinde çalışacak projenin yolu. Varsayılan olarak geçerli dizindeki projeyi seçer.
--scheme Oluşturulan belirteç için kullanılacak şema adı. Varsayılan olarak Bearer değerini alır.
-n \| --name JWT oluşturulacak kullanıcının adı. Varsayılan olarak geçerli ortam kullanıcısını kullanır.
--audience JWT oluşturulacağı hedef kitleler. Projenin launchSettings.json dosyasında yapılandırılan URL'leri varsayılan olarak kullanır.
--issuer ihraççısıdır JWT. Varsayılan olarak dotnet-user-jwts değerini alır.
--scope JWT öğesine eklenecek bir kapsam talebi. Her kapsam için bir kez belirtin.
--role JWT öğesine eklenecek bir rol talebi. Her rol için bir kez belirtin.
--claim JWT öğesine eklenecek talepler Her talep için name=value biçiminde bir kez belirtin.
--not-before yyyy-MM-dd [[HH:mm[[:ss]]]] öğesinin geçerli olduğu UTC tarih ve saat, JWT biçiminde. JWT varsayılanı, oluşturulduğu tarih ve saattir.
--expires-on JWT öğesinin sona erdiği UTC tarih ve saati, yyyy-MM-dd [[[ [HH:mm]]:ss]] biçiminde. Varsayılan olarak, --not-before tarihinden altı ay sonrasıdır. Bu seçeneği --valid-for seçeneğiyle kullanmayın.
--valid-for JWT geçerlilik süresi. Süreye ulaşıldığında JWT süresi dolar. Bir sayıyı ve ardından süre türünü (d gün, saat, hm dakika, s saniye) (gibi 365d) belirtin. Bu seçeneği --expires-on seçeneğiyle kullanmayın.
-o \| --output Komutundan çıktı görüntülemek için kullanılacak biçim: default, tokenveya json.
-h \| --help Komutun yardım bilgilerini gösterin.

Dosya tabanlı uygulamalarla kullanın

dotnet user-jwts, --file seçeneği aracılığıyla dosya tabanlı uygulamalarla çalışır. .csUygulamanın C# dosyasını (--file) gösterin.

Aşağıdaki örnekte uygulama, app.cs adlı, proje dosyası olmayan bir dosyadır ve komut, uygulamanın kök dizininden bir komut kabuğunda yürütülür:

dotnet user-jwts create --file app.cs

--file seçeneği, --project seçeneğinde olduğu gibi, her user-jwts komutu için geçerlidir (create, clear, key, list, print ve remove). --file veya --project belirtilmediğinde, araç geçerli dizinde bir MSBuild projesi arar.

Kurallar:

  • --file parametresine geçirilen yol, .cs dosya uzantısına sahip bir C# dosyası olmalıdır.
  • --file ve --project seçenekleri birlikte kullanılamaz.

Örnekler

Boş bir web projesi oluşturmak ve Microsoft.AspNetCore.Authentication.JwtBearer NuGet paketini eklemek için aşağıdaki komutları çalıştırın:

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

Program.cs dosyasının içeriğini aşağıdaki kodla değiştirin:

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

Yukarıdaki kodda, uç noktaya yönelik /secret bir GET isteği bir 401 Unauthorized hata döndürür. Bir üretim uygulaması, kimlik bilgileriyle oturum açmaya yanıt olarak JWT alabilir. Api'yi yerel geliştirme sırasında kullandığınızda, dotnet user-jwts uygulamaya özgü yerel JWT'ler oluşturmak ve yönetmek için komut satırı aracı kullanılabilir.

user-jwts aracı, kavramsal olarak user-secrets aracına benzer. Uygulamanın yalnızca yerel makinedeki geliştirici için geçerli olan değerlerini yönetmek için kullanılabilir. Aslında, user-jwts aracı JWT'lerin imzalanmasında kullanılan anahtarı yönetmek için user-secrets altyapısından yararlanır. Bu yaklaşım anahtarın kullanıcı profilinde güvenli bir şekilde depolanmasını sağlar.

Araç user-jwts , değerlerin nerede ve nasıl depolandığı gibi uygulama ayrıntılarını gizler. Araç, uygulama ayrıntıları bilinmeden kullanılabilir.

Değerler yerel makinenin kullanıcı profili klasöründeki bir JSON dosyasında depolanır:

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

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

Bir JWT oluştur

Aşağıdaki komut yerel bir JWT oluşturur:

dotnet user-jwts create

Yukarıdaki komut bir JWT oluşturur ve proje appsettings.Development.json dosyasını aşağıdaki örneğe benzer JSON ile güncelleştirir:

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

JWT ve önceki komutta oluşturulan ID öğesini kopyalayın. JWT uç noktayı test etmek için Curl gibi bir araç kullanın; burada {token}, daha önce oluşturulan /secret’dir:

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

Görüntüle JWT güvenlik bilgilerini

Aşağıdaki komut, süre sonu, kapsamlar, roller, belirteç üst bilgisi ve yükü ile kompakt belirteç dahil olmak üzere JWT güvenlik bilgilerini görüntüler:

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

Belirli bir kullanıcı ve kapsam için belirteç oluşturma

Aşağıdaki komut, JWT adlı bir kullanıcı için bir MyTestUser oluşturur. Desteklenen create seçenekler için komut oluşturma seçenekleri bölümüne bakın.

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

Yukarıdaki komutun çıktısı aşağıdaki örneğe benzer:

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

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.{Remaining token deleted}

Yukarıdaki belirteç, aşağıdaki kodda /secret2 uç noktasını test etmek için kullanılabilir:

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

İlgili içerik

  • Son güncelleştirme: