Minimum API'lerde kimlik doğrulaması ve yetkilendirme

En düşük API'ler ASP.NET Core'da sağlanan tüm kimlik doğrulama ve yetkilendirme seçeneklerini destekler ve kimlik doğrulamasıyla çalışma deneyimini geliştirmek için bazı ek işlevler sağlar.

Kimlik doğrulaması ve yetkilendirmedeki temel kavramlar

Kimlik doğrulaması, kullanıcının değerini belirleme işlemidir identity. Yetkilendirme, bir kullanıcının bir kaynağa erişip erişemeyeceğini belirleme işlemidir. Hem kimlik doğrulama hem de yetkilendirme senaryoları ASP.NET Core'da benzer uygulama semantiğini paylaşır. Kimlik doğrulaması, kimlik doğrulama ara yazılımı tarafından kullanılan IAuthenticationService kimlik doğrulama hizmeti tarafından işlenir. Yetkilendirme, yetkilendirme ara yazılımı tarafından kullanılan IAuthorizationService yetkilendirme hizmeti tarafından işlenir.

Kimlik doğrulaması hizmeti, kimlik doğrulamasıyla ilgili eylemleri tamamlamak için kayıtlı kimlik doğrulaması işleyicilerini kullanır. Örneğin, kimlik doğrulamasıyla ilgili bir eylem kullanıcının kimliğini doğrulamak veya bir kullanıcıyı oturumu kapatma işlemidir. Kimlik doğrulama düzenleri, kimlik doğrulama işleyicisini ve yapılandırma seçeneklerini benzersiz olarak tanımlamak için kullanılan adlardır. Kimlik doğrulama işleyicileri, kimlik doğrulaması stratejilerini uygulamak ve OAuth veya OIDC gibi belirli bir kimlik doğrulama stratejisine bağlı olarak kullanıcının taleplerini oluşturmakla sorumludur. Yapılandırma seçenekleri de stratejiye özeldir ve işleyiciye yeniden yönlendirme URI'leri gibi kimlik doğrulama davranışını etkileyen yapılandırmayı sağlar.

Yetkilendirme katmanındaki kaynaklara kullanıcı erişimini belirlemek için iki strateji vardır:

• Rol tabanlı stratejiler, kullanıcının erişimini, veya Usergibi Administrator atandıkları role göre belirler. Rol tabanlı yetkilendirme hakkında daha fazla bilgi için rol tabanlı yetkilendirme belgelerine bakın.
• Talep tabanlı stratejiler, merkezi bir yetkili tarafından verilen taleplere göre kullanıcının erişimini belirler. Talep tabanlı yetkilendirme hakkında daha fazla bilgi için talep tabanlı yetkilendirme belgelerine bakın.

ASP.NET Core'da her iki strateji de bir yetkilendirme gereksinimine yakalanır. Yetkilendirme hizmeti, belirli bir kullanıcının kaynağa uygulanan yetkilendirme gereksinimlerini karşılayıp karşılamadığını belirlemek için yetkilendirme işleyicilerinden yararlanır.

Minimum uygulamalarda kimlik doğrulamasını etkinleştirme

Kimlik doğrulamasını etkinleştirmek için, uygulamanın hizmet sağlayıcısına gerekli kimlik doğrulama hizmetlerini kaydetme çağrısında AddAuthentication bulunur.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Genellikle belirli bir kimlik doğrulama stratejisi kullanılır. Aşağıdaki örnekte, uygulama JWT taşıyıcı tabanlı kimlik doğrulaması desteğiyle yapılandırılır. Bu örnek, API'lerin NuGet paketinde Microsoft.AspNetCore.Authentication.JwtBearer kullanılmasını sağlar.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Varsayılan olarak, WebApplication belirli kimlik doğrulama ve yetkilendirme hizmetleri etkinse kimlik doğrulama ve yetkilendirme ara yazılımlarını otomatik olarak kaydeder. Aşağıdaki örnekte ara yazılımların çağrılması UseAuthentication veya UseAuthorization kaydedilmesi gerekmez çünkü WebApplication bu işlem otomatik olarak sonra AddAuthentication yapılır veya AddAuthorization çağrılır.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Ara yazılım sırasını denetleme gibi bazı durumlarda kimlik doğrulaması ve yetkilendirmeyi açıkça kaydetmek gerekir. Aşağıdaki örnekte, kimlik doğrulama ara yazılımı CORS ara yazılımı çalıştırıldıktan sonra çalıştırılır. Ara yazılım ve bu otomatik davranış hakkında daha fazla bilgi için bkz . Minimal API uygulamalarında ara yazılım.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Kimlik doğrulama stratejisini yapılandırma

Kimlik doğrulama stratejileri genellikle seçenekler aracılığıyla yüklenen çeşitli yapılandırmaları destekler. En az uygulama, aşağıdaki kimlik doğrulama stratejileri için yapılandırmadan yükleme seçeneklerini destekler:

• JWT taşıyıcı tabanlı
• OpenID Bağlantı Tabanlı

ASP.NET Core çerçevesi, yapılandırma bölümündeki Authentication:Schemes:{SchemeName} bu seçenekleri bulmayı bekler. Aşağıdaki örnekte, iki farklı düzen Bearer ve LocalAuthIssuer, ilgili seçenekleriyle tanımlanır. seçeneği Authentication:DefaultScheme , kullanılan varsayılan kimlik doğrulama stratejisini yapılandırmak için kullanılabilir.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

içinde Program.cs, aşağıdakilerle birlikte iki JWT taşıyıcı tabanlı kimlik doğrulama stratejisi kaydedilir:

• "Taşıyıcı" düzen adı.
• "LocalAuthIssuer" düzeni adı.

"Taşıyıcı", JWT taşıyıcı tabanlı etkin uygulamalarda tipik varsayılan düzendir, ancak önceki örnekte olduğu gibi özelliği ayarlanarak DefaultScheme varsayılan düzen geçersiz kılınabilir.

Düzen adı, bir kimlik doğrulama stratejisini benzersiz olarak tanımlamak için kullanılır ve aşağıdaki örnekte gösterildiği gibi yapılandırmadan kimlik doğrulama seçenekleri çözümlendiğinde arama anahtarı olarak kullanılır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Minimum uygulamalarda yetkilendirme ilkelerini yapılandırma

Kimlik doğrulaması, bir API'ye karşı kullanıcıların kimliğini belirlemek ve doğrulamak identity için kullanılır. Yetkilendirme, API'deki kaynaklara erişimi doğrulamak ve doğrulamak için kullanılır ve uzantı yöntemi tarafından kaydedilen tarafından IAuthorizationService AddAuthorization kolaylaştırılır. Aşağıdaki senaryoda, bir /hello kullanıcının kapsam talebiyle rol talebi sununu gerektiren bir admin greetings_api kaynak eklenir.

Bir kaynakta yetkilendirme gereksinimlerini yapılandırmak, şunları gerektiren iki adımlı bir işlemdir:

1. İlkedeki yetkilendirme gereksinimlerini genel olarak yapılandırma.
2. Kaynaklara tek tek ilkeler uygulama.

Aşağıdaki kodda şu AddAuthorizationBuilder kod çağrılır:

• DI kapsayıcısına yetkilendirmeyle ilgili hizmetler ekler.
• Yetkilendirme ilkelerini doğrudan kaydetmek için kullanılabilecek bir AuthorizationBuilder döndürür.

Kod, iki yetkilendirme gereksinimini kapsayan adlı admin_greetingsyeni bir yetkilendirme ilkesi oluşturur:

• aracılığıyla rolü olan kullanıcılar için rol tabanlı bir admin gereksinimRequireRole.
• Kullanıcının bir kapsam talebi sağlaması gerektiği yoluyla RequireClaim talep tabanlı bir greetings_api gereksinim.

İlke admin_greetings , uç noktaya gerekli bir ilke /hello olarak sağlanır.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Geliştirme testi için kullanma dotnet user-jwts

Bu makale boyunca JWT taşıyıcı tabanlı kimlik doğrulaması ile yapılandırılan bir uygulama kullanılır. JWT taşıyıcı tabanlı kimlik doğrulaması, istemcilerin ve taleplerini doğrulamak için istek üst bilgisinde bir belirteç sunmalarını identity gerektirir. Bu belirteçler genellikle sunucu gibi identity merkezi bir yetkili tarafından verilir.

Yerel makinede geliştirme yaparken araç taşıyıcı dotnet user-jwts belirteçleri oluşturmak için kullanılabilir.

dotnet user-jwts create

Belirteçler çeşitli özelleştirmelerle yapılandırılabilir. Örneğin, önceki kodda admin yetkilendirme ilkesi tarafından beklenen rol ve greetings_api kapsam için bir belirteç oluşturmak için:

dotnet user-jwts create --scope "greetings_api" --role "admin"

Oluşturulan belirteç daha sonra tercih edilen test aracında üst bilginin bir parçası olarak gönderilebilir. Örneğin, curl ile:

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

Araç hakkında dotnet user-jwts daha fazla bilgi için tüm belgeleri okuyun.